---
title: GitHub 集成
description: "Jamdesk 使用两种 GitHub 连接：用于访问仓库的 GitHub App，以及用于构建归属的个人账户链接。"
---

> **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 连接**，各自承担不同的任务。本页将说明每种连接的作用及其使用时机。

<Info>
**简要说明：**GitHub App 允许 Jamdesk 访问您的仓库。关联个人账户可确保您的提交归属于您本人。
</Info>

## 概览

| 连接 | 用途 | 范围 | 是否必需？ |
|------------|---------|-------|-----------|
| **GitHub App** | 访问仓库和 Webhook | 每个项目 | 是 |
| **个人账户** | 用户身份和归属 | 每个用户 | 建议 |

## GitHub App（项目级别）

**Jamdesk GitHub App** 安装在您的 GitHub 账户或组织中。它授予 Jamdesk 访问特定仓库的权限。

### 功能

- **读取仓库内容** - 克隆您的文档以进行构建
- **接收 Webhook** - 在您推送更改时收到通知
- **报告构建状态** - 在提交上显示部署状态

### 为什么需要它

如果未安装 GitHub App，Jamdesk 将无法：

- 访问您的仓库以构建文档
- 在您推送更改时自动部署
- 在 GitHub 提交上显示构建状态

### 工作方式

设置项目时，Jamdesk 会引导您连接 GitHub。您可以选择以下两种方式之一。

#### 创建入门文档仓库（新项目默认选项）

<Steps>
  <Step title="Sign in with GitHub">
    授权 Jamdesk，使其能够在您的账户或组织中创建仓库。
  </Step>
  <Step title="Choose where to create it">
    选择您的个人账户或组织。Jamdesk 会创建一个预填入入门文档的新仓库。
  </Step>
  <Step title="Install the GitHub App">
    安装 Jamdesk GitHub App（或授予其访问新仓库的权限），以便它能够构建并自动部署您的文档。
  </Step>
  <Step title="Push triggers builds">
    每次推送到已配置的分支都会自动触发部署。准备好后，您可以自定义入门文档。
  </Step>
</Steps>

#### 连接现有仓库

已经有文档仓库？安装 Jamdesk GitHub App，授予其访问该仓库的权限，然后在 Jamdesk 的 **Project Settings → Git Repository** 中选择仓库和分支。之后的工作方式相同。

### 一个 App，多个项目

一次 GitHub App 安装可以为多个 Jamdesk 项目提供支持：

- 在您的账户或组织中安装一次 App
- 将不同仓库连接到不同的 Jamdesk 项目
- 每个项目都有自己的分支和路径配置

<Tip>
对于组织，管理员只需安装一次 GitHub App。之后，任何团队成员都可以使用该 App 有权访问的仓库创建 Jamdesk 项目。
</Tip>

## 个人 GitHub 账户（用户级别）

关联**个人 GitHub 账户**会将您的 GitHub 身份与 Jamdesk 个人资料关联起来。这与 GitHub App 相互独立。

### 功能

- **识别您** - 将您的 GitHub 用户名与 Jamdesk 账户关联
- **标记构建归属** - 显示触发每次部署的用户
- **团队可见性** - 其他团队成员可以查看是谁进行了更改

### 为什么需要它

当您向 GitHub 推送时，Jamdesk 需要确定是哪位用户触发了构建。如果未关联您的账户：

- Jamdesk 会回退到通过电子邮件地址匹配
- 如果您的 Git 提交邮箱与 Jamdesk 邮箱不同，归属识别将失败
- 构建历史中可能会在您的提交旁显示“Unknown user”

<Warning>
**常见问题：**您的 Git 配置使用个人邮箱，但注册 Jamdesk 时使用的是工作邮箱。关联您的 GitHub 账户可确保正确识别归属。
</Warning>

### 检查 Git 邮箱

```bash
git config user.email
git config --global user.email "you@company.com"
```

使用与 Jamdesk 账户中显示的相同邮箱，避免构建历史中的归属显示为“Unknown user”。

### 关联账户

<Steps>
  <Step title="Go to User Settings">
    点击右上角的头像，然后选择 **User Settings**。
  </Step>
  <Step title="Find GitHub Account section">
    滚动到 **GitHub Account** 卡片。
  </Step>
  <Step title="Click Link GitHub Account">
    此时会打开 GitHub 弹窗。授权 Jamdesk 读取您的个人资料。
  </Step>
  <Step title="Confirm connection">
    您的 GitHub 用户名会显示在 Jamdesk 个人资料中。
  </Step>
</Steps>

## 两者如何协同工作

可以将它们看作两把独立的钥匙：

| 密钥 | 打开 | 所有者 |
|-----|-------|----------|
| GitHub App | 访问仓库 | 项目/组织 |
| 个人链接 | 您的身份 | 个人用户 |

### 团队示例

假设一个团队中有 3 名开发者共同维护公司文档：

1. **管理员在组织中安装 GitHub App**
2. **管理员创建连接到文档仓库的 Jamdesk 项目**
3. **每位开发者关联自己的个人账户**

现在，无论哪位开发者进行推送：

- **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 会被移除
- 个人账户链接不受影响

<Warning>
只有在您想移除 Jamdesk 对**所有**仓库的访问权限时，才卸载 GitHub App。此操作会影响连接到您 GitHub 账户的每个 Jamdesk 项目。
</Warning>

**卸载方法：**
1. 前往 [GitHub Settings → Applications → Installed GitHub Apps](https://github.com/settings/installations)
2. 找到“Jamdesk”，然后点击 **Configure**
3. 向下滚动并点击 **Uninstall**

## 快速参考

| 操作 | 位置 | 范围 | 是否可逆？ |
|--------|----------|-------|-------------|
| **断开 GitHub 连接** | Project Settings → Git Repository | 单个项目 | 是 - 可随时重新连接 |
| **取消 GitHub 关联** | User Settings → GitHub Account | 您的账户 | 是 - 可随时重新关联 |
| **卸载 GitHub App** | GitHub Settings | 所有项目 | 是 - 可重新安装 |

## 故障排除

### “已经安装 Jamdesk？”

如果您之前安装过 Jamdesk GitHub App，点击“Install GitHub App”后会转到 GitHub 的设置页面，而不是安装页面。这是正常现象！完成设置的方法如下：

<Steps>
  <Step title="Find Repository access">
    在 GitHub 设置页面向下滚动到 **Repository access** 部分。
  </Step>
  <Step title="Enable the Save button">
    如果 Save 按钮处于禁用状态（灰色），请从“All repositories”切换到“Only select repositories”，然后再切换回来。
  </Step>
  <Step title="Click Save">
    点击绿色的 **Save** 按钮。Jamdesk 会检测到更改并继续设置。
  </Step>
</Steps>

### 弹窗被阻止

如果 GitHub 弹窗没有打开，可能是浏览器阻止了它。请在地址栏中找到弹窗拦截器图标，允许来自 Jamdesk 的弹窗，然后点击 **Try Again**。

### “我的构建显示‘Unknown user’”

您的个人 GitHub 账户尚未关联。前往 **User Settings → Link GitHub Account**。

### “没有显示仓库”

GitHub App 无权访问该仓库。前往 [GitHub Settings](https://github.com/settings/installations)，找到 Jamdesk，然后添加该仓库。

### “构建没有触发”

1. 检查仓库是否已在 **Project Settings → Git Repository** 中连接
2. 确认您推送到了已配置的分支
3. 在 GitHub 仓库设置中检查 Webhook 投递情况

### “我无法访问组织仓库”

组织管理员必须批准 GitHub App 的安装。请管理员在组织设置中安装或批准 Jamdesk。

## 相关文章

<Columns cols={2}>
  <Card title="创建项目" icon="plus" href="/cn/help/projects/creating">
    设置您的第一个文档项目
  </Card>
  <Card title="构建故障排除" icon="wrench" href="/cn/help/troubleshooting/build-failures">
    常见构建问题及解决方案
  </Card>
</Columns>