Σύνδεσμος GitHub

Συνδέστε τα αποθετήριά σας GitHub με το Brevo για παρακολούθηση δέσμευσης developer, ροές εργασίας ειδοποίησης κυκλοφορίας και παρακολούθηση κοινοτικής δραστηριότητας μέσω Tajo.

Επισκόπηση

Χαρακτηριστικά

• Παρακολούθηση ζητημάτων και PR - Συγχρονισμός εκδηλώσεων ζητημάτων και pull request στα χρονοδιαγράμματα επαφών Brevo
• Ειδοποιήσεις κυκλοφορίας - Ενεργοποίηση καμπανιών Brevo σε νέες κυκλοφορίες αποθετηρίου
• Συγχρονισμός συνεισφερόντων - Αντιστοίχιση συνεισφερόντων GitHub σε επαφές Brevo για κοινοτική δέσμευση
• Παρακολούθηση αστεριών και forks - Παρακολούθηση μετρήσεων δημοτικότητας αποθετηρίου
• Προώθηση εκδηλώσεων webhook - Προώθηση εκδηλώσεων GitHub σε αυτοματισμούς Brevo
• Κατάλογος αποθετηρίου - Συγχρονισμός metadata αποθετηρίου ως στοιχεία καταλόγου Brevo

Προαπαιτούμενα

Πριν ξεκινήσετε, βεβαιωθείτε ότι διαθέτετε:

1. Λογαριασμό GitHub με πρόσβαση στα στοχευόμενα αποθετήρια
2. GitHub App ή Personal Access Token (συνιστάται λεπτομερής)
3. Πρόσβαση διαχειριστή στα αποθετήρια για ρύθμιση webhook
4. Λογαριασμό Brevo με πρόσβαση API
5. Λογαριασμό Tajo με ενεργή συνδρομή

Πιστοποίηση

Το GitHub υποστηρίζει πολλαπλές μεθόδους πιστοποίησης. Το Tajo συνιστά τη χρήση GitHub Apps για πρόσβαση σε επίπεδο οργανισμού.

Επιλογή 1: GitHub App (Συνιστάται)

1. Μεταβείτε στο Settings > Developer settings > GitHub Apps
2. Κάντε κλικ στο New GitHub App
3. Ρυθμίστε την εφαρμογή με αυτά τα δικαιώματα:

Repository permissions:
  Issues: Read
  Pull requests: Read
  Contents: Read
  Metadata: Read

Organization permissions:
  Members: Read

Subscribe to events:
  Issues
  Pull request
  Push
  Release
  Star
  Fork

Επιλογή 2: Λεπτομερής Personal Access Token

1. Μεταβείτε στο Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Κάντε κλικ στο Generate new token
3. Επιλέξτε στοχευόμενα αποθετήρια
4. Παραχωρήστε αυτά τα δικαιώματα:

Repository access: Selected repositories
Permissions:
  Issues: Read-only
  Pull requests: Read-only
  Contents: Read-only
  Metadata: Read-only

Σύνδεση με Tajo

# Using GitHub App
tajo connectors install github \
  --app-id $GITHUB_APP_ID \
  --private-key-path ./github-app-key.pem \
  --installation-id $GITHUB_INSTALLATION_ID

# Using Personal Access Token
tajo connectors install github \
  --token $GITHUB_TOKEN

Διαμόρφωση

Βασική Ρύθμιση

connectors:
  github:
    enabled: true
    auth_type: "github_app"  # or "token"

    repositories:
      - owner/repo-1
      - owner/repo-2

    sync:
      issues: true
      pull_requests: true
      releases: true
      contributors: true
      stars: true

    lists:
      contributors: 20
      stargazers: 21

Αντιστοίχιση Πεδίων

Αντιστοιχίστε δεδομένα χρήστη GitHub σε χαρακτηριστικά επαφών Brevo:

field_mapping:
  # Standard fields
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # Developer metrics
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # Custom attributes
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

Endpoints API

Το Tajo ενσωματώνεται με τα παρακάτω endpoints REST API GitHub:

Παραδείγματα Κώδικα

Αρχικοποίηση Συνδέσμου

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('github', {
  appId: process.env.GITHUB_APP_ID,
  privateKey: process.env.GITHUB_PRIVATE_KEY,
  installationId: process.env.GITHUB_INSTALLATION_ID
});

Συγχρονισμός Συνεισφερόντων στο Brevo

await tajo.connectors.sync('github', {
  type: 'full',
  resources: ['contributors'],
  repositories: ['owner/repo-1', 'owner/repo-2']
});

const status = await tajo.connectors.status('github');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T11:00:00Z',
//   contributorsCount: 245,
//   issuesTracked: 1890,
//   releasesTracked: 34
// }

Χειρισμός Εκδηλώσεων Webhook

app.post('/webhooks/github', async (req, res) => {
  const signature = req.get('X-Hub-Signature-256');
  const event = req.get('X-GitHub-Event');

  // Verify webhook signature
  if (!verifyGitHubSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('github', {
    event,
    payload: req.body
  });

  res.status(200).send('OK');
});

Ενεργοποίηση Καμπάνιας Κυκλοφορίας

// Listen for new releases and trigger Brevo campaign
tajo.connectors.on('github', 'release.published', async (event) => {
  await tajo.campaigns.trigger('release-announcement', {
    listId: 21,
    params: {
      version: event.release.tag_name,
      release_notes: event.release.body,
      download_url: event.release.html_url
    }
  });
});

Όρια Ρυθμού

Το GitHub επιβάλλει όρια ρυθμού βάσει μεθόδου πιστοποίησης:

Πρόσθετα όρια:

• Δευτερεύοντα όρια ρυθμού: Όχι περισσότερα από 100 ταυτόχρονα αιτήματα. Όχι περισσότεροι από 900 πόντοι ανά λεπτό για endpoints REST API.
• GraphQL: 5.000 πόντοι ανά ώρα (το κόστος ερωτήματος ποικίλλει ανάλογα με την πολυπλοκότητα).

Αντιμετώπιση Προβλημάτων

Συνηθισμένα Προβλήματα

Λειτουργία Εντοπισμού Σφαλμάτων

connectors:
  github:
    debug: true
    log_level: verbose
    log_webhooks: true

Δοκιμή Σύνδεσης

tajo connectors test github
# ✓ API authentication successful
# ✓ Repository access verified
# ✓ Issue data readable
# ✓ Webhook delivery active
# ✓ Rate limit healthy (4,850/5,000 remaining)

Βέλτιστες Πρακτικές

1. Χρησιμοποιήστε GitHub Apps αντί PATs - Τα GitHub Apps παρέχουν λεπτομερή δικαιώματα και αυτόματα ανανεούμενα tokens
2. Ενεργοποιήστε secrets webhook - Επαληθεύετε πάντα υπογραφές webhook με HMAC-SHA256
3. Χρησιμοποιήστε υπό όρους αιτήματα - Αξιοποιήστε ETags για αποφυγή σπατάλης ποσόστωσης ορίου ρυθμού
4. Σελιδοποίηση μεγάλων αποκρίσεων - Το GitHub επιστρέφει μέγ. 100 στοιχεία ανά σελίδα· επαναλάβετε με headers Link
5. Συγχρονίστε σε ώρες χαμηλής δραστηριότητας - Προγραμματίστε πλήρεις συγχρονισμούς εκτός ωρών αιχμής ανάπτυξης
6. Παρακολουθήστε headers ορίου ρυθμού - Ελέγξτε X-RateLimit-Remaining για προληπτική δυνατότητα ρύθμισης

Ασφάλεια

• Πιστοποίηση GitHub App - JWT βάσει κλειδιού RSA με βραχύβια tokens εγκατάστασης
• Υπογραφές Webhook - Επαλήθευση υπογραφής HMAC-SHA256 σε όλα τα payloads webhook
• Λεπτομερή Tokens - Περιορισμένα σε συγκεκριμένα αποθετήρια και δικαιώματα
• Μόνο HTTPS - Όλη η επικοινωνία API κρυπτογραφημένη μέσω TLS 1.2+
• Κρυπτογραφημένη Αποθήκευση - Ιδιωτικά κλειδιά και tokens κρυπτογραφημένα σε ηρεμία στο Tajo
• Λήξη Token - Τα λεπτομερή tokens λήγουν αυτόματα· ρυθμίστε ειδοποιήσεις εναλλαγής

Σχετικοί Πόροι

• Σύνδεσμος Jira
• Σύνδεσμος Linear
• Σύνδεσμος Notion
• API Επαφών Brevo