GitHub-connector

Verbind je GitHub-repositories met Brevo voor developer-engagementtracking, release-notificatieworkflows en monitoring van community-activiteit via Tajo.

Overzicht

Functies

• Issue- en PR-tracking - Synchroniseer issue- en pull request-events naar Brevo-contacttimelines
• Release-notificaties - Trigger Brevo-campagnes bij nieuwe repository-releases
• Contributor-sync - Map GitHub-contributors naar Brevo-contacten voor community-engagement
• Star- en fork-tracking - Monitor populariteitsstatistieken van repositories
• Webhook event forwarding - Stuur GitHub-events door naar Brevo-automatiseringen
• Repositorycatalogus - Synchroniseer repository-metadata als Brevo-catalogusitems

Vereisten

Voordat je begint, zorg dat je beschikt over:

1. Een GitHub-account met toegang tot de doel-repositories
2. Een GitHub App of Personal Access Token (fine-grained aanbevolen)
3. Admin-toegang tot repositories voor webhook-configuratie
4. Een Brevo-account met API-toegang
5. Een Tajo-account met een actief abonnement

Authenticatie

GitHub ondersteunt meerdere authenticatiemethoden. Tajo beveelt GitHub Apps aan voor toegang op organisatieniveau.

Optie 1: GitHub App (aanbevolen)

1. Navigeer naar Settings > Developer settings > GitHub Apps
2. Klik op New GitHub App
3. Configureer de app met deze permissies:

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

Optie 2: Fine-Grained Personal Access Token

1. Ga naar Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Klik op Generate new token
3. Selecteer de doel-repositories
4. Geef deze permissies:

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

Verbinden met 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

Configuratie

Basisinstelling

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

Veldmapping

Map GitHub-gebruikersdata naar Brevo-contactattributen:

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-endpoints

Tajo integreert met de volgende GitHub REST API-endpoints:

Codevoorbeelden

Connector initialiseren

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

Contributors synchroniseren naar 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-events afhandelen

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-campagne triggeren

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

Rate limits

GitHub hanteert rate limits afhankelijk van de authenticatiemethode:

Aanvullende limieten:

• Secondary rate limits: Niet meer dan 100 gelijktijdige requests. Niet meer dan 900 punten per minuut voor REST API-endpoints.
• GraphQL: 5.000 punten per uur (querycost varieert per complexiteit).

Probleemoplossing

Veelvoorkomende problemen

Debugmodus

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

Verbinding 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. Gebruik GitHub Apps in plaats van PATs - GitHub Apps bieden granulaire permissies en tokens die automatisch verversen
2. Zet webhook secrets aan - Verifieer altijd webhook-signatures met HMAC-SHA256
3. Gebruik conditional requests - Benut ETags om geen rate limit-quota te verspillen
4. Pagineer grote responses - GitHub retourneert max. 100 items per pagina; itereer met Link-headers
5. Synchroniseer tijdens laagactieve uren - Plan full syncs buiten piek-developmenturen
6. Monitor rate limit-headers - Controleer X-RateLimit-Remaining om proactief te throttlen

Beveiliging

• GitHub App-authenticatie - RSA-key-gebaseerde JWT met kortlevende installation tokens
• Webhook-signatures - HMAC-SHA256-signature-verificatie op alle webhook-payloads
• Fine-Grained Tokens - Gescoped tot specifieke repositories en permissies
• Alleen HTTPS - Alle API-communicatie is versleuteld via TLS 1.2+
• Encrypted storage - Private keys en tokens versleuteld opgeslagen bij Tajo
• Tokenverloop - Fine-grained tokens verlopen automatisch; zet rotatie-alerts op

Gerelateerde bronnen

• Jira-connector
• Linear-connector
• Notion-connector
• Brevo Contacts API