Conector GitHub

Conectați depozitele GitHub la Brevo pentru urmărirea implicării dezvoltatorilor, fluxuri de notificare pentru lansări și monitorizarea activității comunității prin Tajo.

Prezentare generală

Funcționalități

• Urmărire probleme și PR-uri - Sincronizați evenimentele de probleme și cereri de pull în cronologiile de contact Brevo
• Notificări lansări - Declanșați campanii Brevo la lansări noi de depozite
• Sincronizare contributori - Mapați contributorii GitHub la contactele Brevo pentru implicarea comunității
• Urmărire stele și fork-uri - Monitorizați valorile de popularitate ale depozitelor
• Redirecționare evenimente webhook - Transmiteți evenimentele GitHub la automatizările Brevo
• Catalog depozite - Sincronizați metadatele depozitelor ca elemente din catalogul Brevo

Cerințe preliminare

Înainte de a începe, asigurați-vă că aveți:

1. Un cont GitHub cu acces la depozitele țintă
2. O aplicație GitHub sau Token de acces personal (recomandat fin-granulat)
3. Acces de administrator la depozite pentru configurarea webhook-urilor
4. Un cont Brevo cu acces API
5. Un cont Tajo cu abonament activ

Autentificare

GitHub suportă mai multe metode de autentificare. Tajo recomandă utilizarea GitHub Apps pentru acces la nivel de organizație.

Opțiunea 1: GitHub App (Recomandat)

1. Navigați la Settings > Developer settings > GitHub Apps
2. Faceți clic pe New GitHub App
3. Configurați aplicația cu aceste permisiuni:

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

Opțiunea 2: Token de acces personal fin-granulat

1. Accesați Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Faceți clic pe Generate new token
3. Selectați depozitele țintă
4. Acordați aceste permisiuni:

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

Conectare la 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

Configurare

Configurare de bază

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

Mapare câmpuri

Mapați datele utilizatorilor GitHub la atributele de contact 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

Puncte finale API

Tajo se integrează cu următoarele puncte finale ale API-ului REST GitHub:

Exemple de cod

Inițializare conector

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

Sincronizare contributori cu 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
// }

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

Declanșare campanie de lansare

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

Limite de rată

GitHub aplică limite de rată bazate pe metoda de autentificare:

Limite suplimentare:

• Limite de rată secundare: Nu mai mult de 100 cereri concurente. Nu mai mult de 900 puncte pe minut pentru punctele finale REST API.
• GraphQL: 5.000 puncte pe oră (costul interogării variază în funcție de complexitate).

Depanare

Probleme frecvente

Modul de depanare

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

Testare conexiune

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

Bune practici

1. Utilizați GitHub Apps față de PAT-uri - GitHub Apps oferă permisiuni granulare și tokeni cu auto-reîmprospătare
2. Activați secretele webhook - Verificați întotdeauna semnăturile webhook cu HMAC-SHA256
3. Utilizați cereri condiționale - Valorificați ETag-urile pentru a evita risipirea cotei de limite de rată
4. Paginați răspunsurile mari - GitHub returnează maxim 100 elemente pe pagină; iterați cu anteturile Link
5. Sincronizați în perioade de activitate redusă - Programați sincronizări complete în afara orelor de vârf de dezvoltare
6. Monitorizați anteturile limitei de rată - Verificați X-RateLimit-Remaining pentru a limita proactiv

Securitate

• Autentificare GitHub App - JWT bazat pe cheie RSA cu tokeni de instalare de scurtă durată
• Semnături webhook - Verificare semnătură HMAC-SHA256 pe toate payload-urile webhook
• Tokeni fin-granulați - Limitați la depozite și permisiuni specifice
• Numai HTTPS - Toată comunicarea API criptată prin TLS 1.2+
• Stocare criptată - Chei private și tokeni criptați în repaus în Tajo
• Expirare token - Tokenii fin-granulați expiră automat; configurați alerte de rotație

Resurse conexe

• Conector Jira
• Conector Linear
• Conector Notion
• API Contacte Brevo