GitHub 连接器

通过 Tajo 将您的 GitHub 仓库连接到 Brevo，实现开发者参与度跟踪、发布通知工作流和社区活动监控。

概览

属性	值
平台	GitHub
类别	自定义
设置复杂度	中等
官方集成	否
同步数据	事件、用户、仓库
API 类型	REST API、GraphQL API
认证方式	GitHub App / 个人访问令牌 / OAuth 2.0
基础 URL	`https://api.github.com`
API 版本	`2022-11-28`（基于头的版本控制）

功能

Issue 和 PR 跟踪 - 将 Issue 和 Pull Request 事件同步到 Brevo 联系人时间线
发布通知 - 新仓库发布时触发 Brevo 活动
贡献者同步 - 将 GitHub 贡献者映射到 Brevo 联系人，用于社区参与
Star 和 Fork 跟踪 - 监控仓库流行度指标
Webhook 事件转发 - 将 GitHub 事件转发到 Brevo 自动化
仓库目录 - 将仓库元数据同步为 Brevo 目录条目

前提条件

开始之前，请确保您已具备：

具有目标仓库访问权限的 GitHub 账户
GitHub App 或个人访问令牌（推荐使用细粒度令牌）
仓库的管理员访问权限，用于配置 Webhook
具有 API 访问权限的 Brevo 账户
具有有效订阅的 Tajo 账户

认证

GitHub 支持多种认证方式。Tajo 推荐使用 GitHub Apps 进行组织级访问。

选项 1：GitHub App（推荐）

前往设置 > 开发者设置 > GitHub Apps
点击新建 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：细粒度个人访问令牌

前往设置 > 开发者设置 > 个人访问令牌 > 细粒度令牌
点击生成新令牌
选择目标仓库
授予以下权限：

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

令牌安全

细粒度令牌有过期日期。在过期前设置令牌轮换。GitHub App 安装令牌自动刷新，推荐用于生产环境。

连接到 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 端点：

端点	方法	用途
`/repos/{owner}/{repo}/issues`	GET	列出仓库 Issue
`/repos/{owner}/{repo}/pulls`	GET	列出 Pull Request
`/repos/{owner}/{repo}/releases`	GET	列出发布
`/repos/{owner}/{repo}/contributors`	GET	列出贡献者
`/repos/{owner}/{repo}/stargazers`	GET	列出 Star 用户
`/repos/{owner}/{repo}/forks`	GET	列出 Fork
`/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');

  // 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 根据认证方式执行速率限制：

认证方式	主要速率限制	搜索 API
未认证	60 请求/小时	10 请求/分钟
个人访问令牌	5,000 请求/小时	30 请求/分钟
GitHub App（安装）	5,000 请求/小时	30 请求/分钟
GitHub App（用户到服务器）	5,000 请求/小时	30 请求/分钟

条件请求

Tajo 使用条件请求（If-None-Match / If-Modified-Since 头）来减少 API 消耗。304 Not Modified 响应不计入速率限制。

附加限制：

次要速率限制：不超过 100 个并发请求。REST API 端点每分钟不超过 900 点。
GraphQL：每小时 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 authentication successful
# ✓ Repository access verified
# ✓ Issue data readable
# ✓ Webhook delivery active
# ✓ Rate limit healthy (4,850/5,000 remaining)

最佳实践

使用 GitHub Apps 而非 PAT - GitHub Apps 提供细粒度权限和自动刷新令牌
启用 Webhook 密钥 - 始终使用 HMAC-SHA256 验证 Webhook 签名
使用条件请求 - 利用 ETag 避免浪费速率限制配额
分页大型响应 - GitHub 每页最多返回 100 条；使用 Link 头迭代
在低活跃期同步 - 在高峰开发时段外安排全量同步
监控速率限制头 - 检查 X-RateLimit-Remaining 以主动限流

安全

GitHub App 认证 - 基于 RSA 密钥的 JWT，具有短期安装令牌
Webhook 签名 - 所有 Webhook 负载的 HMAC-SHA256 签名验证
细粒度令牌 - 限定到特定仓库和权限
仅 HTTPS - 所有 API 通信通过 TLS 1.2+ 加密
加密存储 - 私钥和令牌在 Tajo 中静态加密
令牌过期 - 细粒度令牌自动过期；设置轮换提醒

GitHub 连接器

概览

功能

前提条件

认证

选项 1：GitHub App（推荐）

选项 2：细粒度个人访问令牌

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

将贡献者同步到 Brevo

处理 Webhook 事件

触发发布活动

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Thanks — you're subscribed.

GitHub 连接器

概览

功能

前提条件

认证

选项 1：GitHub App（推荐）

选项 2：细粒度个人访问令牌

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

将贡献者同步到 Brevo

处理 Webhook 事件

触发发布活动

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Subscribe to updates

Thanks — you're subscribed.