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