Connecteur GitHub

Connectez vos dépôts GitHub à Brevo pour le suivi de l’engagement développeur, les workflows de notification de release et la surveillance de l’activité communautaire via Tajo.

Vue d’ensemble

Fonctionnalités

• Suivi des issues et PR, Synchronisez les événements d’issues et de pull requests vers les timelines de contacts Brevo
• Notifications de release, Déclenchez des campagnes Brevo lors de nouvelles releases de dépôt
• Synchronisation des contributeurs, Mappez les contributeurs GitHub vers des contacts Brevo pour l’engagement communautaire
• Suivi des stars et forks, Surveillez les métriques de popularité de dépôt
• Transfert d’événements webhook, Transférez les événements GitHub vers les automatisations Brevo
• Catalogue de dépôts, Synchronisez les métadonnées de dépôts en tant qu’éléments de catalogue Brevo

Prérequis

Avant de commencer, assurez-vous de disposer de :

1. Un compte GitHub avec accès aux dépôts cibles
2. Une GitHub App ou un Personal Access Token (fine-grained recommandé)
3. Un accès admin aux dépôts pour la configuration des webhooks
4. Un compte Brevo avec accès API
5. Un compte Tajo avec un abonnement actif

Authentification

GitHub prend en charge plusieurs méthodes d’authentification. Tajo recommande d’utiliser les GitHub Apps pour un accès au niveau de l’organisation.

Option 1 : GitHub App (recommandé)

1. Allez dans Settings > Developer settings > GitHub Apps
2. Cliquez sur New GitHub App
3. Configurez l’app avec ces permissions :

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. Allez dans Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Cliquez sur Generate new token
3. Sélectionnez les dépôts cibles
4. Accordez ces permissions :

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

Connexion à Tajo

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

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

Configuration

Configuration de base

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

Mappage des champs

Mappez les données utilisateur GitHub vers les attributs de contact Brevo :

field_mapping:
  # Champs standards
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # Métriques développeur
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # Attributs personnalisés
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

Endpoints API

Tajo s’intègre avec les endpoints suivants de l’API REST GitHub :

Exemples de code

Initialiser le connecteur

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

Synchroniser les contributeurs vers 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
// }

Gérer les événements webhook

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

  // Vérifier la signature du 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');
});

Déclencher une campagne de release

// Écouter les nouvelles releases et déclencher une campagne 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
    }
  });
});

Limites de débit

GitHub impose des limites de débit selon la méthode d’authentification :

Limites supplémentaires :

• Limites de débit secondaires : pas plus de 100 requêtes simultanées. Pas plus de 900 points par minute pour les endpoints de l’API REST.
• GraphQL : 5 000 points par heure (le coût de la requête varie selon la complexité).

Dépannage

Problèmes courants

Mode debug

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

Tester la connexion

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

Bonnes pratiques

1. Préférez les GitHub Apps aux PAT, Les GitHub Apps offrent des permissions granulaires et des tokens auto-rafraîchis
2. Activez les secrets de webhook, Vérifiez toujours les signatures de webhook avec HMAC-SHA256
3. Utilisez les requêtes conditionnelles, Exploitez les ETags pour éviter de gaspiller votre quota de débit
4. Paginez les grandes réponses, GitHub renvoie max 100 éléments par page ; itérez avec les en-têtes Link
5. Synchronisez hors pic d’activité, Planifiez les synchronisations complètes en dehors des heures de dev
6. Surveillez les en-têtes de limite de débit, Vérifiez X-RateLimit-Remaining pour throttler de manière proactive

Sécurité

• Authentification GitHub App, JWT basé sur clé RSA avec tokens d’installation à courte durée de vie
• Signatures des webhooks, Vérification de signature HMAC-SHA256 sur toutes les charges utiles webhook
• Tokens fine-grained, Limités à des dépôts et permissions spécifiques
• HTTPS uniquement, Toutes les communications API chiffrées via TLS 1.2+
• Stockage chiffré, Clés privées et tokens chiffrés au repos dans Tajo
• Expiration des tokens, Les tokens fine-grained expirent automatiquement ; configurez des alertes de rotation

Ressources associées

• Connecteur Jira
• Connecteur Linear
• Connecteur Notion
• API Contacts Brevo