 |
摘要 | Discourse GitHub 允许工作人员根据 GitHub 贡献为用户分配徽章。此外，还允许用户创建 GitHub 链接回指（Linkbacks）、固定链接（Permalinks），并在单盒（oneboxes）中显示实时 PR 状态。 |
 |
安装指南 | 此插件已捆绑在 Discourse 核心中。无需单独安装该插件。 |
功能
GitHub 徽章
根据 GitHub 贡献为用户分配徽章。
使用方法：
- 在 设置 → 插件 中启用
github badges enabled。 - 生成 GitHub 访问令牌并将其粘贴到
github linkback access token设置中。请参阅下方的说明。 - 将一个或多个要扫描贡献的 GitHub 仓库 URL 添加到
github badges repos站点设置中。
徽章计数原理：
徽章会统计所有仓库的提交次数。当用户为多个仓库做出贡献时，其所有提交次数将合并为一个总数。
提交者徽章：
| 徽章 | 所需提交次数 |
|---|---|
| 青铜 | 1 次提交 |
| 白银 | 25 次提交 |
| 黄金 | 1000 次提交 |
徽章晋升： 随着用户在任意受跟踪的仓库中积累更多贡献，他们将自动晋升到更高的徽章等级。例如，如果用户先向仓库 A 提交，然后向仓库 B 提交，这两项贡献都将计入其总数，使其能够从青铜晋升到白银，再到黄金。
GitHub 链接回指 (Linkback)
从 GitHub 拉取请求 (PR) 或提交创建链接，回指到提及它的 Discourse 帖子。
使用方法：
- 在 设置 → 插件 中启用
github linkback enabled。 - 生成 GitHub 访问令牌并将其粘贴到
github linkback access token设置中。请参阅下方的说明。 - 最后，在
github linkback projects站点设置中以以下格式添加您希望发布的项目：用户名/仓库名用于特定仓库用户名/*用于特定用户的所有仓库
GitHub 固定链接 (Permalink)
将 GitHub 的非固定链接替换为 固定链接。
使用方法：
- 在 设置 → 插件 中启用
github permalinks enabled。
PR 实时状态
在帖子和聊天消息中的 GitHub 拉取请求 (PR) 单盒 (oneboxes) 上显示实时状态指示器。当 GitHub 上的 PR 发生变化时，状态会通过 Webhook 自动更新。
状态类型
| 状态 | 颜色 | 描述 |
|---|---|---|
| 草稿 (Draft) | 灰色 | PR 被标记为草稿 |
| 开放 (Open) | 灰色 | PR 已开放并等待审查 |
| 已批准 (Approved) | 绿色 | PR 已通过审查者批准 |
| 要求修改 (Changes Requested) | 橙色 | 审查者要求修改 |
| 已合并 (Merged) | 紫色 | PR 已合并 |
| 已关闭 (Closed) | 红色 | PR 已关闭但未合并 |
使用方法：
步骤 1：启用功能
前往 管理 > 设置 > 插件，将 github pr status enabled 设置为 true。
步骤 2：配置 GitHub 访问令牌
为了获取 PR 状态（特别是针对私有仓库），请配置 GitHub 访问令牌。
设置项： github onebox access tokens
格式：
组织名称|ghp_your_token_here
default|ghp_fallback_token_here
您可以为每个组织指定令牌，并设置一个 default 令牌作为备用。每行应包含 org_name|token，其中令牌是具有 repo 范围的 GitHub 个人访问令牌（经典版）。
示例：
discourse|ghp_xxxxxxxxxxxxxxxxxxxx
my-company|ghp_yyyyyyyyyyyyyyyyyyyy
default|ghp_zzzzzzzzzzzzzzzzzzzzzz
步骤 3：设置 GitHub Webhook（用于实时更新）
为了在 PR 发生变化时自动更新状态，请在 GitHub 上配置 Webhook。
生成 Webhook 密钥：
openssl rand -hex 32
将生成的密钥设置为 github webhook secret 站点设置。
在 GitHub 上创建 Webhook：
您可以在组织级别（覆盖所有仓库）或每个仓库级别创建 Webhook。
对于组织：
- 进入您的组织设置
- 导航到 Webhooks（在“代码、规划和自动化”下）
- 点击 添加 Webhook
对于仓库：
- 进入您的仓库设置
- 导航到 Webhooks
- 点击 添加 Webhook
Webhook 配置：
| 字段 | 值 |
|---|---|
| Payload URL | https://your-discourse-site.com/discourse-github/webhooks/github |
| 内容类型 | application/json |
| 密钥 | 您生成的 Webhook 密钥 |
| SSL 验证 | 启用（推荐） |
| 事件 | 选择“让我选择单独的事件” |
选择以下事件：
- Pull requests（拉取请求）
- Pull request reviews（拉取请求审查）
点击 添加 Webhook 保存。
步骤 4：验证设置
- 创建一个包含 GitHub PR URL 的测试帖子
- 验证单盒是否显示状态图标
- 在 GitHub 上更改 PR 状态（例如，批准它或关闭它）
- 几秒钟后刷新 Discourse 页面——状态应已更新
您可以在 GitHub 的 Webhook 设置中检查 Webhook 交付状态，以确认事件是否成功发送和接收。
状态优先级
当 PR 具有多个状态（例如，已批准但同时也要求修改）时，状态由以下优先级决定：
- 已合并 (Merged)（最高优先级）
- 已关闭 (Closed)
- 草稿 (Draft)
- 要求修改 (Changes Requested)
- 已批准 (Approved)
- 开放 (Open)（默认）
审查状态逻辑
该功能从 GitHub API 获取审查信息以确定批准状态：
- 获取每位审查者的最新审查
- 忽略“评论”和“待定”的审查状态
- 如果任何审查者要求修改，则显示“要求修改”
- 仅当存在审查且无人要求修改时，才显示“已批准”
适用范围
- 论坛帖子 — 任何包含 GitHub PR 单盒的帖子
- 聊天消息 — 聊天中的 PR 单盒也会显示实时状态
注意：内联单盒（当链接作为文本的一部分出现而非完整预览时）不显示状态图标。
从 GitHub Status 主题组件迁移
此功能替代了 GitHub Status Indicators 主题组件。两者不兼容，不应同时使用。
如果您当前正在使用该主题组件：
- 禁用并移除
github-status-theme主题组件 - 通过
github pr status enabled设置启用此内置功能
配置
GitHub 访问令牌
为了使链接回指功能正常工作并向用户授予徽章，您需要提供 GitHub 访问令牌。您可以在此处生成令牌：Sign in to GitHub · GitHub
链接回指功能需要 public_repo 范围，而授予徽章不需要任何范围（如果只需要徽章，请取消勾选所有内容）。由于 public_repo 范围授予对仓库的写入权限，我们建议您创建一个废弃的 GitHub 账户，该账户不访问任何仓库，仅用于生成令牌。
各功能所需的令牌范围
| 功能 | 所需范围 |
|---|---|
| 徽章 | 不需要范围 |
| 链接回指 | public_repo |
| PR 状态（公共仓库） | 不需要范围 |
| PR 状态（私有仓库） | repo |
站点设置参考
| 设置项 | 默认值 | 描述 |
|---|---|---|
enable discourse github plugin |
false |
插件的主开关 |
github badges enabled |
false |
启用 GitHub 贡献徽章 |
github badges repos |
(空) | 用于跟踪徽章的仓库 URL |
github linkback enabled |
false |
启用从 GitHub 到 Discourse 的链接回指 |
github linkback access token |
(空) | 链接回指功能的访问令牌 |
github linkback projects |
(空) | 要创建链接回指的项目 |
github permalinks enabled |
false |
将 GitHub 链接替换为固定链接 |
github pr status enabled |
false |
在单盒上启用 PR 状态图标 |
github webhook secret |
(空) | 用于 Webhook 签名验证的密钥 |
github onebox access tokens |
(空) | GitHub API 的访问令牌（格式：org|token） |
技术细节
PR 状态 API 使用
生成 GitHub PR 单盒时，Discourse 最多会进行两次 API 调用：
- PR 数据：
GET /repos/{owner}/{repo}/pulls/{number}— 获取基本 PR 信息，包括状态、合并状态和草稿状态 - 审查：
GET /repos/{owner}/{repo}/pulls/{number}/reviews— 获取审查数据以确定批准状态
如果配置了访问令牌，这些调用将使用该令牌，从而允许访问私有仓库。
Webhook 安全性
Webhook 请求使用 HMAC-SHA256 签名验证进行验证。GitHub 使用您的密钥对 Webhook 负载进行签名，Discourse 在处理之前会验证此签名。无效的签名将以 403 响应被拒绝。
触发更新的 Webhook 事件
- PR 状态变更（打开、关闭、重新打开）
- PR 已合并
- 草稿状态变更（转换为草稿、准备审查）
- 提交拉取请求审查
- 审查被编辑或驳回
性能考虑
- 重新烘焙（Rebaking）被排列为低优先级的后台作业，以避免影响网站性能
- 仅对包含完整 GitHub PR 单盒的帖子/消息进行重新烘焙（跳过内联单盒）
- 聊天消息的重新烘焙会跳过通知，以防止重复警报
更新日志
2025-12-10
- 修复：在从 GitHub Webhook 重新烘焙聊天消息时跳过通知
2025-12-09
- 修复：跳过重新烘焙包含内联 GitHub PR 单盒的帖子
- 修复：避免在重新烘焙包含单盒的帖子时出现中间状态
- 修复：当 GitHub PR 状态变更时重新烘焙聊天消息
- 用户体验：使用最小高度以防止状态图标变更时的布局偏移
- 用户体验：减小移动端 GitHub PR 状态图标的大小
2025-12-08
- 功能：在 GitHub PR 单盒中添加“要求修改”状态
2025-12-04
- 功能：GitHub PR 实时状态图标
2025-11-10
- 功能：允许和拒绝链接回指的列表
2025-11-08
- 功能：为 GitHub 链接回指添加类别忽略列表
2024-12-20
- 开发：将 discourse-github 移至核心（不再需要单独安装）
此插件现已作为