本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 正在连接 GitHub
<a name="connecting-to-cicd-pipelines-connecting-github"></a>

GitHub 集成使 AWS DevOps 代理能够在事件调查期间访问代码存储库并接收部署事件。此集成遵循两个步骤的过程：账户级注册 GitHub，然后将特定的存储库连接到各个代理空间。

AWS DevOps 代理支持 GitHub.com (SaaS)、具有数据驻留功能的 GitHub 企业云 (`*.ghe.com`) 和 GitHub 企业服务器（自托管）实例。

## 先决条件
<a name="prerequisites"></a>

在连接之前 GitHub，请确保您具有：
+ 访问 AWS DevOps 代理管理员控制台
+ 具有管理员权限的 GitHub 用户账户或组织
+ 授权在您的账户或组织中安装 GitHub 应用程序

对于 GitHub 企业服务器，您还需要：
+ 可通过 HTTPS 访问的 GitHub 企业服务器实例（版本 3.x 或更高版本）
+ 您的 GitHub 企业服务器实例的 HTTPS 网址（例如，`https://github.example.com`）
+ （可选）私有连接（如果您的 GitHub 企业服务器实例不可公开访问）

对于具有数据驻留功能的 GitHub 企业云，您还需要：
+ 启用数据驻留功能的 GitHub 企业云组织，托管在您的专用`*.ghe.com`子域上
+ 组织管理员权限，包括创建和安装 GitHub 应用程序的权限
+ 您的数据驻留实例的 HTTPS 网址（例如，`https://octocorp.ghe.com`）

## 注册 GitHub （账户级别）
<a name="registering-github-account-level"></a>

GitHub 在 AWS 账户级别注册，并在该账户中的所有代理空间之间共享。每次注册对应一个 GitHub 用户、一个组织或一个 GitHub 企业服务器实例。

### 步骤 1：导航到管道提供商
<a name="step-1-navigate-to-pipeline-providers"></a>

1. 登录到 AWS 管理控制台

1. 导航到 AWS DevOps 代理控制台

1. 前往 “**功能**” 选项卡

1. 在 “**管道**” 部分，选择 “**添加**”

1. **GitHub**从可用提供商列表中选择

如果 GitHub 尚未注册，系统将提示您先注册。

### 步骤 2：选择连接类型
<a name="step-2-choose-connection-type"></a>

在 “注册 GitHub 账户/组织” 屏幕上，选择您是以用户还是组织身份进行连接：
+ **用户**-包含用户名和个人资料的个人 GitHub 账户
+ **组织** — 一个共享 GitHub 帐户，多个人可以同时在多个项目中进行协作。如果您选择**组织**，请输入 GitHub 组织名称。该名称必须与您的 GitHub 组织名称完全匹配，因为您必须按照以下步骤在该组织上授权并安装该应用程序。

为您的**GitHub 应用程序选择 GitHub 应用程序权限**。权限级别决定了 GitHub 应用程序可以在您的存储库中执行的操作：
+ **读写**（默认）： GitHub 应用程序同时请求读取和写入权限。这将启用所有功能。 DevOps 代理可以发布内联拉取请求评论、提出修复建议和触发工作流程。
+ **只读**： GitHub 应用程序仅请求读取权限。 DevOps 代理可以查看代码和拉取请求，但不能发布评论、提出修复建议或触发工作流程。

如果您要连接到 GitHub 企业服务器实例，请选择**使用 GitHub 企业版**并输入您的实例的 HTTPS URL（例如`https://github.example.com`）。

如果您的 GitHub 企业服务器实例不可公开访问，则可以选择配置私有连接，以允许 AWS DevOps 代理安全访问您的实例。有关更多信息，请参阅 [连接到私人托管的工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。

**注意**  
**请勿在 URL 中包含`/api/v3`或任何尾随路径 — 仅输入基本 URL。

对于具有数据驻留功能的 GitHub 企业云，请选择**使用 GitHub 企业版**并输入您的数据驻留实例的 HTTPS 网址（例如，`https://octocorp.ghe.com`）。

### 第 3 步：设置 GitHub 应用程序
<a name="step-3-set-up-the-github-app"></a>

选择 “**提交**” 以开始应用程序设置过程。后续步骤会有所不同 GitHub.com，具体取决于您是通过数据驻留连接到 GitHub GitHub 企业服务器还是企业云。

#### 对于 GitHub.com
<a name="for-githubcom"></a>

1. GitHub 将您重定向到登录并授权 AWS DevOps 代理。

1. 查看授权请求并授权 AWS DevOps 代理。

1. 授权后， AWS DevOps 代理将完成注册。如果您指定的账户或组织尚未安装该 GitHub 应用程序，则可以继续进入安装页面（请参阅步骤 4）。如果应用程序已安装，则注册无需重新安装即可完成。

1. 安装后， AWS DevOps 代理会收到来自已连接存储库的事件，包括部署事件。

**注意**  
**您必须在注册时指定的同一个用户或组织上授权并安装该应用程序。如果您在其他账户或组织上授权或安装，则注册将失败，您必须重新启动该过程，选择正确的账户或组织。

**注意**  
** AWS DevOps 代理对每个权限级别（读写和只读）使用单独的 GitHub 应用程序，并且每个应用程序都是独立授权的。 GitHub 在您在 “设置” > “应用程序” > “已授权的应用程序” 下撤销授权 GitHub 之前，会记住该授权。如果您之前以此权限级别对应用程序进行了授权，则 GitHub 可能会跳过授权屏幕。如果您更改权限级别，则 GitHub 会提示您首次授权相应的应用程序。

#### 适用于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云
<a name="for-github-enterprise-server-and-github-enterprise-cloud-with-data-residency"></a>

GitHub 具有数据驻留功能的 GitHub 企业服务器和企业云都使用 GitHub 应用程序清单流程，该流程会自动在您的实例上设置新的 GitHub 应用程序。在安装过程中，您的浏览器会被重定向两次：一次重定向到您的实例，另一次重定向到 AWS DevOps 代理。

1. AWS DevOps 代理将您的浏览器重定向到您的 GitHub 企业实例的 “**创建 GitHub 应用程序**” 页面。

1. 应用程序名称已预先填写。根据需要更改名称，然后选择**创建 GitHub 应用程序**。

1.  AWS DevOps 代理将您的浏览器重定向回后，它会将清单代码交换为应用程序凭据。

### 步骤 4：选择存储库并完成安装
<a name="step-4-select-repositories-and-complete-installation"></a>

如果您的账户或组织中已经安装了该 GitHub 应用程序，请跳过此步骤。

1. 此时将显示 GitHub 应用程序的 “**安装和授权**” 页面。

1. 选择允许该应用程序访问的存储库：
   + **所有存储库**-授予对所有当前和将来存储库的访问权限
   + **仅选择存储库**-从您的账户或组织中选择特定的存储库

1. 选择**安装和授权**。

1. 您将被重定向回 AWS DevOps 代理控制台，该控制台 GitHub 将显示为已注册账号。

## 将存储库连接到代理空间
<a name="connecting-repositories-to-an-agent-space"></a>

在账户 GitHub 级别注册后，您可以将特定的存储库连接到各个代理空间：

1. 在 AWS DevOps 代理控制台中，选择您的代理空间

1. 前往 “**功能**” 选项卡

1. 在 “**管道**” 部分，选择 “**添加**”

1. **GitHub**从可用提供商列表中选择

1. 选择包含您要使用的存储库的 GitHub 注册

1. 选择与该代理空间相关的存储库子集

1. 选择 “**添加**” 以完成连接

您可以根据组织需求将不同的存储库集连接到不同的代理空间。单个 Agent Space 可以使用来自多个注册的存储库。要从其他注册中添加存储库，请重复以下步骤。

## 配置代码审查和自动测试
<a name="configuring-code-review-and-automated-testing"></a>

在 GitHub 连接步骤中选择存储库时，它们会自动添加到 “**代码审查和自动测试**” 部分。本节配置哪些存储库会自动触发[发布就绪代码审查](release-management-release-readiness-code-review.md)和自动测试功能。

代码审查和自动测试配置包括：
+ **功能**-为每个存储库选择代码审查和自动测试功能。该部分为每个存储库提供了两个设置：
  + **自动触发变更审查**-为存储库启用后，[发布就绪代码审查](release-management-release-readiness-code-review.md)每次打开或更新拉取请求时， DevOps 代理都会自动运行。审查结果显示为拉取请求的内联评论。默认情况下，所有连接的存储库都启用此功能。
  + **自动验证测试**-为存储库启用后， DevOps 代理将在代码审查期间在托管验证环境中构建、运行和测试您的代码更改。这提供了静态分析之外的功能验证。有关更多信息，请参阅[自动验证测试](release-management-release-readiness-code-review.md)。默认情况下，所有连接的存储库都启用此功能。
+ **存储库列表**-显示您在连接步骤中选择的所有存储库。使用搜索字段按名称筛选存储库。每个存储库都有用于这两种功能的独立复选框。
+ **运行时角色**（可选）— 选择 A DevOps gent 代入的 IAM 角色，以便在您选定的存储库上运行自动化功能。此角色用于访问构建期间所需的内部服务，例如私有包注册表和工件存储系统。我们建议使用与主代理角色不同的角色。

要配置自动审阅，请执行以下操作：

1. 连接存储库后，导航到 GitHub 集成设置中的 “**代码审查和自动测试**” 部分。

1. 对于每个存储库，启用或禁用**自动触发变更审查**功能，具体取决于您是否需要自动拉取请求审阅。

1. 对于每个存储库，根据您是否希望在托管**验证**环境中进行[自动验证测试](release-management-release-readiness-code-review.md)，启用或禁用自动验证测试功能。

1. （可选）从 “**运行时角色**” 下拉列表中选择 A DevOps gent 在所选存储库上运行自动化功能时将担任的 IAM 角色。

1. 选择 “**保存**” 以应用您的配置。

配置完成后，启用自动**触发变更审查**的存储库中的任何新拉取请求都将自动触发发布就绪代码审查。如果还启用了**自动验证测试**，则审查包括验证环境中的功能验证。有关代码审查的更多信息，请参阅[发布就绪代码审查](release-management-release-readiness-code-review.md)。

## 了解 GitHub 应用程序
<a name="understanding-the-github-app"></a>

 AWS DevOps 代理 GitHub 应用程序：
+ 请求访问您的存储库 — 您可以在 GitHub 应用程序安装期间查看特定权限
+ 接收部署事件和其他存储库事件
+ 允许 AWS DevOps Agent 将代码更改与操作事件关联起来
+ 可以通过您的 GitHub 设置随时卸载

对于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云， AWS DevOps 代理会在注册期间自动在您的实例上创建 GitHub 应用程序。您可以管理应用程序的存储库访问权限，也可以通过 **“设置” > “应用程序” > “已安装的 GitHub 应用程序**” 将其卸载。要完全删除应用程序定义，请前往 **“设置” > “开发者设置” > “ GitHub 应用程序**”。

## GitHub 应用程序权限更新
<a name="github-app-permission-updates"></a>

AWS DevOps 在您安装 GitHub 应用程序后，代理可能会请求权限更新以支持新功能。当这种情况发生时：

1. 您将收到来自的 GitHub 有关权限更新请求的通知。

1. 查看更新详细信息以了解正在申请哪些新权限。

1. 选择 “**接受新权限”** 以授予更新的权限。

无需对您的服务或应用程序进行任何更改。在您接受更新的权限后， AWS DevOps 代理请求的下一个安装访问令牌 GitHub 将自动包含新的权限。

**注意**  
**在您接受权限更新之前， AWS DevOps 代理将继续使用先前授予的权限进行操作。在您批准请求之前，依赖于更新权限的新功能将不可用。如果您选择不接受新权限，则该应用程序将保留其当前权限。

### 请求 权限
<a name="requested-permissions"></a>

下表描述了 AWS DevOps 代理 GitHub 应用程序请求的每项权限以及需要这些权限的原因。

如果您在注册时选择了**只读**，则 GitHub 应用程序仅请求下表中每项权限的读取级访问权限。使用 “只读” 权限， GitHub 应用程序无法执行 “**目的**” 列中列出的写入级操作。


| 权限 | 访问级别 | 用途 | 
| --- | --- | --- | 
| 支票 | 读和写 | 发布准备就绪后的代码审查结果是对拉取请求进行检查，允许审核状态直接显示在 GitHub 用户界面中。 | 
| 工作流 | 读和写 | 阅读工作流程定义并触发 GitHub 操作工作流程，以便在 CI/CD 管道中进行发布测试。 | 
| 操作 | 读和写 | 监控 GitHub 操作工作流程在事件调查和发布测试期间运行并访问运行日志。 | 
| 内容 | 读和写 | 阅读存储库源代码以进行代码审查分析和依赖关系映射。写入权限使代理能够针对已发现的问题提出修复建议。 | 
| 拉取请求 | 读和写 | 阅读拉取请求详细信息以触发自动代码审查。写入权限允许发布包含发现结果和建议修复的内联评论评论。 | 
| 组织管理 | 读取 | 阅读目标组织中安装的应用程序列表，以验证 AWS DevOps 代理 GitHub 应用程序是否已安装。 | 

## 管理 GitHub 连接
<a name="managing-github-connections"></a>
+ **更新存储库访问权限**-要更改 GitHub 应用程序可以访问的存储库，请转到您的 GitHub 账户或组织设置。对于具有数据驻留功能的 GitHub GitHub 企业服务器或企业云，请转到您的实例设置。然后导航到已安装的 GitHub 应用程序并修改 AWS DevOps 代理应用程序配置。
+ **查看连接的存储库**-在 AWS DevOps 代理控制台中，选择您的代理空间，然后转到 “功能” 选项卡，在 “管道” 部分中查看连接的存储库。
+ **删除 GitHub 连接**-要断 GitHub 开与代理空间的连接，请在 “管道” 部分中选择连接，然后选择**删除**。要从您的帐户中删除 GitHub 注册，请导航至**能力提供者**页面，在该**GitHub**部分中找到您的注册，然后选择**注销**。

要完全删除集 GitHub 成，请执行以下操作：
+ 要卸载该 GitHub 应用程序，请前往您的 GitHub 账户或组织设置。
+ 要重新连接，请在 AWS DevOps 代理控制台 GitHub 中重新注册。

对于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云， AWS DevOps 代理会在注册期间在您的实例上创建 GitHub 应用程序。要完全清理应用程序，请执行以下两项操作：
+ **卸载应用程序** — 前往 **“设置” > “应用程序” > “已安装的 GitHub 应用程序**”，在应用程序上选择 “**配置**”，然后将其卸载。
+ **删除应用程序**-前往 **“设置” > “开发者设置” > “ GitHub 应用程序**”，选择应用程序，转到 “**高级**” 选项卡，然后选择 “**删除 GitHub 应用程序**”。**警告：**删除 GitHub 应用程序是永久性的，无法撤消。要创建新应用程序，请在 AWS DevOps 代理控制台 GitHub 中重新注册。