GitHub Bağlayıcısı

Geliştirici etkileşim takibi, sürüm bildirim iş akışları ve topluluk aktivite izleme için GitHub depolarınızı Tajo üzerinden Brevo’ya bağlayın.

Genel Bakış

Özellikler

• Sorun ve PR takibi - Sorun ve pull request olaylarını Brevo kişi zaman çizelgelerine senkronize edin
• Sürüm bildirimleri - Yeni depo sürümlerinde Brevo kampanyalarını tetikleyin
• Katkıda bulunan senkronizasyonu - GitHub katkıda bulunanlarını topluluk etkileşimi için Brevo kişileriyle eşleştirin
• Yıldız ve fork takibi - Depo popülerlik metriklerini izleyin
• Webhook olay yönlendirme - GitHub olaylarını Brevo otomasyonlarına iletin
• Depo kataloğu - Depo meta verilerini Brevo katalog öğeleri olarak senkronize edin

Ön Koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

1. Hedef depolara erişimi olan bir GitHub hesabı
2. Bir GitHub App veya Kişisel Erişim Belirteci (ince taneli önerilir)
3. Webhook yapılandırması için depolara yönetici erişimi
4. API erişimi olan bir Brevo hesabı
5. Etkin aboneliği olan bir Tajo hesabı

Kimlik Doğrulama

GitHub birden fazla kimlik doğrulama yöntemini destekler. Tajo, kuruluş düzeyinde erişim için GitHub App kullanımını önerir.

Seçenek 1: GitHub App (Önerilen)

1. Settings > Developer settings > GitHub Apps bölümüne gidin
2. New GitHub App öğesine tıklayın
3. Uygulamayı şu izinlerle yapılandırın:

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

Seçenek 2: İnce Taneli Kişisel Erişim Belirteci

1. Settings > Developer settings > Personal access tokens > Fine-grained tokens bölümüne gidin
2. Generate new token öğesine tıklayın
3. Hedef depoları seçin
4. Şu izinleri verin:

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

Tajo’ya Bağlanma

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

# Kişisel Erişim Belirteci kullanarak
tajo connectors install github \
  --token $GITHUB_TOKEN

Yapılandırma

Temel Kurulum

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

Alan Eşleştirme

GitHub kullanıcı verilerini Brevo kişi özniteliklerine eşleyin:

field_mapping:
  # Standart alanlar
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # Geliştirici metrikleri
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # Özel öznitelikler
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

API Uç Noktaları

Tajo, aşağıdaki GitHub REST API uç noktalarıyla entegre olur:

Kod Örnekleri

Bağlayıcıyı Başlatma

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

Katkıda Bulunanları Brevo’ya Senkronize Etme

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

Webhook Olaylarını İşleme

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

  // Webhook imzasını doğrula
  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');
});

Sürüm Kampanyası Tetikleme

// Yeni sürümleri dinleyip Brevo kampanyasını tetikle
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
    }
  });
});

Hız Sınırları

GitHub, kimlik doğrulama yöntemine göre hız sınırları uygular:

Ek sınırlar:

• İkincil hız sınırları: En fazla 100 eşzamanlı istek. REST API uç noktaları için dakikada en fazla 900 puan.
• GraphQL: Saatte 5.000 puan (sorgu maliyeti karmaşıklığa göre değişir).

Sorun Giderme

Yaygın Sorunlar

Hata Ayıklama Modu

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

Bağlantı Testi

tajo connectors test github
# ✓ API kimlik doğrulaması başarılı
# ✓ Depo erişimi doğrulandı
# ✓ Sorun verileri okunabilir
# ✓ Webhook teslimatı aktif
# ✓ Hız sınırı sağlıklı (4.850/5.000 kalan)

En İyi Uygulamalar

1. PAT yerine GitHub App kullanın - GitHub App’ler ayrıntılı izinler ve otomatik yenilenen belirteçler sağlar
2. Webhook gizli anahtarlarını etkinleştirin - Webhook imzalarını her zaman HMAC-SHA256 ile doğrulayın
3. Koşullu istekler kullanın - Hız sınırı kotasını boşa harcamamak için ETag’lerden yararlanın
4. Büyük yanıtları sayfalandırın - GitHub sayfa başına maksimum 100 öğe döndürür; Link başlıklarıyla yineleyin
5. Düşük aktivite döneminde senkronize edin - Tam senkronizasyonları yoğun geliştirme saatleri dışında planlayın
6. Hız sınırı başlıklarını izleyin - Proaktif olarak kısıtlamak için X-RateLimit-Remaining değerini kontrol edin

Güvenlik

• GitHub App Kimlik Doğrulaması - Kısa ömürlü kurulum belirteçleriyle RSA anahtar tabanlı JWT
• Webhook İmzaları - Tüm webhook yüklerinde HMAC-SHA256 imza doğrulama
• İnce Taneli Belirteçler - Belirli depolara ve izinlere kapsamlandırılmış
• Yalnızca HTTPS - Tüm API iletişimi TLS 1.2+ ile şifrelenir
• Şifreli Depolama - Özel anahtarlar ve belirteçler Tajo’da şifreli olarak saklanır
• Belirteç Süresi - İnce taneli belirteçler otomatik olarak süresi dolar; rotasyon uyarıları ayarlayın

İlgili Kaynaklar

• Jira Bağlayıcısı
• Linear Bağlayıcısı
• Notion Bağlayıcısı
• Brevo Kişiler API