GitHub 集成
Jamdesk 使用两种 GitHub 连接：GitHub App 用于仓库访问，个人账户链接用于构建归属。
Jamdesk 使用两种独立的 GitHub 连接，各自承担不同的任务。本页面介绍每种连接的作用，以及何时需要使用它。
**简而言之：**GitHub App 让 Jamdesk 访问您的仓库。关联个人账户可确保您的提交归属于您。
Bitbucket Cloud 项目的工作方式不同：单个 OAuth 授权即可涵盖仓库访问、Webhook 和构建归属。请参阅连接 Bitbucket。
概览
| 连接 | 用途 | 范围 | 必需？ |
|---|---|---|---|
| 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 的项目设置 → Git 仓库中选择仓库和分支。之后的工作方式相同。
一个 App，多个项目
单个 GitHub App 安装可以支持多个 Jamdesk 项目：
- 在您的账户或组织中安装一次 App
- 将不同仓库连接到不同的 Jamdesk 项目
- 每个项目都有自己的分支和路径配置
对于组织，管理员只需安装一次 GitHub App。之后，任何团队成员都可以使用该 App 有权访问的仓库创建 Jamdesk 项目。
个人 GitHub 账户（用户级）
关联您的个人 GitHub 账户会将您的 GitHub 身份与 Jamdesk 个人资料关联起来。这与 GitHub App 相互独立。
功能
- 识别您 - 将您的 GitHub 用户名与 Jamdesk 账户关联
- 标记构建归属 - 显示触发每次部署的用户
- 团队可见性 - 其他团队成员可以看到谁进行了更改
为什么需要它
当您推送到 GitHub 时，Jamdesk 需要确定哪个用户触发了构建。如果未关联您的账户：
- Jamdesk 会退回到通过电子邮件地址匹配
- 如果您的 Git 提交邮箱与 Jamdesk 邮箱不同，则无法标记归属
- 构建历史记录中可能会为您的提交显示“未知用户”
**常见问题：**您的 Git 配置使用个人邮箱，但您注册 Jamdesk 时使用了工作邮箱。关联您的 GitHub 账户可确保正确标记归属。
检查您的 Git 邮箱
git config user.email
git config --global user.email "you@company.com"使用与 Jamdesk 账户中显示的相同邮箱，避免构建历史记录中的归属显示为“未知用户”。
如何关联您的账户
点击右上角的头像，然后选择 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 项目不受影响
- 您的个人账户链接不受影响
**使用时机：**您想连接其他仓库，或暂时停止部署。
**重新连接方法：**前往项目设置 → Git 仓库，然后选择一个仓库。
取消关联 GitHub（用户设置）
**功能：**从您的 Jamdesk 个人资料中移除 GitHub 身份。
影响：
- 您的 GitHub 用户名不再显示在个人资料中
- 构建归属会退回到通过邮箱匹配
- 所有仓库连接仍然保留
- GitHub App 仍保持安装状态
**使用时机：**您想关联其他 GitHub 账户，或移除该连接。
**重新关联方法：**前往用户设置 → GitHub 账户 → 关联 GitHub 账户。
卸载 GitHub App（在 GitHub 中）
**功能：**完全移除 Jamdesk 对您 GitHub 账户的访问权限。
影响：
- 使用此安装的所有 Jamdesk 项目都会失去访问权限
- 所有受影响项目的自动部署都会停止
- Webhook 会被移除
- 个人账户链接不受影响
只有在您想移除 Jamdesk 对所有仓库的访问权限时，才应卸载 GitHub App。这会影响连接到您 GitHub 账户的每个 Jamdesk 项目。
卸载方法：
- 前往 GitHub Settings → Applications → Installed GitHub Apps
- 找到“Jamdesk”，然后点击 Configure
- 向下滚动并点击 Uninstall
快速参考
| 操作 | 位置 | 范围 | 可逆？ |
|---|---|---|---|
| 断开 GitHub | 项目设置 → Git 仓库 | 单个项目 | 是 - 随时重新连接 |
| 取消关联 GitHub | 用户设置 → GitHub 账户 | 您的账户 | 是 - 随时重新关联 |
| 卸载 GitHub App | GitHub 设置 | 所有项目 | 是 - 重新安装 |
故障排除
“已经安装 Jamdesk？”
如果您之前已经安装过 Jamdesk GitHub App，点击“Install GitHub App”会将您带到 GitHub 设置页面，而不是安装页面。这是正常现象！请按以下步骤完成设置：
在 GitHub 设置页面向下滚动到 Repository access 部分。
如果 Save 按钮处于禁用状态（灰色），请从“All repositories”切换到“Only select repositories”，然后再切换回来。
点击绿色的 Save 按钮。Jamdesk 会检测到更改并继续设置。
弹出窗口被阻止
如果 GitHub 弹出窗口没有打开，您的浏览器可能阻止了它。在地址栏中找到弹出窗口拦截器图标，允许来自 Jamdesk 的弹出窗口，然后点击 Try Again。
“我的构建显示‘未知用户’”
您的个人 GitHub 账户尚未关联。前往用户设置 → 关联 GitHub 账户。
“找不到仓库”
GitHub App 无权访问该仓库。前往 GitHub Settings，找到 Jamdesk，然后添加该仓库。
“构建没有触发”
- 检查仓库是否已在项目设置 → Git 仓库中连接
- 确认您推送到的是配置的分支
- 在 GitHub 仓库设置中检查 Webhook 投递情况
“我无法访问组织仓库”
组织管理员必须批准 GitHub App 的安装。请让管理员在组织设置中安装或批准 Jamdesk。
“GitHub 一直把我带回 Jamdesk App 页面”
您的公司可能管理着您的 GitHub 账户，而 GitHub 不允许这类账户在自己的账户中安装 App。请参阅公司管理的 GitHub 账户来解决此问题。