GitHub 集成
Jamdesk 使用两种 GitHub 连接：用于访问仓库的 GitHub App，以及用于构建归属的个人账户链接。
Jamdesk 使用两种独立的 GitHub 连接，各自承担不同的任务。本页将说明每种连接的作用及其使用时机。
**简要说明：**GitHub App 允许 Jamdesk 访问您的仓库。关联个人账户可确保您的提交归属于您本人。
概览
| 连接 | 用途 | 范围 | 是否必需？ |
|---|---|---|---|
| GitHub App | 访问仓库和 Webhook | 每个项目 | 是 |
| 个人账户 | 用户身份和归属 | 每个用户 | 建议 |
GitHub App（项目级别）
Jamdesk GitHub App 安装在您的 GitHub 账户或组织中。它授予 Jamdesk 访问特定仓库的权限。
功能
- 读取仓库内容 - 克隆您的文档以进行构建
- 接收 Webhook - 在您推送更改时收到通知
- 报告构建状态 - 在提交上显示部署状态
为什么需要它
如果未安装 GitHub App，Jamdesk 将无法：
- 访问您的仓库以构建文档
- 在您推送更改时自动部署
- 在 GitHub 提交上显示构建状态
工作方式
设置项目时，Jamdesk 会引导您连接 GitHub。您可以选择以下两种方式之一。
创建入门文档仓库（新项目默认选项）
授权 Jamdesk，使其能够在您的账户或组织中创建仓库。
选择您的个人账户或组织。Jamdesk 会创建一个预填入入门文档的新仓库。
安装 Jamdesk GitHub App（或授予其访问新仓库的权限），以便它能够构建并自动部署您的文档。
每次推送到已配置的分支都会自动触发部署。准备好后，您可以自定义入门文档。
连接现有仓库
已经有文档仓库？安装 Jamdesk GitHub App，授予其访问该仓库的权限，然后在 Jamdesk 的 Project Settings → Git Repository 中选择仓库和分支。之后的工作方式相同。
一个 App，多个项目
一次 GitHub App 安装可以为多个 Jamdesk 项目提供支持：
- 在您的账户或组织中安装一次 App
- 将不同仓库连接到不同的 Jamdesk 项目
- 每个项目都有自己的分支和路径配置
对于组织，管理员只需安装一次 GitHub App。之后，任何团队成员都可以使用该 App 有权访问的仓库创建 Jamdesk 项目。
个人 GitHub 账户（用户级别）
关联个人 GitHub 账户会将您的 GitHub 身份与 Jamdesk 个人资料关联起来。这与 GitHub App 相互独立。
功能
- 识别您 - 将您的 GitHub 用户名与 Jamdesk 账户关联
- 标记构建归属 - 显示触发每次部署的用户
- 团队可见性 - 其他团队成员可以查看是谁进行了更改
为什么需要它
当您向 GitHub 推送时，Jamdesk 需要确定是哪位用户触发了构建。如果未关联您的账户：
- Jamdesk 会回退到通过电子邮件地址匹配
- 如果您的 Git 提交邮箱与 Jamdesk 邮箱不同，归属识别将失败
- 构建历史中可能会在您的提交旁显示“Unknown user”
**常见问题：**您的 Git 配置使用个人邮箱，但注册 Jamdesk 时使用的是工作邮箱。关联您的 GitHub 账户可确保正确识别归属。
检查 Git 邮箱
git config user.email
git config --global user.email "you@company.com"使用与 Jamdesk 账户中显示的相同邮箱，避免构建历史中的归属显示为“Unknown user”。
关联账户
点击右上角的头像，然后选择 User Settings。
滚动到 GitHub Account 卡片。
此时会打开 GitHub 弹窗。授权 Jamdesk 读取您的个人资料。
您的 GitHub 用户名会显示在 Jamdesk 个人资料中。
两者如何协同工作
可以将它们看作两把独立的钥匙：
| 密钥 | 打开 | 所有者 |
|---|---|---|
| GitHub App | 访问仓库 | 项目/组织 |
| 个人链接 | 您的身份 | 个人用户 |
团队示例
假设一个团队中有 3 名开发者共同维护公司文档：
- 管理员在组织中安装 GitHub App
- 管理员创建连接到文档仓库的 Jamdesk 项目
- 每位开发者关联自己的个人账户
现在，无论哪位开发者进行推送：
- GitHub App 允许 Jamdesk 读取仓库并执行构建
- 个人链接 识别触发构建的用户
独立开发者示例
即使您是独立开发者，这两种连接也承担不同的作用：
- GitHub App - 将您的仓库连接到 Jamdesk
- 个人链接 - 确保构建历史中显示您的姓名和提交
断开连接与取消关联
每项操作都会移除不同部分的访问权限。以下是每项操作的影响。
断开 GitHub 连接（项目设置）
**功能：**移除单个 Jamdesk 项目与仓库之间的连接。
影响：
- 该项目的自动部署会停止
- GitHub App 仍安装在 GitHub 中
- 其他 Jamdesk 项目不受影响
- 您的个人账户链接不受影响
**使用时机：**您想连接其他仓库，或暂时停止部署。
**重新连接方法：**前往 Project Settings → Git Repository，然后选择一个仓库。
取消 GitHub 关联（用户设置）
**功能：**从您的 Jamdesk 个人资料中移除 GitHub 身份。
影响：
- 您的 GitHub 用户名不再显示在个人资料中
- 构建归属会回退到电子邮件匹配
- 所有仓库连接保持不变
- GitHub App 仍保持安装状态
**使用时机：**您想关联其他 GitHub 账户，或移除该连接。
**重新关联方法：**前往 User Settings → GitHub Account → Link GitHub Account。
卸载 GitHub App（在 GitHub 中）
**功能：**完全移除 Jamdesk 对您 GitHub 账户的访问权限。
影响：
- 使用此安装的所有 Jamdesk 项目都会失去访问权限
- 所有受影响项目的自动部署都会停止
- Webhook 会被移除
- 个人账户链接不受影响
只有在您想移除 Jamdesk 对所有仓库的访问权限时，才卸载 GitHub App。此操作会影响连接到您 GitHub 账户的每个 Jamdesk 项目。
卸载方法：
- 前往 GitHub Settings → Applications → Installed GitHub Apps
- 找到“Jamdesk”，然后点击 Configure
- 向下滚动并点击 Uninstall
快速参考
| 操作 | 位置 | 范围 | 是否可逆？ |
|---|---|---|---|
| 断开 GitHub 连接 | Project Settings → Git Repository | 单个项目 | 是 - 可随时重新连接 |
| 取消 GitHub 关联 | User Settings → GitHub Account | 您的账户 | 是 - 可随时重新关联 |
| 卸载 GitHub App | GitHub Settings | 所有项目 | 是 - 可重新安装 |
故障排除
“已经安装 Jamdesk？”
如果您之前安装过 Jamdesk GitHub App，点击“Install GitHub App”后会转到 GitHub 的设置页面，而不是安装页面。这是正常现象！完成设置的方法如下：
在 GitHub 设置页面向下滚动到 Repository access 部分。
如果 Save 按钮处于禁用状态（灰色），请从“All repositories”切换到“Only select repositories”，然后再切换回来。
点击绿色的 Save 按钮。Jamdesk 会检测到更改并继续设置。
弹窗被阻止
如果 GitHub 弹窗没有打开，可能是浏览器阻止了它。请在地址栏中找到弹窗拦截器图标，允许来自 Jamdesk 的弹窗，然后点击 Try Again。
“我的构建显示‘Unknown user’”
您的个人 GitHub 账户尚未关联。前往 User Settings → Link GitHub Account。
“没有显示仓库”
GitHub App 无权访问该仓库。前往 GitHub Settings，找到 Jamdesk，然后添加该仓库。
“构建没有触发”
- 检查仓库是否已在 Project Settings → Git Repository 中连接
- 确认您推送到了已配置的分支
- 在 GitHub 仓库设置中检查 Webhook 投递情况
“我无法访问组织仓库”
组织管理员必须批准 GitHub App 的安装。请管理员在组织设置中安装或批准 Jamdesk。