Konektor GitHub

Hubungkan repositori GitHub Anda ke Brevo untuk melacak engagement developer, menjalankan alur notifikasi rilis, dan memantau aktivitas komunitas melalui Tajo.

Ikhtisar

Fitur

• Pelacakan issue dan PR - Sinkronkan event issue dan pull request ke linimasa contact Brevo
• Notifikasi rilis - Picu kampanye Brevo saat ada rilis repositori baru
• Sync kontributor - Petakan kontributor GitHub ke contacts Brevo untuk engagement komunitas
• Pelacakan star dan fork - Pantau metrik popularitas repositori
• Penerusan event webhook - Teruskan event GitHub ke otomatisasi Brevo
• Katalog repositori - Sinkronkan metadata repositori sebagai item katalog Brevo

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

1. Akun GitHub dengan akses ke repositori yang dituju
2. GitHub App atau Personal Access Token (fine-grained direkomendasikan)
3. Akses admin ke repositori untuk mengonfigurasi webhook
4. Akun Brevo dengan akses API
5. Akun Tajo dengan langganan aktif

Autentikasi

GitHub mendukung beberapa metode autentikasi. Tajo merekomendasikan GitHub Apps untuk akses tingkat organisasi.

Opsi 1: GitHub App (direkomendasikan)

1. Buka Settings > Developer settings > GitHub Apps
2. Klik New GitHub App
3. Konfigurasikan app dengan permission berikut:

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

Opsi 2: Fine-grained Personal Access Token

1. Buka Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Klik Generate new token
3. Pilih repositori yang dituju
4. Berikan permission berikut:

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

Menghubungkan ke 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

Konfigurasi

Penyiapan dasar

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

Pemetaan field

Petakan data pengguna GitHub ke atribut 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

Endpoint API

Tajo terintegrasi dengan endpoint GitHub REST API berikut:

Contoh kode

Inisialisasi konektor

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

Menyinkronkan kontributor ke 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
// }

Menangani event 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');
});

Memicu kampanye rilis

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

Batas rate

GitHub menerapkan rate limit berdasarkan metode autentikasi:

Batas tambahan:

• Rate limit sekunder: Tidak lebih dari 100 request bersamaan. Tidak lebih dari 900 poin per menit untuk endpoint REST API.
• GraphQL: 5.000 poin per jam (biaya query bervariasi menurut kompleksitas).

Pemecahan masalah

Masalah umum

Mode debug

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

Uji koneksi

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

Praktik terbaik

1. Utamakan GitHub Apps dibanding PAT - GitHub Apps memberikan permission yang lebih granular dan token yang diperbarui otomatis
2. Aktifkan secret webhook - Selalu verifikasi signature webhook dengan HMAC-SHA256
3. Gunakan request kondisional - Manfaatkan ETag agar kuota rate limit tidak terbuang
4. Paginasikan respons besar - GitHub mengembalikan maksimal 100 item per halaman; lakukan iterasi dengan header Link
5. Sinkronkan saat aktivitas rendah - Jadwalkan sync penuh di luar jam pengembangan tersibuk
6. Pantau header rate limit - Periksa X-RateLimit-Remaining untuk melakukan throttling secara proaktif

Keamanan

• Autentikasi GitHub App - JWT berbasis kunci RSA dengan token instalasi berumur pendek
• Signature webhook - Verifikasi signature HMAC-SHA256 pada semua payload webhook
• Token fine-grained - Dibatasi ke repositori dan permission tertentu
• HTTPS Only - Semua komunikasi API dienkripsi melalui TLS 1.2+
• Penyimpanan terenkripsi - Private key dan token dienkripsi saat disimpan di Tajo
• Masa berlaku token - Token fine-grained kedaluwarsa otomatis; siapkan peringatan rotasi

Sumber daya terkait

• Konektor Jira
• Konektor Linear
• Konektor Notion
• Brevo Contacts API