本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 教程：配置 CodeBuild托管的 Buildkite 运行器
本教程向您展示如何配置 CodeBuild 项目以运行 Buildkite 作业。有关将 Buildkite 与配合 CodeBuild 使用的更多信息，请参阅。[自我管理的 Buildkite 运行器进来了 AWS CodeBuild](buildkite-runner.md)
要完成本教程，您首先必须：
+ 可以访问 Buildkite 组织。有关设置 Buildkite 账户和组织的更多信息，您可以关注此 [Getting Started Tutorial](https://buildkite.com/docs/pipelines/getting-started)。
+ 创建配置为使用自托管运行程序的 Buildkite 管道、集群和队列。有关设置这些资源的更多信息，可以参考 [Buildkite Pipeline Setup Tutorial](https://buildkite.com/docs/pipelines/create-your-own)。
![\[在 Buildkite 中构建项目\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-first.png)
## 步骤 1：生成 Buildkite 代理令牌
在此步骤中，您将在 Buildkite 中生成代理令牌，该令牌将用于对 CodeBuild 自托管运行器进行身份验证。有关此资源的更多信息，请参阅 [Buildkite Agent Tokens](https://buildkite.com/docs/agent/v3/tokens)。
**生成 Buildkite 代理令牌**
1. 在 Buildkite 集群中，选择**代理令牌**，然后选择**新建令牌**。
1. 向令牌添加描述，然后单击**创建令牌**。
1. 保存代理令牌值，以便稍后在 CodeBuild 项目设置过程中使用该值。
![\[Buildkite 中的代理令牌\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-createtoken.png)
## 第 2 步：使用 webhook 创建 CodeBuild 项目
**使用 webhook 创建 CodeBuild 项目**
1. 在 [https://console.aws.amazon.com/codesuite/codebuild](https://console.aws.amazon.com/codesuite/codebuild/home) /home 中打开 AWS CodeBuild 控制台。
1. 创建自托管构建项目。有关更多信息，请参阅 [创建构建项目（控制台）](create-project.md#create-project-console) 和 [运行构建（控制台）](run-build-console.md)。
+ 在**项目配置**中，选择**运行程序项目**。在**运行程序**中：
+ 对于**运行程序提供商**，选择 **Buildkite**。
+ 对于 **Buildkite 代理令牌**，选择**使用创建密钥页面创建新的代理令牌**。系统将提示您在中 AWS Secrets Manager 创建一个新的密钥，其密钥值等于您在上面生成的 Buildkite 代理令牌。
+ （可选）如果您想为作业使用 CodeBuild 托管证书，请在 **Buildkite 来源凭据选项下选择作业的源**存储库提供商，并验证是否已为您的账户配置了凭据。此外，请验证 Buildkite 管道是否采用**使用 HTTPS 签出**。
**注意**
Buildkite 需要构建环境中的源凭证才能提取作业的源。有关可用的源凭证选项，请参阅[针对私有存储库对 Buildkite 进行身份验证](#sample-runner-buildkite-config)。
+ （可选）在**环境**中：
+ 选择支持的**环境映像**和**计算**。
请注意，您可以选择在 Buildkite YAML 步骤中使用标签来覆盖映像和实例设置。有关更多信息，请参阅 [步骤 4：更新 Buildkite 管道步骤](#sample-runner-buildkite-update-pipeline)。
+ （可选）在 **Buildspec** 中：
+ 除非将 `buildspec-override: "true"` 添加为标签，否则系统默认情况下会忽略 buildspec。相反， CodeBuild 将覆盖它以使用设置自托管运行器的命令。
**注意**
CodeBuild 不支持 Buildkite 自托管运行器版本的 buildspec 文件。对于内联构建规范，如果您已配置 CodeBuild 托管源凭据，则需要[ git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper)在构建规范中启用
1. 继续使用默认值，然后选择**创建构建项目**。
1. 保存**创建 webhook** 弹出窗口中的**有效载荷 URL** 和**密钥**值。要么按照弹出窗口中的说明创建新的 Buildkite 组织 webhook，要么继续下一节。
## 第 3 步：在 Buildkite 中创建一个 CodeBuild webhook
在此步骤中，您将使用 CodeBuild webhook 中的**有效负载 URL** 和 S **ecret** 值在 Buildkite 中创建一个新的 webhook。此 webhook 将用于在有效的 Buildkite 作业启动 CodeBuild 时触发构建。
**在 Buildkite 中创建新的 webhook**
1. 导航到 Buildkite 组织的**设置**页面。
1. 在**集成**下，选择**通知服务**。
1. 选择 **Webhook** 框旁边的**添加**。在**添加 Webhook 通知**页面中，使用以下配置：
1. 在 **Webhook URL** 下，添加保存的**有效载荷 URL** 值。
1. 在 “**令牌**” 下，确认已选**中 “按原样 X-Buildkite-Token发送令牌**”。将 webhook **密钥**值添加到**令牌**字段。
1. 在下方，确认选**中了按原样 X-Buildkite-Token发送令牌**。将 webhook **密钥**值添加到**令牌**字段。
1. 在**事件**下，选择 `job.scheduled` webhook 事件。
1. （可选）在**管道**下，您可以选择仅触发特定管道的构建。
1. 选择**添加 Webhook 通知**。
## 步骤 4：更新 Buildkite 管道步骤
在此步骤中，您将更新 Buildkite 管道的步骤，以便添加必要的标签和可选的覆盖。有关支持的标签覆盖的完整列表，请参阅[CodeBuild托管的 Buildkite 运行器支持的标签覆盖](buildkite-runner-update-labels.md)。
**更新管道步骤**
1. 通过选择 Buildkite 管道，选择**设置**，然后选择**步骤**，导航到 Buildkite 管道步骤页面。
如果您尚未选择，请选择**转换为 YAML 步骤**。
![\[用于更新 YAML 的步骤。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-steps.png)
1. 您至少需要指定一个引用管道名称的 [Buildkite 代理标签](https://buildkite.com/docs/agent/v3/cli-start#agent-targeting)。 CodeBuild 需要项目名称才能将 Buildkite 作业的 AWS相关设置链接到特定 CodeBuild 项目。通过在 YAML 中包含项目名称 CodeBuild ，可以调用具有正确项目设置的作业。
```
agents:
project: "codebuild-"
```
以下是仅具有项目标注标签的 Buildkite 管道步骤的示例：
```
agents:
project: "codebuild-myProject"
steps:
- command: "echo \"Hello World\""
```
您也可以在标签中覆盖映像和计算类型。有关可用映像的列表，请参阅[计算 CodeBuild托管的 Buildkite 运行器支持的图像](buildkite-runner-update-yaml.images.md)。标签中的计算类型和映像将覆盖项目的环境设置。要替换 CodeBuild EC2 或 Lambda 计算版本的环境设置，请使用以下语法：
```
agents:
project: "codebuild-"
image: "-"
instance-size: ""
```
以下是具有映像和实例大小覆盖的 Buildkite 管道步骤的示例：
```
agents:
project: "codebuild-myProject"
image: "arm-3.0"
instance-size: "small"
steps:
- command: "echo \"Hello World\""
```
您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅[在预留容量实例集上运行构建](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html)。
要覆盖 Amazon EC2 计算构建的实例集设置，请使用以下语法：
```
agents:
project: "codebuild-"
fleet: ""
```
要同时覆盖构建所用的实例集和映像，请使用以下语法：
```
agents:
project: "codebuild-"
fleet: ""
image: "-"
```
以下是具有实例集和映像覆盖的 Buildkite 管道步骤的示例：
```
agents:
project: "codebuild-myProject"
fleet: "myFleet"
image: "arm-3.0"
steps:
- command: "echo \"Hello World\""
```
1. 您可以选择在自托管 Buildkite 运行程序构建期间运行内联 buildspec 命令（有关更多详细信息，请参阅[对于 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 阶段运行 buildspec 命令](sample-runner-buildkite-buildspec.md)）。要指定该 CodeBuild 版本应在 Buildkite 自托管运行器构建期间运行 buildspec 命令，请使用以下语法：
```
agents:
project: "codebuild-"
buildspec-override: "true"
```
以下是具有 buildspec 覆盖的 Buildkite 管道的示例：
```
agents:
project: "codebuild-myProject"
buildspec-override: "true"
steps:
- command: "echo \"Hello World\""
```
1. 或者，您可以在 CodeBuild 支持的标签之外提供标签。在覆盖构建的属性时会忽略这些标签，但不会导致 webhook 请求失败。例如，添加 `myLabel: “testLabel"` 作为标签不会阻止构建运行。
## 第 5 步：查看您的结果
每当你的管道中启动 Buildkite 作业时， CodeBuild 都会通过 Buildkite `job.scheduled` webhook 收到一个 webhook 事件。对于你的 Buildkite 版本中的每项任务，都 CodeBuild 将启动一个构建来运行一个临时的 Buildkite 运行器。该运行程序负责执行单个 Buildkite 作业。作业完成后，运行器和关联的构建过程会立即终止。
要查看工作流程作业日志，请导航到 Buildkite 管道并选择最新的构建（您可以通过选择**新构建**来触发新的构建。每项任务的关联 CodeBuild 构建启动并启动任务后，您应该可以在 Buildkite 控制台中看到该任务的日志
![\[查看结果。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-log.png)
## 针对私有存储库对 Buildkite 进行身份验证
如果您在 Buildkite 管道中配置了私有存储库，则 Buildkite 需要[构建环境中的额外权限](https://buildkite.com/docs/agent/v3/github-ssh-keys)才能提取存储库，因为 Buildkite 不会向自托管运行程序提供凭证以从私有存储库中进行提取。要针对外部私有源存储库对 Buildkite 自托管运行程序代理进行身份验证，可以使用以下选项之一。
**要使用进行身份验证 CodeBuild**
CodeBuild 为支持的源类型提供托管凭据处理。要使用 CodeBuild 源证书提取作业的源存储库，您可以使用以下步骤：
1. 在 CodeBuild 控制台中，导航到**编辑项目**或使用中的步骤创建新 CodeBuild 项目[第 2 步：使用 webhook 创建 CodeBuild 项目](#sample-runner-buildkite-create-project)。
1. 在 **Buildkite 源凭证选项**下，选择作业的源存储库提供商。
1. 如果您想使用账户级 CodeBuild 凭证，请验证其配置是否正确。此外，如果您的项目配置了内联构建规范，请验证[ git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper)是否已启用。
1. 如果您想使用项目级别的 CodeBuild 凭据，请选择 “**仅为此项目使用覆盖凭据**”，然后为您的项目设置凭据。
1. 在 Buildkite 管道设置中，导航到**存储库设置**。将源存储库签出设置设为**使用 HTTPS 签出**
![\[查看结果。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-repo-https.png)
**使用 Buildkite 密钥进行身份验证**
Buildkite 维护一个 [ssh-checkout 插件](https://github.com/buildkite-plugins/git-ssh-checkout-buildkite-plugin)，该插件可用于使用 ssh 密钥针对外部源存储库对自托管运行程序进行身份验证。密钥值存储为 [Buildkite 密钥](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets)，并在尝试提取私有存储库时由 Buildkite 自托管运行程序代理自动获取。要为 Buildkite 管道配置 ssh-checkout 插件，可以使用以下步骤：
1. 使用您的电子邮件地址生成私有和公有 ssh 密钥，例如 `ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"`
1. 将公有密钥添加到私有源存储库。例如，您可以按照[本指南](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)为 GitHub 账户添加密钥。
1. 向 Buildkite 集群添加一个[新的 SSH 密钥](https://buildkite.com/docs/pipelines/hosted-agents/code-access#private-repositories-with-other-providers-add-the-ssh-key-secret)。在 Buildkite 集群中，选择**密钥** → **新密钥**。在**密钥**字段中为您的密钥添加名称，然后将私有 SSH 密钥添加到**值**字段中：
![\[查看结果。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-secret.png)
1. 在 Buildkite 管道中，导航到存储库设置并将签出设置为使用 **SSH**。
![\[查看结果。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-repo.png)
1. 更新管道 YAML 步骤以使用 `git-ssh-checkout` 插件。例如，以下管道 YAML 文件使用带有上述 Buildkite 秘密密钥的签出操作：
```
agents:
project: "codebuild-myProject"
steps:
- command: "npm run build"
plugins:
- git-ssh-checkout#v0.4.1:
ssh-secret-key-name: 'SOURCE_SSH_KEY'
```
1. 在其中运行 Buildkite 自托管运行器作业时 CodeBuild，Buildkite 现在将在提取私有存储库时自动使用你配置的密钥值
## 运行程序配置选项
您可以在项目配置中指定以下环境变量，以修改自托管运行程序的设置配置：
+ `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`: CodeBuild 将从 AWS Secrets Manager 中获取配置为该环境变量值的秘密值，以便注册 Buildkite 自托管的运行器代理。此环境变量的类型必须为 `SECRETS_MANAGER`，其值应是您在 Secrets Manager 中的密钥名称。所有 Buildkite 运行程序项目都需要一个 Buildkite 代理令牌环境变量。
+ `CODEBUILD_CONFIG_BUILDKITE_CREDENTIAL_DISABLE`: 默认情况下， CodeBuild会将账户或项目级别的源凭据加载到构建环境中，因为 Buildkite 代理使用这些凭据来提取作业的源存储库。要禁用此行为，您可以将此环境变量添加到项目中，值设置为 `true`，这将防止源凭证加载到构建环境中。