> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> 直接在你的代码仓库中与 Devin 一起工作

<div id="why-integrate-devin-with-github">
  ## 为什么要将 Devin 与 GitHub 集成？
</div>

将 Devin 与你的 GitHub 组织集成后，Devin 就可以创建 Pull Request (PR) 、回复 PR 评论，并直接在你的代码仓库中协作。这样，Devin 就能作为你工程团队中的正式贡献者参与工作。

要开始使用，请前往 [app.devin.ai](http://app.devin.ai) > **Settings** > **Integrations** > **GitHub**，点击 **Add Connection**，并按照提示进行操作。你需要选择 Devin 可以访问的代码仓库，并审核所需的权限。

<Note>
  **在使用 GitHub Enterprise Server，或启用了数据驻留的 GitHub Enterprise Cloud？** 请参阅 [GitHub Enterprise Server Integration guide](/zh/enterprise/integrations/github-enterprise-server)，了解配置说明。
</Note>

<div id="setting-up-the-integration">
  ## 设置集成
</div>

<Tip>要创建和管理 Devin 集成，您必须是 GitHub 组织的管理员。遇到问题？请查看我们的[常见问题](/zh/admin/common-issues#i-m-unable-to-connect-my-github-organization)。</Tip>

1. 在您的 Devin 账户中访问 [app.devin.ai](http://app.devin.ai)，导航到 **Settings** > **Integrations** > **GitHub**，然后点击 **Add Connection**。

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/Add-GitHub-Connection.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=6a5120cb74d52c7b9abbd09cc4849dc5" alt="Devin" width="1264" height="1474" data-path="images/integrations/Add-GitHub-Connection.png" />
</Frame>

2. 如果您尚未登录 GitHub，系统会提示您进行身份验证。

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/GitHub-Authenticate.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=1318f858b4f4e65aceb84f5583acf119" alt="Devin" width="1004" height="1380" data-path="images/integrations/GitHub-Authenticate.png" />
</Frame>

3. 选择您希望连接到 Devin 的 GitHub 组织。

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/GitHub-Select-Organization.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=9344af98e3c15f1a3db3543e58082935" alt="Devin" width="1296" height="726" data-path="images/integrations/GitHub-Select-Organization.png" />
</Frame>

4. 选择是否授予 Devin 对 **All repositories** 或 **Select repositories** 的访问权限，以控制 Devin 可访问的代码仓库范围。

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/GitHub-Grant-Repository-Permissions.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=997ba548f0face4b855e62a03b826b09" alt="Devin" width="1004" height="652" data-path="images/integrations/GitHub-Grant-Repository-Permissions.png" />
</Frame>

5. 完成 GitHub 授权后，系统会将您重定向回 Devin 的设置页面，您可以在该页面确认集成已激活。

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/GitHub-Connected.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=bbfa1d3dcfcdf40bf9a13bccf85af0f9" alt="Devin" width="1212" height="326" data-path="images/integrations/GitHub-Connected.png" />
</Frame>

<Tip>我们建议在主分支上启用分支保护规则，以确保在 Devin 合并更改之前，所有必需的检查都已通过。</Tip>

<div id="using-devin-with-the-github-integration">
  ## 使用 Devin 的 GitHub 集成
</div>

<div id="for-core-and-teams-users">
  ### 针对 Core 和 Teams 用户
</div>

完成集成配置后，你可以在 Devin Web 应用中的提示中直接使用 @ 提及代码仓库。

<div id="for-enterprise-users">
  ### 适用于 Enterprise 用户
</div>

完成集成配置后，你可以在 **Enterprise Settings** > **Repository Permissions** 中，将代码仓库分配给特定组织。

<Frame>
  <img src="https://mintcdn.com/cognitionai/IRy9C2mAI1Fl2Qc9/images/enterprise/Enterprise-Add-Repositories.png?fit=max&auto=format&n=IRy9C2mAI1Fl2Qc9&q=85&s=5d056bf93a6f544b0f5893692f365b2b" alt="Devin" width="2360" height="1322" data-path="images/enterprise/Enterprise-Add-Repositories.png" />
</Frame>

<Tip>
  如果你是首次使用某个代码仓库，我们建议先完成[在引导流程中设置开发环境](/zh/onboard-devin/environment)，以确保 Devin 获取到关于你的代码库的准确且最新的信息。只要会话尚未被归档，Devin 会自动回复 PR 评论。
</Tip>

<div id="managing-devins-permissions-in-github">
  ## 在 GitHub 中管理 Devin 的权限
</div>

在设置过程中，你可以授予 Devin 访问你组织中**所有仓库**的权限，或将其访问范围限制为**特定仓库**。

你可以随时通过 GitHub 的设置调整仓库访问权限：

1. 前往你的 GitHub 组织的 **Settings** > **GitHub Apps** (例如：`https://github.com/organizations/<org_name>/settings/installations`)
2. 找到 Devin.ai 集成并选择 **Configure**
3. 在 **Repository access** 中，选择授予对所有仓库的访问权限，或仅选择特定仓库
4. 点击 **Save** 以应用更改

<Frame>
  <img src="https://mintcdn.com/cognitionai/wcZUamn7iKJ5mKOX/images/integrations/GitHub-Manage-Devin-Permissions.png?fit=max&auto=format&n=wcZUamn7iKJ5mKOX&q=85&s=952f1f5df1f6311a1e80ff230bb7f429" alt="Devin" width="1984" height="1542" data-path="images/integrations/GitHub-Manage-Devin-Permissions.png" />
</Frame>

Devin 需要以下权限：

对以下项目的\*\*读取 (Read) \*\*访问权限：

| Permission                       | Description                                     |
| -------------------------------- | ----------------------------------------------- |
| `dependabot alerts`              | 允许 Devin 代表你处理 Dependabot 警报 (例如升级依赖版本)         |
| `actions`                        | 允许 Devin 查看为仓库配置的 actions，以便了解 Devin 的更改是否通过 CI |
| `deployments`                    | 允许 Devin 查看仓库的哪些版本已被部署                          |
| `metadata`                       | 允许 Devin 查看关于仓库的重要元数据，例如仓库所有者                   |
| `packages`                       | 允许 Devin 查看仓库的哪些版本被发布为 package                  |
| `pages`                          | 允许 Devin 查看与仓库关联的 pages，例如用于查看文档                |
| `repository security advisories` | 允许 Devin 查看与仓库相关的安全公告，以便帮助修复安全问题                |
| `members`                        | 允许 Devin 查看组织的成员                                |
| `webhooks`                       | 允许 Devin 查看为仓库配置的 webhooks，例如 lint 和类型检查        |

对以下项目的\*\*读取 (Read) **和**写入 (Write) \*\*访问权限：

| Permission        | Description                                    |
| ----------------- | ---------------------------------------------- |
| `checks`          | 允许 Devin 查看并上报仓库的检查结果，以便了解并告知 Devin 的更改是否通过 CI |
| `commit statuses` | 允许 Devin 查看并设置提交状态，以指示某次提交是否通过 CI              |
| `contents`        | 允许 Devin 向代码库提交更改                              |
| `discussions`     | 允许 Devin 参与 discussions                        |
| `issues`          | 允许 Devin 创建新的 issues                           |
| `pull requests`   | 允许 Devin 创建新的 PR                               |
| `projects`        | 允许 Devin 查看和管理与仓库关联的 projects，例如获取某个任务的信息      |
| `workflows`       | 允许 Devin 设置新的 workflows，例如帮助配置 CI/CD           |

这些权限使 Devin 能够像普通贡献者一样在你的仓库中工作——推送分支、打开 PR，并参与 PR 讨论。

<div id="pull-request-templates">
  ## Pull Request 模板
</div>

当 Devin 创建 Pull Request 时，它会使用你仓库中的模板来组织 PR 描述。如果你提供了模板，Devin 在向 GitHub 提交 PR 时会遵循该模板的格式。

<div id="devin-specific-template-recommended">
  ### Devin 专用模板 (推荐)
</div>

你可以在下方任一受支持的 `PULL_REQUEST_TEMPLATE` 位置添加一个名为 `devin_pr_template.md` 的文件，为 Devin 提供单独的模板，而无需修改你面向人工审核的默认模板。如果你希望 Devin 包含额外的上下文信息 (例如审阅者检查清单或已修改文件的 Mermaid 图表) ，这会特别有用。

<div id="template-search-order">
  ### 模板查找顺序
</div>

Devin 会按以下顺序查找模板，并使用第一个匹配项：

1. PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
2. docs/PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
3. .github/PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
4. pull\_request\_template.md
5. docs/pull\_request\_template.md
6. .github/pull\_request\_template.md

如果未找到任何模板，Devin 会使用其默认的 PR 描述格式。

<Tip>如果你希望 Devin 使用你现有的 `pull_request_template.md`，请将其复制或创建符号链接到上述任一 `devin_pr_template.md` 路径。</Tip>

<Info>有关 GitHub pull request 模板的更多信息 (支持的位置、多模板、查询参数等) ，请参阅 GitHub 文档 (GitHub Docs) ：<a href="https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository" target="_blank" rel="noopener noreferrer">为你的仓库创建 pull request 模板</a>。</Info>

<div id="commit-signing">
  ### 提交签名
</div>

要使用 GPG 为 Devin 的提交签名，请在你的[环境](/zh/onboard-devin/environment/blueprints)中配置该密钥，以便它能在不同会话间持续保留。在会话终端中生成密钥是行不通的——每个 Devin 会话都会从 machine image 的 fresh copy 启动，因此在会话过程中创建的任何密钥都会在会话结束时被丢弃。

<Warning>
  通过环境配置进行 GPG 签名，只有在 Devin 是*提交作者*时才会生成 **Verified**
  提交。GitHub 会根据作者身份验证签名；但在任何**提交作者模式**下，只要作者是发起
  请求的用户 (例如 "Co-authored"、"User only"、"User as author, Devin as
  committer") ，Devin 就会在每个会话中用各用户自己的邮箱覆盖 `user.email`——
  这就无法与单个共享 GPG 密钥匹配。在依赖此设置之前，请将你的 org 的[提交作者模式](https://app.devin.ai/settings/profile)
  设置为 **"Devin only"** 或 **"Devin as author, user as committer"**。
</Warning>

请在 **org-wide** 层 (如果你的所有 orgs 都需要，则在 **enterprise** 层) 进行此设置，以便每个 repo 都能获得已签名提交配置：

1. 创建 (或选择) 一个专用的 GitHub 用户账户，由它同时拥有提交作者身份 *以及* Devin 用来推送的凭据——例如 `devin@company.com`。同一个账户同时承担这两项职责会让签名设置更简单；如果使用两个账户，则需要将下文所述配置拆分到两边。
2. 在本地使用该账户的邮箱作为 UID 生成一个 GPG 密钥，并按照 [GitHub 的指示](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)操作。
3. 将**公钥**上传到与 GPG UID 匹配的已验证邮箱所属的 GitHub 账户中，位置为 [GitHub Settings > SSH and GPG keys](https://github.com/settings/keys)。GitHub 会根据 *提交作者* 身份验证签名，而不是根据推送身份——公钥必须存在于拥有 `user.email` 中该邮箱的账户上。 (如果这正是你用于推送的同一个专用账户，那么这一步只需执行一次。)
4. 导出**私钥**，将其进行 base64 编码，并将它 (以及对应的 `GIT_USER_NAME` / `GIT_USER_EMAIL`) 作为 secrets 添加到 [Settings > Secrets](https://app.devin.ai/settings/secrets)。
5. 在你的[org-wide 环境配置](https://app.devin.ai/settings/environment)中导入该密钥，并在每次会话启动时启用签名。完整 YAML 请参见可直接复制粘贴的 [GPG commit signing example](/zh/onboard-devin/environment/templates#gpg-commit-signing)。

<Tip>
  提交者邮箱 (`user.email`) 必须与 GPG 密钥上的某个 UID 匹配，同时该邮箱还必须是你上传公钥所在 GitHub 账户上的已验证邮箱。如果这三者中有任何一个不匹配，GitHub 都会将该提交显示为
  **Unverified**，即使签名本身是有效的。
</Tip>

<div id="security-considerations">
  ### 安全注意事项
</div>

* **分支保护：** 我们建议在主分支上启用分支保护规则，以确保在 Devin 合并更改之前，所有必需的检查都已通过。
* **组织级权限：** Devin 使用授予组织级别的权限，而不是运行会话的个人用户的权限。
* **一致的访问控制：** 所有同时加入 GitHub 组织和 Devin 组织的用户，共享相同的 Devin 集成权限。
* **仓库创建：** Devin 无法在你的 GitHub 账户中创建新的仓库。

<div id="ip-allowlisting">
  ## IP 白名单
</div>

如果你的组织在访问 GitHub 时需要配置 IP 白名单，请将以下 IP 地址加入允许列表：

* 100.20.50.251
* 44.238.19.62
* 52.10.84.81
* 52.183.72.253
* 20.172.46.235
* 52.159.232.99
* 4.204.199.103
* 54.201.200.193
* 54.69.238.189
* 100.23.34.160

<Note>这些 IP 地址可能会在未来更新中发生变化。我们建议你关注我们的发行说明，以便了解任何变更。</Note>

<div id="troubleshooting-github-organization-connected-to-the-wrong-devin-organization">
  ## 故障排查：GitHub organization 连接到了错误的 Devin organization
</div>

如果你的 GitHub organization 已经连接到一个你无权访问的 Devin organization，GitHub org admin 可以移除现有安装，并将其重新安装到另一个 Devin organization 下。

<Warning>我们建议在移除安装前，先与当前 Devin organization 的所有者确认。</Warning>

1. 前往 [github.com/settings/installations](https://github.com/settings/installations)，然后点击 **Devin.ai Integration** 旁边的 **Configure**。

   如有需要，可使用右上角的 **Go to settings page** 下拉菜单切换到正确的 GitHub organization context。

   <Frame>
     <img src="https://mintcdn.com/cognitionai/fbV8dpDB0lpUNhsC/images/integrations/GitHub-Settings-Switch-Context.png?fit=max&auto=format&n=fbV8dpDB0lpUNhsC&q=85&s=833e7727b53d26f19addeba7320393cd" alt="切换 GitHub 设置 context" width="788" height="192" data-path="images/integrations/GitHub-Settings-Switch-Context.png" />
   </Frame>

2. 在安装页面中，滚动到 **Danger zone** 部分并点击 **Uninstall**，从 GitHub organization 中移除 Devin.ai Integration。

   <Frame>
     <img src="https://mintcdn.com/cognitionai/fbV8dpDB0lpUNhsC/images/integrations/GitHub-Uninstall-App.png?fit=max&auto=format&n=fbV8dpDB0lpUNhsC&q=85&s=fa31cff537e8b97f3c74da8dcc536980" alt="卸载 Devin.ai Integration" width="1095" height="839" data-path="images/integrations/GitHub-Uninstall-App.png" />
   </Frame>

3. 返回 [app.devin.ai](https://app.devin.ai) 并刷新页面。现在，你可以在你的 Devin organization 下重新安装 GitHub integration。

<div id="github-integration-faqs">
  ## GitHub 集成常见问题
</div>

<AccordionGroup>
  <Accordion title="我可以将个人 GitHub 账号连接到我们组织的 Devin 账号吗？" icon="user">
    可以。用户可以将 GitHub 组织账号或个人 GitHub 账号连接到其 Devin 组织。不过，我们建议连接具备 Devin 访问团队所需代码仓库的相应权限的账号。
  </Accordion>

  <Accordion title="GitHub 应用如何处理用户认证？" icon="shield-halved">
    只有安装了该 GitHub 集成的组织成员，才能在其 Devin 会话中使用该集成。Devin 会根据用户的组织成员身份继承对该 GitHub 集成的访问权限。
  </Accordion>

  <Accordion title="Devin 如何管理和轮换加密密钥？" icon="binary">
    加密密钥由 AWS KMS 管理，并会定期轮换。
  </Accordion>
</AccordionGroup>