Connettore GitHub

Collega i tuoi repository GitHub a Brevo per monitorare l’engagement degli sviluppatori, attivare flussi di notifica sulle release e tracciare l’attività della community tramite Tajo.

Panoramica

Funzionalità

• Tracciamento issue e PR - Sincronizza eventi di issue e pull request sulle timeline dei contatti Brevo
• Notifiche di release - Attiva campagne Brevo sulle nuove release dei repository
• Sync dei contributor - Mappa i contributor GitHub sui contatti Brevo per la community engagement
• Tracciamento star e fork - Monitora le metriche di popolarità dei repository
• Inoltro eventi webhook - Inoltra gli eventi GitHub alle automazioni Brevo
• Catalogo repository - Sincronizza i metadati dei repository come elementi del catalogo Brevo

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account GitHub con accesso ai repository target
2. Una GitHub App o un Personal Access Token (fine-grained consigliato)
3. Accesso admin ai repository per la configurazione dei webhook
4. Un account Brevo con accesso API
5. Un account Tajo con abbonamento attivo

Autenticazione

GitHub supporta diversi metodi di autenticazione. Tajo consiglia l’uso di GitHub App per accessi a livello di organizzazione.

Opzione 1: GitHub App (consigliata)

1. Vai su Settings > Developer settings > GitHub Apps
2. Clicca su New GitHub App
3. Configura l’app con questi permessi:

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

Opzione 2: Fine-Grained Personal Access Token

1. Vai su Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Clicca su Generate new token
3. Seleziona i repository target
4. Concedi questi permessi:

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

Connessione a Tajo

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

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

Configurazione

Setup di base

connectors:
  github:
    enabled: true
    auth_type: "github_app"  # oppure "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

Mapping dei campi

Mappa i dati utente GitHub sugli attributi dei contatti Brevo:

field_mapping:
  # Campi standard
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # Metriche dello sviluppatore
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # Attributi personalizzati
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

Endpoint API

Tajo si integra con i seguenti endpoint della REST API di GitHub:

Esempi di codice

Inizializzare il connettore

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

Sincronizzare i contributor su 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
// }

Gestire gli eventi webhook

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

  // Verifica la firma del webhook
  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');
});

Attivare una campagna sulle release

// Ascolta le nuove release e attiva una campagna Brevo
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
    }
  });
});

Limiti di rate

GitHub applica limiti di rate in base al metodo di autenticazione:

Limiti aggiuntivi:

• Rate limit secondari: non più di 100 richieste concorrenti. Non più di 900 punti al minuto per gli endpoint REST API.
• GraphQL: 5.000 punti all’ora (il costo della query varia in base alla complessità).

Risoluzione dei problemi

Problemi comuni

Modalità debug

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

Testare la connessione

tajo connectors test github
# ✓ Autenticazione API riuscita
# ✓ Accesso ai repository verificato
# ✓ Dati issue leggibili
# ✓ Consegna webhook attiva
# ✓ Rate limit sano (4.850/5.000 rimanenti)

Best practice

1. Preferisci le GitHub App ai PAT - Le GitHub App offrono permessi granulari e token auto-refreshing
2. Abilita i segreti dei webhook - Verifica sempre le firme webhook con HMAC-SHA256
3. Usa richieste condizionali - Sfrutta gli ETag per non sprecare quota del rate limit
4. Paginate le risposte grandi - GitHub restituisce max 100 elementi per pagina; itera tramite header Link
5. Sincronizza nei momenti di minore attività - Pianifica i sync completi fuori dagli orari di picco
6. Monitora gli header di rate limit - Controlla X-RateLimit-Remaining per applicare throttling in modo proattivo

Sicurezza

• Autenticazione GitHub App - JWT basato su chiave RSA con token di installazione a breve durata
• Firme webhook - Verifica firma HMAC-SHA256 su tutti i payload webhook
• Token fine-grained - Limitati a repository e permessi specifici
• Solo HTTPS - Tutte le comunicazioni API cifrate tramite TLS 1.2+
• Archiviazione cifrata - Chiavi private e token cifrati a riposo in Tajo
• Scadenza token - I token fine-grained scadono automaticamente; imposta alert di rotazione

Risorse correlate

• Connettore Jira
• Connettore Linear
• Connettore Notion
• Brevo Contacts API