GitHub コネクタ

GitHub リポジトリを Brevo に接続し、Tajo を介して開発者エンゲージメントのトラッキング、リリース通知ワークフロー、コミュニティアクティビティの監視を実現します。

概要

プロパティ	値
プラットフォーム	GitHub
カテゴリ	カスタム
セットアップの複雑さ	中
公式統合	いいえ
同期データ	イベント、ユーザー、リポジトリ
API タイプ	REST API、GraphQL API
認証	GitHub App / Personal Access Token / OAuth 2.0
ベース URL	`https://api.github.com`
API バージョン	`2022-11-28`(ヘッダーベースのバージョニング)

機能

Issue と PR のトラッキング - Issue およびプルリクエストのイベントを Brevo 連絡先タイムラインに同期
リリース通知 - 新しいリポジトリリリース時に Brevo キャンペーンをトリガー
コントリビューター同期 - コミュニティエンゲージメントのために GitHub コントリビューターを Brevo 連絡先にマッピング
スターとフォークのトラッキング - リポジトリの人気指標を監視
Webhook イベント転送 - GitHub イベントを Brevo 自動化に転送
リポジトリカタログ - リポジトリメタデータを Brevo カタログ項目として同期

前提条件

開始する前に、以下を準備してください。

対象リポジトリへのアクセス権を持つ GitHub アカウント
GitHub App または Personal Access Token(fine-grained 推奨)
Webhook 設定のためのリポジトリへの管理者アクセス
API アクセス可能な Brevo アカウント
有効なサブスクリプションを持つ Tajo アカウント

認証

GitHub は複数の認証方法をサポートしています。Tajo では組織レベルのアクセスには GitHub Apps の使用を推奨します。

オプション 1: GitHub App(推奨)

Settings > Developer settings > GitHub Apps に移動
New GitHub App をクリック
以下の権限でアプリを設定:

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

Settings > Developer settings > Personal access tokens > Fine-grained tokens に移動
Generate new token をクリック
対象リポジトリを選択
以下の権限を付与:

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

トークンセキュリティ

Fine-grained トークンには有効期限があります。期限前にトークンローテーションを設定してください。GitHub App インストールトークンは自動的に更新され、本番使用で推奨されます。

Tajo への接続

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

# Personal Access Token を使用
tajo connectors install github \
  --token $GITHUB_TOKEN

設定

基本セットアップ

connectors:
  github:
    enabled: true
    auth_type: "github_app"  # または "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:
  # 標準フィールド
  login: GITHUB_USERNAME
  email: email
  name: FIRSTNAME

  # 開発者メトリクス
  contributions: GITHUB_CONTRIBUTIONS
  repositories_count: GITHUB_REPOS
  followers: GITHUB_FOLLOWERS
  created_at: GITHUB_JOINED

  # カスタム属性
  company: COMPANY
  location: LOCATION
  bio: GITHUB_BIO

API エンドポイント

Tajo は以下の GitHub REST API エンドポイントと統合します。

エンドポイント	メソッド	目的
`/repos/{owner}/{repo}/issues`	GET	リポジトリの Issue を一覧取得
`/repos/{owner}/{repo}/pulls`	GET	プルリクエストを一覧取得
`/repos/{owner}/{repo}/releases`	GET	リリースを一覧取得
`/repos/{owner}/{repo}/contributors`	GET	コントリビューターを一覧取得
`/repos/{owner}/{repo}/stargazers`	GET	スターしたユーザーを一覧取得
`/repos/{owner}/{repo}/forks`	GET	フォークを一覧取得
`/repos/{owner}/{repo}/events`	GET	リポジトリイベントを一覧取得
`/users/{username}`	GET	ユーザープロファイルを取得
`/orgs/{org}/members`	GET	組織メンバーを一覧取得
`/repos/{owner}/{repo}/hooks`	POST	Webhook を作成

コード例

コネクタの初期化

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

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

リリースキャンペーンをトリガー

// 新しいリリースをリッスンして 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
    }
  });
});

レート制限

GitHub は認証方法に基づいてレート制限を適用します。

認証	主要レート制限	Search API
未認証	60 リクエスト/時間	10 リクエスト/分
Personal Access Token	5,000 リクエスト/時間	30 リクエスト/分
GitHub App(インストール)	5,000 リクエスト/時間	30 リクエスト/分
GitHub App(ユーザー to サーバー)	5,000 リクエスト/時間	30 リクエスト/分

条件付きリクエスト

Tajo は条件付きリクエスト(If-None-Match / If-Modified-Since ヘッダー)を使用して API 消費を削減します。304 Not Modified のレスポンスはレート制限にカウントされません。

追加の制限:

セカンダリレート制限: 同時リクエスト 100 件以下。REST API エンドポイントは 1 分あたり 900 ポイント以下。
GraphQL: 1 時間あたり 5,000 ポイント(クエリコストは複雑度により変動)。

トラブルシューティング

一般的な問題

問題	原因	解決策
401 Unauthorized	トークン期限切れまたは資格情報の誤り	トークンを再生成するか GitHub App を再インストール
403 Forbidden	権限不足	トークンのスコープまたは App の権限を確認
404 Not Found	アクセス権のないプライベートリポジトリ	トークンまたは App にリポジトリアクセスを付与
レート制限超過	API 呼び出し過多	条件付きリクエストを有効化して同期頻度を下げる
Webhook を受信できない	不正な URL またはファイアウォール	Webhook URL が公開アクセス可能か確認

デバッグモード

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

接続テスト

tajo connectors test github
# ✓ API 認証に成功
# ✓ リポジトリアクセスを確認
# ✓ Issue データ読み取り可能
# ✓ Webhook 配信有効
# ✓ レート制限は正常(4,850/5,000 残り)

ベストプラクティス

PAT よりも GitHub Apps を使用する - GitHub Apps は細かい権限と自動更新トークンを提供
Webhook シークレットを有効化する - 常に HMAC-SHA256 で Webhook 署名を検証
条件付きリクエストを使用する - ETag を活用してレート制限の無駄を防止
大きなレスポンスをページネーションする - GitHub はページあたり最大 100 アイテムを返します。Link ヘッダーで反復処理
低アクティビティ時間中に同期する - ピーク開発時間外にフル同期をスケジュール
レート制限ヘッダーを監視する - X-RateLimit-Remaining を確認して事前にスロットリング

セキュリティ

GitHub App 認証 - RSA キーベースの JWT と短期インストールトークン
Webhook 署名 - すべての Webhook ペイロードで HMAC-SHA256 署名検証
Fine-Grained トークン - 特定のリポジトリと権限にスコープ
HTTPS のみ - すべての API 通信は TLS 1.2 以上で暗号化
暗号化されたストレージ - プライベートキーとトークンは Tajo で保存時に暗号化
トークンの有効期限 - Fine-grained トークンは自動的に期限切れ。ローテーションアラートを設定

GitHub コネクタ

概要

機能

前提条件

認証

オプション 1: GitHub App(推奨)

オプション 2: Fine-Grained Personal Access Token

Tajo への接続

設定

基本セットアップ

フィールドマッピング

API エンドポイント

コード例

コネクタの初期化

コントリビューターを Brevo に同期

Webhook イベントの処理

リリースキャンペーンをトリガー

レート制限

トラブルシューティング

一般的な問題

デバッグモード

接続テスト

ベストプラクティス

セキュリティ

関連リソース

Thanks — you're subscribed.

GitHub コネクタ

概要

機能

前提条件

認証

オプション 1: GitHub App(推奨)

オプション 2: Fine-Grained Personal Access Token

Tajo への接続

設定

基本セットアップ

フィールドマッピング

API エンドポイント

コード例

コネクタの初期化

コントリビューターを Brevo に同期

Webhook イベントの処理

リリースキャンペーンをトリガー

レート制限

トラブルシューティング

一般的な問題

デバッグモード

接続テスト

ベストプラクティス

セキュリティ

関連リソース

Subscribe to updates

Thanks — you're subscribed.