---
title: "GitHub 连接器"
description: "完整的 GitHub 集成指南，通过 Tajo 将仓库事件、Issue、Pull Request 和开发者活动与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/github/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/github.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# GitHub 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 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 目录条目

## 前提条件

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

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

## 认证

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

### 选项 1：GitHub App（推荐）

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

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

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

令牌安全

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

### 连接到 Tajo

```bash
# 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
```

## 配置

### 基础设置

```yaml
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 联系人属性：

```yaml
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 |

## 代码示例

### 初始化连接器

```javascript
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

```javascript
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 事件

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

### 触发发布活动

```javascript
// 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 可公开访问 |

### 调试模式

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

### 测试连接

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

## 安全

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

## 相关资源

- [Jira 连接器](https://tajo.io/zh-cn/docs/connectors/custom/jira)
- [Linear 连接器](https://tajo.io/zh-cn/docs/connectors/custom/linear)
- [Notion 连接器](https://tajo.io/zh-cn/docs/connectors/custom/notion)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)