本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # GitHub 和 GitHub 企业服务器访问权限 CodeBuild 对于 GitHub，您可以使用个人访问令牌、 OAuth 应用程序、Secrets Manager 密钥或 GitHub 应用程序连接来访问源提供商。对于 E GitHub nterprise Server，您可以使用个人访问令牌、Secrets Manager 密钥或 GitHub 应用程序连接来访问源提供商。 **Topics** + [GitHub GitHub 和 GitHub 企业服务器的应用程序连接](connections-github-app.md) + [GitHub 和 GitHub 企业服务器访问令牌](access-tokens-github.md) + [GitHub OAuth 应用程序](oauth-app-github.md) # GitHub GitHub 和 GitHub 企业服务器的应用程序连接 您可以使用 GitHub App 进行连接 CodeBuild。 GitHub 通过支持应用程序连接[AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html)。 源提供程序访问权限使您可以通过订阅使用或[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)在中[GitHub webhook 事件](github-webhook.md) CodeBuild使用[ CreateWebhook](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateWebhook.html)来触发构建。 **注意** CodeConnections 在少于. 的地区中可用 CodeBuild。您可以在中使用跨区域连接。 CodeBuild在选择加入区域创建的连接不能在其他区域中使用。有关更多信息，请参阅 [AWS CodeConnections 终端节点和限额](https://docs.aws.amazon.com/general/latest/gr/codestar_connections.html)。 **Topics** + [步骤 1：创建与 GitHub 应用程序（控制台）的连接](#connections-github-console) + [步骤 2：向 CodeBuild 项目 IAM 角色授予使用连接的访问权限](#connections-github-role-access) + [步骤 3：配置 CodeBuild 为使用新连接](#connections-github-account-credential) + [对 GitHub 应用程序进行故障排除](#connections-github-troubleshooting) ## 步骤 1：创建与 GitHub 应用程序（控制台）的连接 使用以下步骤使用 CodeBuild 控制台为您的项目添加连接 GitHub。 **要创建与的连接 GitHub** + 按照《*开发者工具用户指南》*中的说明进行操作[，创建与的连接 GitHub](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html)。 **注意** 您可以使用其他账户共享的连接，而不是创建或使用 AWS 账户中的现有连接。有关更多信息，请参阅[与 AWS 账户共享连接](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html)。 ## 步骤 2：向 CodeBuild 项目 IAM 角色授予使用连接的访问权限 您可以授予 CodeBuild 项目 IAM 角色访问权限，以使用您的连接出售的 GitHub 令牌。 **授予 CodeBuild 项目 IAM 角色访问权限** 1. 按照项目的说明为您的 CodeBuild 项目创建 IAM 角色。[CodeBuild 允许与其他 AWS 服务进行交互](setting-up-service-role.md) CodeBuild 1. 按照说明进行操作时，将以下 IAM 策略添加到您的 CodeBuild 项目角色以授予对连接的访问权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [ "arn:aws:iam::*:role/Service*" ] } ] } ``` ------ ## 步骤 3：配置 CodeBuild 为使用新连接 您可以将连接配置为账户级别凭证，并在项目中使用。 ------ #### [ AWS 管理控制台 ] **要将连接配置为账户级别的凭证，请参阅 AWS 管理控制台** 1. 对于**源提供商**，请选择**GitHub**。 1. 对于**凭证**，执行以下操作之一： + 选择**默认来源凭证**，使用您账户的默认来源凭证应用于所有项目。 1. 如果您未连接到 GitHub，请选择 “**管理默认来源凭据**”。 1. 对于 “**凭据类型**”，选择 “**GitHub 应用程序**”。 1. 在**连接**中，选择使用现有连接或创建新连接。 + 选择**自定义来源凭证**，以便使用自定义来源凭证来覆盖您账户的默认设置。 1. 对于 “**凭据类型**”，选择 “**GitHub 应用程序**”。 1. 在**连接**中，选择使用现有连接或创建新连接。 ------ #### [ AWS CLI ] **要将连接配置为账户级别的凭证，请参阅 AWS CLI** + 打开终端（Linux、macOS 或 Unix）或命令提示符（Windows）。 AWS CLI 使用运行**import-source-credentials**命令，`--token`为您的连接指定`--auth-type``--server-type`、和。 使用以下命令： ``` aws codebuild import-source-credentials --auth-type CODECONNECTIONS --server-type GITHUB --token ``` ------ 您也可以为 CodeBuild 项目设置多个代币。有关更多信息，请参阅 [将多个令牌配置为源级别凭证](multiple-access-tokens.md#asm-source-credential)。 ## GitHub 应用程序问题疑难解答 以下信息可以帮助您解决 GitHub 应用程序的常见问题。 **Topics** + [在不想要的 GitHub 区域安装应用程序 AWS 连接器](#connections-github-troubleshooting.undesired-region) + [GitHub 应用程序连接无权访问存储库](#connections-github-troubleshooting.repo-access) + [该 AWS 服务的 IAM 角色缺少必要的 IAM 权限。](#connections-github-troubleshooting.iam-permissions) ### 在不想要的 GitHub 区域安装应用程序 AWS 连接器 **问题：**您 GitHub 从 GitHub Marketplace 安装了连接 AWS 器，但连接是在不需要的区域创建的。如果您尝试在 GitHub 网站上重新配置应用程序，则该应用程序将无法运行，因为该应用程序已安装在您的 GitHub 帐户中。 **可能的原因：**该应用程序已安装在您的 GitHub 帐户中，因此您只能重新配置应用程序权限。 **推荐的解决方案：**您可以在期望区域使用安装 ID 创建新连接。 1. 在[https://console.aws.amazon.com/codesuite/设置/连接](https://console.aws.amazon.com/codesuite/settings/connections)处打开 CodeConnections 控制台，然后使用控制 AWS 台导航栏中的区域选择器导航到所需区域。 1. 按照《*开发者工具用户指南》*中的说明进行操作[，创建与的连接 GitHub](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html)。 **注意** 由于您已经为 GitHub 应用程序安装了 C AWS onnector，因此您可以选择它来代替安装新应用程序。 ### GitHub 应用程序连接无权访问存储库 **问题：**使用连接的 AWS 服务（例如 CodeBuild 或 CodePipeline）报告它无权访问存储库或存储库不存在。一些可能的错误消息包括： + `Authentication required for primary source.` + `Unable to create webhook at this time. Please try again later.` + `Failed to create webhook. GitHub API limit reached. Please try again later.` ***可能的原因：**您可能一直在使用该 GitHub 应用程序，但尚未授予 webhook 权限范围。* **推荐的解决方案：**要授予所需的权限范围，请按照[导航到要查看或修改的 GitHub 应用程序](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify)中的说明配置已安装的应用程序。在权限部分下面，您会看到该应用程序没有 webhook 权限，并且您可以选择查看新请求的权限。查看并接受新权限。有关更多信息，请参阅[批准应用程序的更新权限。 GitHub ](https://docs.github.com/en/apps/using-github-apps/approving-updated-permissions-for-a-github-app) ***可能的原因：**连接按预期运行，但突然无权访问存储库。* **可能的解决方案：**首先查看您的[授权](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps)和[安装](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps)情况，然后验证 GitHub 应用程序是否已授权并已安装。如果 GitHub 应用程序安装已暂停，则需要将其取消暂停。如果 GitHub 应用程序未获得 [UAT（用户访问令牌）](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)连接的授权，或者未为 [IAT（安装访问令牌）](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)连接安装该应用程序，则现有连接将无法再使用，您将需要创建一个新连接。请注意，重新安装该 GitHub 应用程序不会恢复与旧安装关联的先前连接。 **可能的解决方案：**如果连接是 UAT 连接，请确保该连接不是同时使用的，例如在多次 CodeBuild 并发运行的构建中使用该连接。这是因为如果连接刷新了即将到期的令牌，则先前发行的 UAT 会 GitHub 立即失效。如果您需要将 UAT 连接用于多个并发 CodeBuild 构建，则可以创建多个连接并独立使用每个连接。 **可能的解决方案：**如果在过去 6 个月内未使用过 UAT 连接，则该连接将失效。 GitHub要修复此问题，请创建新的连接。 ***可能的原因：**您可能在未安装应用程序的情况下使用 UAT 连接。* **推荐的解决方案：**尽管创建 UAT 连接不需要将连接与 GitHub 应用程序安装相关联，但需要安装才能访问存储库。按照说明[查看安装情况](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps)，确保 GitHub 应用程序已安装。如果未安装，请导航至[GitHub 应用程序页面](https://github.com/marketplace/aws-connector-for-github)以安装该应用程序。有关 UAT 访问权限的更多信息，请参阅[关于用户访问令牌](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#about-user-access-tokens)。 ### 该 AWS 服务的 IAM 角色缺少必要的 IAM 权限。 **问题：**您看到以下任何错误消息： + `Access denied to connection ` + `Failed to get access token from ` **推荐的解决方案：**通常使用与 AWS 服务的连接，例如 CodePipeline 或 CodeBuild。当您为 AWS 服务提供 IAM 角色时，该 AWS 服务可以使用该角色的权限代表您执行操作。确保 IAM 角色具有必要的权限。有关必需的 IAM 权限的更多信息，请参阅[向 CodeBuild 项目 IAM 角色授予使用连接的访问](#connections-github-role-access)权限以及[AWS CodeStar 通知的身份和访问管理](https://docs.aws.amazon.com/dtconsole/latest/userguide/security-iam.html)，以及开发者工具控制台用户指南 CodeConnections中的*开发者工具控制台用户指南*。 # GitHub 和 GitHub 企业服务器访问令牌 ## 访问令牌先决条件 在开始之前，必须向 GitHub 访问令牌添加适当的权限范围。 对于 GitHub，您的个人访问令牌必须具有以下范围。 + **repo**：授予私有存储库的完全控制权。 + **repo: status：授予对公共和私有仓库提交状态**的 read/write 访问权限。 + **admin:repo\$1hook**：授予存储库挂钩的完全控制权。如果您的令牌具有 `repo` 范围，则不需要此权限范围。 + **admin:org\$1hook**：对组织挂钩授予完全控制权限。仅当您使用组织 webhook 特征时，才需要此范围。 有关更多信息，请参阅[了解 GitHub 网站上 OAuth 应用程序的范围](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/)。 如果您使用的是细粒度个人访问令牌，则根据您的使用场景，您的个人访问令牌可能需要以下权限： + **内容：只读**：授予对私有存储库的访问权限。如果使用私有存储库作为源，则需要此权限。 + **提交状态：读写**：授予创建提交状态的权限。如果您的项目设置了 webhook，或者启用了报告构建状态特征，则需要此权限。 + **Webhook：读写**：授予管理 webhook 的权限。如果您的项目设置了 webhook，则需要此权限。 + **拉取请求：只读**：授予访问拉取请求的权限。如果您的 webhook 对拉取请求事件设置了 `FILE_PATH` 筛选条件，则需要此权限。 + **管理：读写**：如果您使用自托管 GitHub 的 Actions 运行器功能，则需要此权限。 CodeBuild有关更多详细信息，请参阅[为存储库创建注册令牌](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository)和[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。 **注意** 如果要访问组织存储库，请务必将该组织指定为访问令牌的资源所有者。 有关更多信息，请参阅网站上的[细粒度个人访问令牌所需的权限](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)。 GitHub ## GitHub 使用访问令牌 Connect（控制台） 要使用控制台 GitHub 使用访问令牌将您的项目与之连接，请在创建项目时执行以下操作。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)。 1. 对于**源提供商**，请选择**GitHub**。 1. 对于**凭证**，执行以下操作之一： + 选择使用账户凭证将您账户的默认源凭证应用于所有项目。 1. 如果您未连接到 GitHub，请选择 “**管理账户凭证**”。 1. 对于**凭证类型**，选择**个人访问令牌**。 + 如果您选择为**服务**使用账户级别凭证，请选择要用于存储令牌的服务，然后执行以下操作： 1. 如果您选择使用 **Secrets Manager**，则可以选择使用现有密钥连接或创建新密钥，然后选择**保存**。有关如何创建新密钥的更多信息，请参阅[在 Secrets Manager 密钥中创建和存储令牌](asm-create-secret.md)。 1. 如果您选择使用 **CodeBuild**，请输入您的 GitHub 个人访问令牌，然后选择**保存**。 + 选择**仅为此项目使用覆盖凭证**，以便使用自定义源凭证来覆盖账户的凭证设置。 1. 从填充的凭证列表中，选择**个人访问令牌**下的选项之一。 1. 您也可以通过在描述中选择**创建新的个人访问令牌连接**来创建新的个人访问令牌。 ## GitHub 使用访问令牌 (CLI) 连接 按照以下步骤使用访问令牌将您的项目连接到 GitHub 该项目。 AWS CLI 有关 AWS CLI 搭配使用的信息 AWS CodeBuild，请参阅[命令行参考](cmd-ref.md)。 1. 运行 **import-source-credentials** 命令： ``` aws codebuild import-source-credentials --generate-cli-skeleton ``` 输出中将显示 JSON 格式的数据。将数据复制到安装的本地计算机或实例上某个位置的文件（例如`import-source-credentials.json`）。 AWS CLI 按照下面所示修改复制的数据，并保存您的结果。 ``` { "serverType": "server-type", "authType": "auth-type", "shouldOverwrite": "should-overwrite", "token": "token", "username": "username" } ``` 替换以下内容： + *server-type*：必填值。用于此凭证的源提供商。有效值为 GITHUB、BITBUCKET、GITHUB\$1ENTERPRISE、GITLAB 和 GITLAB\$1SELF\$1MANAGED。 + *auth-type*：必填值。用于连接到存储库的身份验证类型。有效值为 OAUTH、BASIC\$1AUTH、PERSONAL\$1ACCESS\$1TOKEN、CODECONNECTIONS 和 SECRETS\$1MANAGER。对于 GitHub，仅允许使用个人访问令牌。对于 Bitbucket 应用程序密码，仅允许 BASIC\$1AUTH。 + *should-overwrite*: 可选值。设置为 `false` 可防止覆盖存储库源凭证。设置为 `true` 可覆盖存储库源凭证。默认值为 `true`。 + *token*：必填值。对于 GitHub 我们的 GitHub 企业服务器，这是个人访问令牌。对于 Bitbucket，这是个人访问令牌或应用程序密码。对于身份验证类型 CODECONNECTIONS，这是连接 ARN。对于身份验证类型 SECRETS\$1MANAGER，这是密钥 ARN。 + *username*: 可选值。对于 GitHub 和 GitHub 企业服务器源提供程序，将忽略此参数。 1. 要使用访问令牌连接您的账户，请切换到包含您在步骤 1 中保存的 `import-source-credentials.json` 文件的目录，然后重新运行 **import-source-credentials** 命令。 ``` aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json ``` JSON 格式的数据将使用 Amazon 资源名称 (ARN) 显示在输出中。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` **注意** 如果您再次使用相同的服务器类型和身份验证类型运行 **import-source-credentials** 命令，则会更新存储的访问令牌。 在您的账户与访问令牌关联后，您可以使用`create-project`来创建您的 CodeBuild 项目。有关更多信息，请参阅 [创建构建项目 (AWS CLI)](create-project.md#create-project-cli)。 1. 要查看连接的访问令牌，请运行 **list-source-credentials** 命令。 ``` aws codebuild list-source-credentials ``` JSON 格式的 `sourceCredentialsInfos` 对象将显示在输出中： ``` { "sourceCredentialsInfos": [ { "authType": "auth-type", "serverType": "server-type", "arn": "arn" } ] } ``` `sourceCredentialsObject` 包含连接的源凭证信息的列表： + `authType` 是凭证使用的身份验证类型。这可以是 `OAUTH`、`BASIC_AUTH`、`PERSONAL_ACCESS_TOKEN`、`CODECONNECTIONS` 或 `SECRETS_MANAGER`。 + `serverType` 是源提供商类型。这可以是 `GITHUB`、`GITHUB_ENTERPRISE`、`BITBUCKET`、`GITLAB` 或 `GITLAB_SELF_MANAGED`。 + `arn` 是令牌的 ARN。 1. 要断开与源提供商的连接并删除其访问令牌，请使用其 ARN 运行 **delete-source-credentials** 命令。 ``` aws codebuild delete-source-credentials --arn arn-of-your-credentials ``` 将返回 JSON 格式的数据，并带有已删除凭证的 ARN。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` # GitHub OAuth 应用程序 ## GitHub 使用 OAuth （控制台）连接 要使用控制台将您的项目与 GitHub OAuth 应用程序连接起来，请在创建项目时执行以下操作。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)。 1. 对于**源提供商**，请选择**GitHub**。 1. 对于**凭证**，执行以下操作之一： + 选择使用账户凭证将您账户的默认源凭证应用于所有项目。 1. 如果您未连接到 GitHub，请选择 “**管理账户凭证**”。 1. 对于**凭据类型**，请选择**OAuth 应用程序**。 + 如果您选择为**服务**使用账户级别凭证，请选择要用于存储令牌的服务，然后执行以下操作： 1. 如果您选择使用 **Secrets Manager**，则可以选择使用现有密钥连接或创建新密钥，然后选择**保存**。有关如何创建新密钥的更多信息，请参阅[在 Secrets Manager 密钥中创建和存储令牌](asm-create-secret.md)。 1. 如果您选择使用**CodeBuild**然后选择**保存**。 + 选择**仅为此项目使用覆盖凭证**，以便使用自定义源凭证来覆盖账户的凭证设置。 1. 从填充的凭据列表中，选择**OAuth 应用程序**下的选项之一。 1. 您也可以通过在描述中选择 “**创建新 OAuth 的 Oauth 应用程序令牌连接” 来创建新的应用程序令牌**。 要查看您的授权 OAuth 应用程序，请导航到 “开启的[应用程序](https://github.com/settings/applications)” GitHub，并验证是否列出了名为 [aws-codesuite `AWS CodeBuild (region)`](https://github.com/aws-codesuite) 拥有的应用程序。