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 提交上显示构建状态
工作方式
项目设置会引导您连接 GitHub。请选择以下两种方式之一。
创建入门文档仓库（新项目的默认选项）
授权 Jamdesk 在您的账户或组织下创建仓库。
选择您的个人账户或某个组织。Jamdesk 会创建一个预填入入门文档的新仓库。
安装 Jamdesk GitHub App（或授予其对新仓库的访问权限）。该应用会构建并自动部署您的文档。
每次推送到您配置的分支都会自动触发部署。您可随时自定义入门文档。
连接现有仓库
安装 Jamdesk GitHub App，并授予其对您的文档仓库的访问权限。然后在 Jamdesk 中前往 Project Settings → Git Repository 选择仓库和分支。其余步骤相同。
一个 App，多个项目
一次 GitHub App 安装可以服务于多个 Jamdesk 项目：
- 在您的账户或组织上只需安装一次应用
- 将不同的仓库连接到不同的 Jamdesk 项目
- 每个项目都有各自的分支和路径配置
组织管理员只需安装一次 GitHub App。之后任何团队成员都可以从该应用有权访问的仓库中创建 Jamdesk 项目。
个人 GitHub 账户（用户级）
关联您的个人 GitHub 账户会将您的 GitHub 身份与您的 Jamdesk 个人资料相关联。这与 GitHub App 是分开的。
功能
- 识别您：将您的 GitHub 用户名与您的 Jamdesk 账户关联
- 归属构建：显示是谁触发了每次部署
- 团队可见性：队友可以看到是谁做出了更改
为什么需要它
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 项目不受影响
- 您的个人账户关联不受影响
何时使用： 您想连接其他仓库，或暂时停止部署。
如何重新连接： 前往 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 部分。
如果保存按钮被禁用（灰色），请从 "All repositories" 切换到 "Only select repositories"，然后再切换回来。
点击绿色的 Save 按钮。Jamdesk 会检测到更改并继续设置。
弹出窗口被阻止
如果 GitHub 弹窗没有打开，您的浏览器可能已将其拦截。请在地址栏中查找弹窗拦截图标，允许来自 Jamdesk 的弹窗，然后点击 Try Again。
“我的构建显示‘未知用户’”
您的个人 GitHub 账户未关联。请前往 User Settings → Link GitHub Account。
“找不到仓库”
GitHub App 没有该仓库的访问权限。请前往 GitHub Settings，找到 Jamdesk，并添加该仓库。
“构建没有触发”
- 检查仓库是否已在 Project Settings → Git Repository 中连接
- 确认您正在推送到已配置的分支
- 在 GitHub 仓库设置中检查 Webhook 投递情况
如果以上都正常，那么推送者可能不是该项目的成员。Jamdesk 仅为项目成员的推送进行构建。它通过其关联的 GitHub 账户，或其提交邮箱与其登录 Jamdesk 所用邮箱是否一致来匹配推送者。
如果没有匹配，构建会显示为失败并附上原因。项目所有者会收到一封邮件，每人每周最多一封。推送内容未涉及您文档文件夹的，不会发送邮件。
请在 Project Settings → Members 中使用其提交邮箱邀请该成员。他们需要使用该邮箱登录 Jamdesk 以接受邀请。如果他们已经是成员，可以在 User Settings 中关联其 GitHub 账户。
“我无法访问组织仓库”
组织管理员必须批准 GitHub App 的安装。请让管理员在组织设置中安装或批准 Jamdesk。
“GitHub 一直把我带回 Jamdesk App 页面”
您的公司可能管理着您的 GitHub 账户。GitHub 不允许受管账户为自己安装应用。修复方法请参阅公司管理的 GitHub 账户。