GitHub Connector

Verbinde deine GitHub-Repositories über Tajo mit Brevo für Developer-Engagement-Tracking, Release-Benachrichtigungs-Workflows und Community-Aktivitätsmonitoring.

Überblick

Funktionen

• Issue- und PR-Tracking - Synchronisiere Issue- und Pull-Request-Events in Brevo-Kontaktverläufe
• Release-Benachrichtigungen - Löse Brevo-Kampagnen bei neuen Repository-Releases aus
• Contributor-Synchronisierung - Ordne GitHub-Contributor:innen Brevo-Kontakten zu, um Community-Engagement zu fördern
• Star- und Fork-Tracking - Überwache Popularitätsmetriken von Repositories
• Webhook-Event-Weiterleitung - Leite GitHub-Events an Brevo-Automatisierungen weiter
• Repository-Katalog - Synchronisiere Repository-Metadaten als Brevo-Katalogeinträge

Voraussetzungen

Bevor du beginnst, stelle sicher, dass du Folgendes hast:

1. Ein GitHub-Konto mit Zugriff auf die Ziel-Repositories
2. Eine GitHub-App oder ein Personal Access Token (Fine-Grained empfohlen)
3. Admin-Zugriff auf Repositories für die Webhook-Konfiguration
4. Ein Brevo-Konto mit API-Zugriff
5. Ein Tajo-Konto mit aktivem Abonnement

Authentifizierung

GitHub unterstützt mehrere Authentifizierungsmethoden. Tajo empfiehlt die Verwendung von GitHub Apps für Zugriff auf Organisationsebene.

Option 1: GitHub-App (Empfohlen)

1. Navigiere zu Settings > Developer settings > GitHub Apps
2. Klicke auf New GitHub App
3. Konfiguriere die App mit diesen Berechtigungen:

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

Option 2: Fine-Grained Personal Access Token

1. Gehe zu Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Klicke auf Generate new token
3. Wähle die Ziel-Repositories aus
4. Gewähre diese Berechtigungen:

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

Verbindung zu Tajo herstellen

# 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

Konfiguration

Grundeinrichtung

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

Feldzuordnung

Ordne GitHub-Nutzer:innen-Daten Brevo-Kontaktattributen zu:

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

API-Endpunkte

Tajo integriert die folgenden Endpunkte der GitHub REST API:

Code-Beispiele

Connector initialisieren

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
});

Contributor:innen mit Brevo synchronisieren

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-Events verarbeiten

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');
});

Release-Kampagne auslösen

// 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
    }
  });
});

Ratenbegrenzungen

GitHub erzwingt Ratenbegrenzungen je nach Authentifizierungsmethode:

Weitere Begrenzungen:

• Sekundäre Ratenbegrenzungen: Maximal 100 gleichzeitige Anfragen. Maximal 900 Punkte pro Minute für REST-API-Endpunkte.
• GraphQL: 5.000 Punkte pro Stunde (Abfragekosten variieren je nach Komplexität).

Fehlerbehebung

Häufige Probleme

Debug-Modus

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

Verbindung testen

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

Best Practices

1. GitHub Apps statt PATs verwenden - GitHub Apps bieten granulare Berechtigungen und automatisch erneuerte Tokens
2. Webhook-Secrets aktivieren - Verifiziere Webhook-Signaturen stets mit HMAC-SHA256
3. Conditional Requests nutzen - Verwende ETags, um Rate-Limit-Kontingente zu schonen
4. Große Antworten paginieren - GitHub liefert maximal 100 Einträge pro Seite; iteriere über Link-Header
5. Vollständige Syncs zu Niedriglastzeiten planen - Führe Full-Syncs außerhalb der Hauptentwicklungszeiten aus
6. Rate-Limit-Header überwachen - Prüfe X-RateLimit-Remaining, um proaktiv zu drosseln

Sicherheit

• GitHub-App-Authentifizierung - RSA-Key-basierte JWTs mit kurzlebigen Installationstokens
• Webhook-Signaturen - HMAC-SHA256-Signaturprüfung für alle Webhook-Payloads
• Fine-Grained Tokens - Auf bestimmte Repositories und Berechtigungen beschränkt
• Nur HTTPS - Die gesamte API-Kommunikation ist per TLS 1.2+ verschlüsselt
• Verschlüsselte Speicherung - Private Keys und Tokens werden in Tajo verschlüsselt gespeichert
• Token-Ablauf - Fine-Grained-Tokens laufen automatisch ab; richte Rotationsalarme ein

Verwandte Ressourcen

• Jira Connector
• Linear Connector
• Notion Connector
• Brevo Contacts API