连接 GitHub
将 GitHub 仓库连接到 Jamdesk，实现推送时自动部署，涵盖应用安装、仓库选择和分支配置。
Jamdesk 集成 GitHub，可在您推送更改时自动部署文档。
屏幕截图显示的是英文界面。
有关 GitHub App 与个人账户关联如何协同工作的背景信息，请参阅了解 GitHub 集成。
安装 GitHub App
首次登录 Jamdesk 时，系统会提示您安装 Jamdesk GitHub App。此应用支持以下功能：
- Repository access - 读取文档内容
- Webhooks - 在推送时触发构建
- Commit status - 在提交上显示构建状态
权限
Jamdesk GitHub App 请求以下权限：
| 权限 | 用途 |
|---|---|
| Repository contents (read) | 克隆并读取文档文件 |
| Metadata (read) | 列出仓库和分支 |
| Webhooks | 接收推送通知 |
Jamdesk 只会访问您明确授予其访问权限的仓库。您可以随时在 GitHub 设置中修改访问权限。
连接仓库
1
选择仓库创建或编辑项目时，点击 Connect Repository。
从已安装 GitHub App 的仓库中进行选择。
2
选择分支选择要部署的分支：
- main 或 master - 最常用于生产文档
- docs - 如果您将文档保存在单独的分支中
- 任意分支 - 用于预览部署
3
指定文档路径如果 docs.json 不在仓库根目录中，请指定路径：
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs package如果 docs.json 位于根目录中，请留空。
连接后，项目仪表板会显示已关联的仓库和分支：
自动部署
连接后，您每次向已配置分支推送时，都会触发构建：
git add .
git commit -m "Update API documentation"
git push origin main构建通常需要 30–90 秒完成。您可以在仪表板或 GitHub 提交中查看状态。
更换仓库
如需连接其他仓库：
- 转到 Settings → Repository
- 点击 Change Repository
- 选择新的仓库和分支
更换仓库可能会影响在线文档。新仓库必须包含有效的 Jamdesk 配置。
管理 GitHub App 访问权限
控制 Jamdesk 可以访问哪些仓库：
- 转到 github.com/settings/installations
- 在列表中找到 Jamdesk
- 点击 Configure
- 在“Repository access”下，选择特定仓库或全部仓库
组织仓库
对于组织仓库，组织管理员必须批准 GitHub App 的安装：
- 在 Jamdesk 仪表板中请求安装
- 管理员会在 GitHub 中收到通知
- 批准后，组织仓库会显示在仓库选择器中
关联个人账户
为确保构建归属准确，请在 User Settings 中关联您的个人 GitHub 账户：
- 点击您的头像 → User Settings
- 找到 GitHub Account 部分
- 点击 Link GitHub Account
此操作独立于 GitHub App，可确保您的提交正确归属于您。了解更多。
故障排除
未显示仓库
- 确认 GitHub App 已安装到该仓库
- 对于组织仓库，确认管理员已批准访问权限
- 尝试在仪表板中刷新仓库列表
未触发构建
- 检查仓库设置中的 Webhook 是否处于活动状态
- 确认您推送到了已配置的分支
- 在 GitHub 中查看 Webhook 投递错误
权限被拒绝错误
- 在 GitHub 设置中重新授权 GitHub App
- 确保 Jamdesk App 可以访问该仓库
如需更详细的故障排除信息，请参阅了解 GitHub 集成。