موصل GitHub

اربط مستودعات GitHub الخاصة بك بـ Brevo لتتبع تفاعل المطورين، وسير عمل إشعارات الإصدارات، ومراقبة نشاط المجتمع عبر Tajo.

نظرة عامة

الميزات

• تتبع المشاكل وطلبات السحب - مزامنة أحداث المشاكل وطلبات السحب إلى جداول زمنية لجهات اتصال Brevo
• إشعارات الإصدارات - تشغيل حملات Brevo عند إصدارات المستودعات الجديدة
• مزامنة المساهمين - ربط مساهمي GitHub بجهات اتصال Brevo لتفاعل المجتمع
• تتبع النجوم والنسخ - مراقبة مقاييس شعبية المستودعات
• إعادة توجيه أحداث Webhook - إعادة توجيه أحداث GitHub إلى أتمتات Brevo
• كتالوج المستودعات - مزامنة بيانات المستودعات الوصفية كعناصر كتالوج Brevo

المتطلبات المسبقة

قبل أن تبدأ، تأكد من توفر ما يلي:

1. حساب GitHub مع الوصول إلى المستودعات المستهدفة
2. تطبيق GitHub App أو Personal Access Token (يُفضَّل النوع الدقيق)
3. وصول المسؤول إلى المستودعات لتكوين webhook
4. حساب Brevo مع وصول API
5. حساب Tajo مع اشتراك نشط

المصادقة

يدعم GitHub عدة طرق للمصادقة. يوصي Tajo باستخدام GitHub Apps للوصول على مستوى المنظمة.

الخيار 1: GitHub App (موصى به)

1. انتقل إلى Settings > Developer settings > GitHub Apps
2. انقر على New GitHub App
3. اضبط التطبيق بهذه الأذونات:

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

الخيار 2: Fine-Grained Personal Access Token

1. اذهب إلى Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. انقر على Generate new token
3. حدد المستودعات المستهدفة
4. امنح هذه الأذونات:

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

الاتصال بـ 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

الإعداد

الإعداد الأساسي

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

ربط الحقول

اربط بيانات مستخدمي GitHub بسمات جهات اتصال 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

نقاط نهاية API

يتكامل Tajo مع نقاط نهاية GitHub REST API التالية:

أمثلة البرمجة

تهيئة الموصل

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

مزامنة المساهمين إلى 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
// }

معالجة أحداث 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');
});

تشغيل حملة إصدار

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

حدود المعدل

يفرض GitHub حدود معدل بناءً على طريقة المصادقة:

حدود إضافية:

• حدود المعدل الثانوية: لا تزيد عن 100 طلب متزامن. لا تزيد عن 900 نقطة في الدقيقة لنقاط نهاية REST API.
• GraphQL: 5,000 نقطة/ساعة (تكلفة الاستعلام تختلف حسب التعقيد).

استكشاف الأخطاء

المشكلات الشائعة

وضع التصحيح

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

اختبار الاتصال

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

أفضل الممارسات

1. استخدم GitHub Apps بدلاً من PATs - توفر GitHub Apps أذونات دقيقة ورموزًا تتجدد تلقائيًا
2. فعّل أسرار webhook - تحقق دائمًا من توقيعات webhook باستخدام HMAC-SHA256
3. استخدم الطلبات الشرطية - استفد من ETags لتجنب إهدار حصة حد المعدل
4. قسّم الاستجابات الكبيرة - يُرجع GitHub كحد أقصى 100 عنصر لكل صفحة؛ كرر باستخدام ترويسات Link
5. زامن في أوقات النشاط المنخفض - جدول عمليات المزامنة الكاملة خارج ساعات التطوير الذروة
6. راقب ترويسات حد المعدل - تحقق من X-RateLimit-Remaining للتحكم في الطلبات بشكل استباقي

الأمان

• مصادقة GitHub App - JWT قائم على مفتاح RSA مع رموز تثبيت قصيرة الأجل
• توقيعات Webhook - التحقق من توقيع HMAC-SHA256 على جميع حمولات webhook
• الرموز الدقيقة - محددة النطاق لمستودعات وأذونات محددة
• HTTPS فقط - جميع اتصالات API مشفرة عبر TLS 1.2+
• التخزين المشفر - المفاتيح الخاصة والرموز مشفرة في حالة السكون في Tajo
• انتهاء صلاحية الرمز - الرموز الدقيقة تنتهي صلاحيتها تلقائيًا؛ اضبط تنبيهات الدوران

موارد ذات صلة

• موصل Jira
• موصل Linear
• موصل Notion
• Brevo Contacts API