View a markdown version of this page

正在连接 GitHub - AWS DevOps 代理人
先决条件注册 GitHub （账户级别）GitHub 使用个人访问令牌注册将存储库连接到代理空间配置代码审查和自动测试了解 GitHub 应用程序GitHub 应用程序权限更新管理 GitHub 连接

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

正在连接 GitHub

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

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

您可以通过两种 GitHub 方式注册。应用程序注册会在您的账户或组织中安装 AWS DevOps 代理 GitHub 应用程序。该 GitHub 应用程序支持 webhook 和细粒度权限，我们建议将其用于大多数用例。个人访问令牌使用您 GitHub 账户中的令牌进行身份验证。当你不需要基于 webhook 的功能时，可以将其用于个人访问。有关更多信息，请参阅 GitHub 使用个人访问令牌注册。

先决条件

在连接之前 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 （账户级别）

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

第 1 步：导航到管道提供商

  1. 登录到 AWS 管理控制台

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

  3. 转到 “能力” 选项卡

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

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

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

步骤 2：选择连接类型

在 “注册 GitHub 帐户/组织” 屏幕上，在 “连接类型” 下，选择 AWS DevOps 代理如何连接到 GitHub：

  • 应用程序注册（推荐）-在您的账户或组织中安装 AWS DevOps 代理 GitHub 应用程序。该 GitHub 应用程序支持 webhook 和细粒度权限。继续执行步骤 3 。

  • 个人访问令牌 -使用您 GitHub 账户中的个人访问令牌进行身份验证。此选项提供个人访问权限，不支持 webhook。跳过本节中的剩余步骤，请参阅 GitHub 使用个人访问令牌注册。

步骤 3：配置 GitHub 应用程序注册

选择您是以用户身份还是以组织身份连接：

  • 用户 — 您的带有用户名和个人资料的个人 GitHub 账户

  • 组织 — 一个共享 GitHub 帐户，多人可以在其中同时跨多个项目进行协作。如果选择 “组织”，请输入 GitHub 组织名称。该名称必须与您的 GitHub 组织名称完全匹配，因为您必须通过以下步骤在该组织上授权和安装应用程序。

为您的GitHub 应用程序选择 GitHub 应用程序权限。权限级别决定了 GitHub 应用程序可以在您的存储库中执行的操作：

  • 读写（默认）： GitHub 应用程序请求读取和写入权限。这将启用所有功能。 DevOps 代理可以发布内联拉取请求评论、提出修复建议并触发工作流程。

  • 只读： GitHub 应用程序仅请求读取权限。 DevOps 代理可以查看代码和拉取请求，但不能发表评论、提出修复建议或触发工作流程。

验证方法

在 “验证方法” 下，选择 AWS DevOps 代理如何确认 GitHub 应用程序已安装在您指定的账户或组织中：

  • Browser-based 回调（默认）— 选择提交后， AWS DevOps 代理会将您重定向 GitHub 到以授权 GitHub 应用程序，并在需要时进行安装。继续执行步骤 4 。

  • 使用个人访问令牌进行验证 -输入个人访问令牌。 AWS DevOps 代理使用一次令牌来确认 GitHub 应用程序已安装在您指定的账户或组织中，然后将其丢弃。该令牌未存储。当您选择 “提交” 时，注册即告完成，不会重定向到 GitHub。

当 GitHub 应用程序已安装时，使用带有个人访问令牌的 “验证”。例如，当你从另一个 AWS 账户或地区连接同一个组织时使用它。如果尚未安装 GitHub 应用程序，请先使用Browser-based 回调进行注册。

验证令牌需要以下权限：

  • 对于组织，代币所有者必须是组织所有者。该代币还需要组织读取权限。对于经典代币，请使用read:org范围。要获得细粒度令牌，请使用管理： Read-only组织权限。

  • 对于个人账户，代币不需要额外的范围。

注意

使用个人访问令牌进行验证仅适用于 GitHub.com。对于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云，请使用Browser-based 回调。

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

如果您的 GitHub 企业服务器实例不可公开访问，则可以选择配置私有连接，以允许 AWS DevOps 代理安全地访问您的实例。有关更多信息，请参阅 连接到私有托管的工具。

注意

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

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

第 4 步：设置 GitHub 应用程序

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

如果您在步骤 3 中选择了使用个人访问令牌进行验证，则无需重定向即可完成注册。跳过步骤 4 和步骤 5。

对于 GitHub.com

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

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

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

  4. 安装后， AWS DevOps Agent 会从连接的存储库接收事件，包括部署事件。

注意

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

注意

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

适用于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云

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

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

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

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

第 5 步：选择存储库并完成安装

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

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

  2. 选择允许应用程序访问哪些存储库：

    • 所有存储库 — 授予对所有当前和未来存储库的访问权限

    • 仅选择存储库 -从您的账户或组织中选择特定的仓库

  3. 选择安装和授权。

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

GitHub 使用个人访问令牌注册

个人访问令牌注册 GitHub 无需安装 AWS DevOps 代理 GitHub 应用程序即可连接。 AWS DevOps 代理存储令牌并使用它代表您对 GitHub API 请求进行身份验证。当您无法安装 GitHub 应用程序，或者仅需要个人存储库访问权限而没有基于 webhook 的功能时，请使用此选项。

个人访问令牌注册支持 GitHub.com、 GitHub 企业服务器和具有数据驻留权的 GitHub 企业云。对于不可公开访问的 GitHub 企业服务器实例，您可以使用私有连接。

在选择此选项之前，请考虑以下限制：

  • 无 webhook — GitHub 不向个人访问令牌注册发送 webhook 事件。 AWS DevOps 代理不接收实时事件，例如拉取请求、推送或部署通知。对于通过个人访问令牌注册连接的存储库，自动发布就绪代码审查和自动验证测试不会触发。您仍然可以通过 DevOps 代理聊天或编码代理集成请求发布准备情况代码审查。有关更多信息，请参阅 发布就绪代码审查。如果您需要实时事件，请使用应用程序注册。

  • 存储库访问权限遵循令牌 — 当您将注册范围限定为组织时， AWS DevOps 代理会列出该组织中该令牌可以访问的存储库。当您连接令牌所有者的个人帐户时， AWS DevOps 代理仅列出令牌所有者拥有的存储库。代理只能执行令牌允许的操作。

  • 不更新令牌 -您无法更新现有 GitHub 注册的令牌。要替换过期或轮换的令牌，请取消注册并使用新令牌 GitHub 重新注册。然后将存储库重新连接到您的代理空间。

创建个人访问令牌

在注册 GitHub 之前，请在中创建令牌。您可以使用经典代币或细粒度令牌。

对于经典代币，请选择以下范围：

  • repo— 需要读取存储库内容和元数据

  • read:org— 将注册范围限定为组织时为必填项。 AWS DevOps 代理使用它来确认代币所有者是该组织的活跃成员。

要获得细粒度令牌，请配置以下内容：

  • 如果您将注册范围限定为某个组织，请将资源所有者设置为该组织。选择 AWS DevOps Agent 可以访问的资料库。

  • 在 “存储库权限” 下，授予 “内容:” Read-only 和 “元数据:” Read-only 。

  • 在 “组织权限” 下，在将注册范围限定为组织 Read-only时授予 “成员：”。

设置符合您的安全政策的到期时间。 AWS DevOps 代理无法续订令牌。在令牌到期之前，创建一个新令牌，注销 GitHub 注册，然后重新注册。

使用个人访问令牌注册

  1. 完成步骤 1：导航到管道提供商。

  2. 在 “注册 GitHub 账户/组织” 屏幕上，在 “连接类型” 下，选择 “个人访问令牌” 。

  3. 在个人访问令牌中，输入您的令牌。

  4. （可选）配置以下字段：

    • GitHub 组织 -输入组织名称，以确定注册的范围。代币所有者必须是该组织的活跃成员。将此字段留空以连接代币所有者的个人 GitHub 账户。当您输入带有数据驻留 URL 的 GitHub 企业云时，此字段是必填字段。

    • GitHub 企业 URL — 输入您的 GitHub 企业实例的 HTTPS 根 URL（例如，https://github.example.com或https://octocorp.ghe.com）。这适用于具有数据驻留权的 GitHub GitHub 企业服务器和企业云。将此字段留空即可连接 GitHub.com。请勿包含/api/v3或任何尾随路径。

    • 私有连接 -如果您的 GitHub 企业服务器实例不可公开访问，请选择私有连接。有关更多信息，请参阅 连接到私有托管的工具。

  5. 选择 “提交” 。 AWS DevOps 代理使用令牌所有者验证令牌 GitHub 并确认代币所有者的身份。当您进入组织时，它还会确认代币所有者是该组织的活跃成员。

注册完成后，在账户级别 GitHub 显示为已注册。按照将资料库连接到代理空间中所述将存储库连接到代理空间。

个人访问令牌注册疑难解答

如果使用个人访问令牌注册失败，请将错误消息与以下列表进行比较。

  • Invalid GitHub personal access token— 令牌无效或已过期。创建一个新令牌并重试。

  • GitHub personal access token does not have sufficient permissions— 将repo范围添加到经典令牌中，或授予对打算使用细粒度令牌的存储库的读取访问权限。

  • The GitHub token's user is not a member of organization "<name>"— 验证组织名称。确认令牌具有read:org范围（经典）或组织成员的读取权限（细粒度）。

  • membership in organization "<name>" is "<state>", not active— 代币所有者向该组织发出了待处理的邀请。接受邀请，然后重试。

  • Failed to reach GitHub— 检查 GitHub 企业 URL 和您的网络配置。有关私有连接，请参阅排除私有连接故障。

  • A GitHub service for "<owner>" is already registered with this account— 该 AWS 账户已经注册了该 GitHub 账户或组织。使用现有注册，或先取消注册。

以下错误适用于使用个人访问令牌进行验证：

  • The DevOps Agent GitHub App is not installed on the requested organization or account— 首先使用Browser-based 回调注册以安装 GitHub 应用程序，然后重试。

  • You do not have permission to install or access the DevOps Agent GitHub App on this organization— 使用对组织具有所有者（管理员）权限的 GitHub 帐户。

  • GitHub App verification is only supported for github.com— 对于具有数据驻留功能的 GitHub GitHub 企业服务器和企业云，请使用Browser-based 回调。

将存储库连接到代理空间

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

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

  2. 转到 “能力” 选项卡

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

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

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

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

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

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

配置代码审查和自动测试

当您在 GitHub 连接步骤中选择存储库时，它们会自动添加到 “代码审查和自动测试” 部分。本节配置哪些存储库会自动触发发布就绪代码审查和自动测试功能。

注意

自动触发器取决于 GitHub 应用程序中的 webhook 事件。对于通过个人访问令牌注册连接的存储库，不运行自动审查和自动测试。改为通过 DevOps 代理聊天或编码代理集成请求发布准备情况代码审查。

代码审查和自动测试配置包括：

  • 功能 -为每个存储库选择代码审查和自动测试功能。该部分提供了两个每个存储库的设置：

    • 自动触发变更审查 -为存储库启用后，发布就绪代码审查每次打开或更新拉取请求时， DevOps 代理都会自动运行。审查结果以拉取请求的内联评论形式显示。默认情况下，所有连接的存储库均启用此功能。

    • 自动验证测试 -启用存储库后， DevOps 代理将在代码审查期间在托管验证环境中构建、运行和测试您的代码更改。这提供了除静态分析之外的功能验证。有关更多信息，请参阅自动验证测试。默认情况下，所有连接的存储库均启用此功能。

  • 存储库列表 -显示您在连接步骤中选择的所有存储库。使用搜索字段按名称筛选存储库。每个存储库都有针对这两种功能的独立复选框。

  • 运行时角色（可选）-选择 DevOps 代理代为在所选存储库上运行自动化功能而代入的 IAM 角色。此角色用于访问构建期间所需的内部服务，例如私有包注册表和工件存储系统。我们建议使用与您的主要代理角色不同的角色。

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

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

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

  3. 对于每个存储库，启用或禁用自动验证测试功能，具体取决于您是否希望在托管验证环境中进行自动验证测试。

  4. （可选）从 “运行时角色” 下拉列表中选择一个 IAM 角色， DevOps 代理在所选存储库上运行自动化功能时将代入该角色。

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

配置完成后，启用自动触发变更审查的仓库中的任何新拉取请求都将自动触发发布就绪代码审查。如果还启用了自动验证测试，则审查包括验证环境中的功能验证。有关代码审查的更多信息，请参阅发布就绪代码审查。

高级设置：触发过滤器

默认情况下，启用了自动触发变更审查的存储库会对任何目标分支上的每个适用的拉取请求事件运行发布准备情况代码审查。使用高级设置添加触发过滤器，控制每个仓库的自动审阅的确切运行时间。

每个过滤器都是一个过滤器组，它结合了两个条件：

  • 目标分支（必填）-一个或多个分支名称或模式，以正则表达式（例如，main或release/.*）形式输入。只有当拉取请求的目标（基本）分支匹配其中一种模式时，审查才会触发。

  • 触发事件（可选）-触发审查的拉取请求事件：拉取请求准备好进行审核或拉取请求已起草。将此项留空以匹配所有适用事件。

在过滤器组中，所有条件都必须匹配 (AND)。您可以添加多个筛选群组，当任何群组匹配时，系统会触发审核 (OR)。

要配置触发器过滤器，请：

  1. 在连接流程中打开 “高级设置” 部分。（要更改现有连接上的过滤器，请在 “管道” 部分选择该连接，选择 “编辑”，然后打开 “高级设置” 。）

  2. 找到要配置的存储库，然后选择 “更改审阅” 选项卡。

  3. 选择添加过滤器组，然后定义该组的条件：

    • 在目标分支下，输入分支名称或模式，然后按 Enter 键或选择添加。重复以添加更多图案。

    • （可选）在 “触发事件” 下，选择 “拉取请求准备审核” 、“拉取请求已草拟”，或两者兼有。将其留空以匹配所有事件。

  4. （可选）再次选择 “添加筛选器组” 以表达备选条件。

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

每个存储库最多可以定义 5 个筛选器组，每个组最多 20 个模式。每种模式必须是最多 256 个字符的有效正则表达式。如果您未添加任何筛选群组，则审阅将在所有目标分支的所有适用事件上触发。

了解 GitHub 应用程序

AWS DevOps 代理 GitHub 应用程序：

  • 请求访问您的存储库-您可以在 GitHub 应用程序安装期间查看特定权限

  • 接收部署事件和其他存储库事件

  • 允许 AWS DevOps 代理将代码更改与操作事件关联起来

  • 可以随时通过您的 GitHub 设置卸载

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

GitHub 应用程序权限更新

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

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

  2. 查看更新详细信息以了解请求了哪些新权限。

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

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

注意

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

请求 权限

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

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

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

管理 GitHub 连接

  • 更新仓库访问权限 -要更改 GitHub 应用程序可以访问的仓库，请访问您的 GitHub 帐户或组织设置。对于具有数据驻留功能的 GitHub GitHub 企业服务器或企业云，请转到您的实例设置。然后导航到已安装的 GitHub 应用程序并修改 AWS DevOps 代理应用程序配置。

  • 查看连接的存储库 -在 AWS DevOps 代理控制台中，选择您的代理空间并转到功能选项卡，在 “管道” 部分查看连接的存储库。

  • 替换个人访问令牌 -您无法更新现有 GitHub 注册的令牌。要替换令牌，请从 “能力提供者” 页面注销注册。然后使用新令牌 GitHub 再次注册，并将存储库重新连接到您的代理空间。在 GitHub 设置中撤销旧令牌。

  • 删除 GitHub 连接 -要断 GitHub 开与代理空间的连接，请在管道部分选择连接，然后选择删除。要从您的账户中删除 GitHub 注册，请导航至能力提供者页面，在该GitHub部分中找到您的注册，然后选择取消注册。

要完全删除集 GitHub 成，请执行以下操作：

  • 要卸载 GitHub 应用程序，请转到您的 GitHub 帐户或组织设置。

  • 要重新连接，请在 AWS DevOps 代理控制台 GitHub 中重新注册。

对于具有数据驻留权的 GitHub GitHub 企业服务器和企业云， AWS DevOps 代理在注册期间会在您的实例上创建 GitHub 应用程序。要彻底清理应用程序，请执行以下两项操作：

  • 卸载应用程序 -前往 “设置” > “应用程序” > “已安装的 GitHub 应用程序”，在应用程序上选择 “配置”，然后将其卸载。

  • 删除应用程序 -前往 “设置” > “开发者设置” > “ GitHub 应用程序”，选择应用程序，转到 “高级” 选项卡，然后选择 “删除 GitHub 应用程序” 。警告：删除 GitHub 应用程序是永久性的，无法撤消。要创建新应用程序，请在 AWS DevOps 代理控制台 GitHub 中重新注册。