Konektor GitHub

Propojte své repozitáře GitHub s Brevo pro sledování zapojení vývojářů, pracovní toky notifikací o vydáních a monitorování aktivity komunity přes Tajo.

Přehled

Funkce

• Sledování issues a PR – Synchronizujte události issues a pull requestů do časových os kontaktů Brevo
• Notifikace o vydáních – Spouštějte kampaně Brevo při nových vydáních repozitáře
• Synchronizace přispěvatelů – Mapujte přispěvatele GitHub na kontakty Brevo pro zapojení komunity
• Sledování hvězdiček a forků – Monitorujte metriky popularity repozitáře
• Přeposílání webhookových událostí – Přeposílejte události GitHub do automatizací Brevo
• Katalog repozitářů – Synchronizujte metadata repozitářů jako položky katalogu Brevo

Předpoklady

Než začnete, ujistěte se, že máte:

1. Účet GitHub s přístupem k cílovým repozitářům
2. GitHub App nebo osobní přístupový token (doporučen jemně granulovaný)
3. Administrátorský přístup k repozitářům pro konfiguraci webhooků
4. Účet Brevo s přístupem k API
5. Účet Tajo s aktivním předplatným

Ověření

GitHub podporuje více metod ověřování. Tajo doporučuje použití GitHub Apps pro přístup na úrovni organizace.

Možnost 1: GitHub App (doporučeno)

1. Přejděte do Settings > Developer settings > GitHub Apps
2. Klikněte na New GitHub App
3. Nakonfigurujte aplikaci s těmito oprávněními:

Oprávnění repozitáře:
  Issues: Čtení
  Pull requests: Čtení
  Contents: Čtení
  Metadata: Čtení

Oprávnění organizace:
  Members: Čtení

Přihlásit se k odběru událostí:
  Issues
  Pull request
  Push
  Release
  Star
  Fork

Možnost 2: Jemně granulovaný osobní přístupový token

1. Přejděte do Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Klikněte na Generate new token
3. Vyberte cílové repozitáře
4. Udělte tato oprávnění:

Přístup k repozitáři: Vybrané repozitáře
Oprávnění:
  Issues: Pouze čtení
  Pull requests: Pouze čtení
  Contents: Pouze čtení
  Metadata: Pouze čtení

Připojení k Tajo

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

# Použití osobního přístupového tokenu
tajo connectors install github \
  --token $GITHUB_TOKEN

Konfigurace

Základní nastavení

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

Mapování polí

Mapujte uživatelská data GitHub na atributy kontaktů Brevo:

field_mapping:
  # Standardní pole
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # Metriky vývojáře
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # Vlastní atributy
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

Koncové body API

Tajo se integruje s následujícími koncovými body GitHub REST API:

Příklady kódu

Inicializace konektoru

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

Synchronizace přispěvatelů do 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
// }

Zpracování webhookových událostí

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

  // Ověření podpisu webhooku
  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');
});

Spuštění kampaně při vydání

// Naslouchání novým vydáním a spuštění kampaně 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
    }
  });
});

Omezení rychlosti

GitHub aplikuje omezení rychlosti na základě metody ověřování:

Další limity:

• Sekundární limity rychlosti: Ne více než 100 souběžných požadavků. Ne více než 900 bodů za minutu pro koncové body REST API.
• GraphQL: 5 000 bodů za hodinu (cena dotazu se liší podle složitosti).

Řešení problémů

Časté problémy

Režim ladění

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

Test připojení

tajo connectors test github
# ✓ Ověření API úspěšné
# ✓ Přístup k repozitáři ověřen
# ✓ Data issues čitelná
# ✓ Doručování webhooků aktivní
# ✓ Limit rychlosti v pořádku (4 850/5 000 zbývá)

Osvědčené postupy

1. Používejte GitHub Apps místo PAT – GitHub Apps poskytují granulovaná oprávnění a automaticky obnovované tokeny
2. Povolte tajné klíče webhooků – Vždy ověřujte podpisy webhooků pomocí HMAC-SHA256
3. Používejte podmíněné požadavky – Využívejte ETags, abyste neplýtvali limitem API
4. Stránkujte velké odpovědi – GitHub vrací max 100 položek na stránku; iterujte s hlavičkami Link
5. Synchronizujte v době nízké aktivity – Plánujte plné synchronizace mimo špičky vývoje
6. Monitorujte hlavičky limitu rychlosti – Kontrolujte X-RateLimit-Remaining pro proaktivní omezování

Zabezpečení

• Ověření GitHub App – JWT na bázi RSA klíče s krátkodobými instalačními tokeny
• Podpisy webhooků – Ověření podpisu HMAC-SHA256 u všech payloadů webhooků
• Jemně granulované tokeny – Omezeny na konkrétní repozitáře a oprávnění
• Pouze HTTPS – Veškerá komunikace API šifrována přes TLS 1.2+
• Šifrované úložiště – Soukromé klíče a tokeny šifrované v klidu v Tajo
• Vypršení tokenů – Jemně granulované tokeny automaticky vyprší; nastavte upozornění na rotaci

Související zdroje

• Konektor Jira
• Konektor Linear
• Konektor Notion
• API kontaktů Brevo