本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 教程：配置 CodeBuild托管的 GitHub 操作运行器
本教程向您展示如何配置 CodeBuild 项目以运行 Action GitHub s 作业。有关将 GitHub 操作与配合使用的更多信息， CodeBuild 请参阅[教程：配置 CodeBuild托管的 GitHub 操作运行器](#action-runner)。
要完成本教程，您首先必须：
+ 使用个人访问令牌、Secrets Manager 密钥、 OAuth 应用程序或 GitHub 应用程序进行连接。如果您想连接 OAuth 应用程序，则必须使用 CodeBuild 控制台进行连接。如果您想创建个人访问令牌，则可以使用 CodeBuild 控制台或使用 [ImportSourceCredentials API](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ImportSourceCredentials.html)。有关更多说明，请参阅 [GitHub 和 GitHub 企业服务器访问权限 CodeBuild](access-tokens-github-overview.md)。
+ Connect CodeBuild 到您的 GitHub 账户。为此，您可以执行以下操作之一：
+ 您可以在控制台中添加 GitHub 为源提供商。您可以使用个人访问令牌、Secrets Manager 密钥、 OAuth 应用程序或 GitHub 应用程序进行连接。有关说明，请参阅[GitHub 和 GitHub 企业服务器访问权限 CodeBuild](access-tokens-github-overview.md)。
+ 您可以通过 [ImportSourceCredentials API](https://docs.aws.amazon.com/cli/latest/reference/codebuild/import-source-credentials.html) 导入您的 GitHub 证书。只有使用个人访问令牌才能执行此操作。如果您使用 OAuth 应用程序进行连接，则必须改用控制台进行连接。有关说明，请参阅[GitHub 使用访问令牌 (CLI) 连接](access-tokens-github.md#access-tokens-github-cli)。
**注意**
只有当你的账户还没有连接时， GitHub 才需要这样做。
## 第 1 步：使用 webhook 创建 CodeBuild 项目
在此步骤中，您将创建一个带有 webhook 的 CodeBuild 项目，并在 GitHub 控制台中对其进行审核。您也可以选择 E GitHub nterprise 作为您的源提供商。要了解有关在 GitHub 企业版中创建 webhook 的更多信息，请参阅[GitHub 手动 webhook](github-manual-webhook.md)。
**使用 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)。
1. 在**项目类型**中，选择**运行程序项目**。
在**运行程序**中：
1. 对于**跑步者提供商**，请选择**GitHub**。
1. 对于**运行程序位置**，请选择**存储库**。
1. 在 “存储库” 下的 “**存储库 URL” 中**，选择**https://github.com/user-name/存储库名称**。
**注意**
默认情况下，您的项目将仅接收单个存储库的 `WORKFLOW_JOB_QUEUED` 事件。如果您想接收组织或企业内所有存储库的事件，请参阅[GitHub 全球和组织 webhook](github-global-organization-webhook.md)。
1.
+ 在**环境**中：
+ 选择支持的**环境映像**和**计算**。请注意，您可以选择在 GitHub 操作工作流程 YAML 中使用标签来覆盖图像和实例设置。有关更多信息，请参阅 [第 2 步：更新您的 GitHub 操作工作流程 YAML](#sample-github-action-runners-update-yaml)。
+ 在 **Buildspec (构建规范)** 中：
+ 请注意，除非将 `buildspec-override:true` 作为标签添加，否则系统会忽略 buildspec。相反， CodeBuild 将覆盖它以使用设置自托管运行器的命令。
1. 继续使用默认值，然后选择**创建构建项目**。
1. 打开 GitHub 控制台，验证是否已创建一个 webhook 并已启用 webhook 来传送**工作流作业**事件。`https://github.com/user-name/repository-name/settings/hooks`
## 第 2 步：更新您的 GitHub 操作工作流程 YAML
在此步骤中，您将更新 GitHub 操作工作流程 YAML 文件[https://github.com/](https://github.com/)以配置您的构建环境并在中使用 GitHub Actions 自托管运行器。 CodeBuild有关更多信息，请参阅[在自托管运行器中使用标签](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners)和[CodeBuild托管的操作运行器支持的 GitHub 标签覆盖](sample-github-action-runners-update-labels.md)。
### 更新你的 GitHub 操作工作流程 YAML
导航到 GitHub 操作工作流程 YAML 中的[https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners)设置[https://github.com/](https://github.com/)并进行更新，以配置您的构建环境。为此，您可以执行以下操作之一：
+ 您可以指定项目名称和运行 ID，在这种情况下，构建将使用计算、映像、映像版本和实例大小的现有项目配置。需要项目名称才能将 Actions 作业的 AWS相关设置链接到特定 CodeBuild项目。 GitHub 通过在 YAML 中包含项目名称 CodeBuild ，可以调用具有正确项目设置的作业。通过提供运行 ID， CodeBuild 会将您的构建映射到特定的工作流程运行，并在取消工作流程运行时停止构建。有关更多信息，请参阅 [`github` 上下文](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context)。
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}
```
**注意**
请确保您的名称与您在上一步中创建的项目名称**相匹配。如果不匹配， CodeBuild 则不会处理 webhook， GitHub操作工作流程可能会挂起。
以下是 GitHub 操作工作流程 YAML 的示例：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
steps:
- run: echo "Hello World!"
```
+ 您也可以在标签中覆盖映像和计算类型。有关精选映像的列表，请参阅[计算 CodeBuild托管的 GitHub 操作运行器支持的图像](sample-github-action-runners-update-yaml.images.md)。有关使用自定义映像，请参阅[CodeBuild托管的操作运行器支持的 GitHub 标签覆盖](sample-github-action-runners-update-labels.md)。标签中的计算类型和映像将覆盖项目的环境设置。要替换 CodeBuild EC2 或 Lambda 计算版本的环境设置，请使用以下语法：
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
image:-
instance-size:
```
以下是 GitHub 操作工作流程 YAML 的示例：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
image:arm-3.0
instance-size:small
steps:
- run: echo "Hello World!"
```
+ 您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅 [在预留容量实例集上运行构建](fleets.md)。要覆盖 Amazon EC2 计算构建的实例集设置，请使用以下语法：
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
fleet:
```
要同时覆盖构建所用的实例集和映像，请使用以下语法：
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
fleet:
image:-
```
以下是 GitHub 操作工作流程 YAML 的示例：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
fleet:myFleet
image:arm-3.0
steps:
- run: echo "Hello World!"
```
+ 要在自定义图像上运行 Actions GitHub 作业，您可以在 CodeBuild 项目中配置自定义图像，避免提供图像覆盖标签。 CodeBuild 如果未提供图像覆盖标签，则将使用项目中配置的图像。
+ 或者，您可以在 CodeBuild 支持的标签之外提供标签。在覆盖构建的属性时会忽略这些标签，但不会导致 webhook 请求失败。例如，添加 `testLabel` 作为标签不会阻止构建运行。
**注意**
如果 GitHub托管运行器提供的依赖项在 CodeBuild环境中不可用，则可以在工作流程运行中使用 Acti GitHub ons 安装依赖项。例如，您可以使用 [https://github.com/actions/setup-python](https://github.com/actions/setup-python) 操作为构建环境安装 Python。
### 在 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 阶段运行 buildspec 命令
默认情况下，在运行自托管 GitHub 的 Actions 版本时 CodeBuild 会忽略所有 buildspec 命令。要在构建期间运行 buildspec 命令，可以将 `buildspec-override:true` 作为后缀添加到标签中：
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
buildspec-override:true
```
通过使用此命令， CodeBuild 将在容器的主源文件夹`actions-runner`中创建一个名为的文件夹。当 Ac GitHub tions 运行器在该`BUILD`阶段启动时，运行器将在`actions-runner`目录中运行。
在自托管的 Actions 版本中使用 buildspec 覆盖有几个限制 GitHub ：
+ CodeBuild 在此`BUILD`阶段不会运行 buildspec 命令，因为自托管运行器将在该`BUILD`阶段运行。
+ CodeBuild 在此`DOWNLOAD_SOURCE`阶段不会下载任何主要或次要来源。如果您配置了 buildspec 文件，则只会从项目的主源下载该文件。
+ 如果构建命令在`PRE_BUILD`或`INSTALL`阶段失败， CodeBuild 则无法启动自托管运行器，并且需要手动取消 GitHub 操作工作流程作业。
+ CodeBuild 在该阶段获取跑步者令牌，该`DOWNLOAD_SOURCE`阶段的到期时间为一小时。如果您的`PRE_BUILD`或`INSTALL`阶段超过一小时，则运行器令牌可能会在 GitHub 自托管运行器启动之前过期。
## 步骤 3：检查您的结果
每当 GitHub 操作工作流程运行时， CodeBuild 都会通过 webhook 接收工作流程作业事件。对于工作流程中的每个作业， CodeBuild 启动构建以运行临时的 Actions GitHub 运行器。该运行器负责执行单个工作流作业。作业完成后，运行器和关联的构建过程会立即终止。
要查看您的工作流程作业日志，请导航到中的 GitHub存储库，选择**操作**，选择所需的工作流程，然后选择要查看日志的特定**作业**。
当任务等待中的自托管运行器接管时，您可以在日志中 CodeBuild查看请求的标签。
![\[正在加载作业的日志。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/hello-world-loading.png)
作业完成后，您将能够查看该作业的日志。
![\[作业的日志。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/hello-world-log.png)
## GitHub 操作运行器配置选项
您可以在项目配置中指定以下环境变量，以修改自托管运行程序的设置配置。
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME`
CodeBuild 会将自托管的运行器注册到指定为该环境变量值的组织名称。有关在组织级别注册运行器和必要权限的更多信息，请参阅[为组织的 just-in-time运行器创建配置](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-organization)。
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ENTERPRISE_REGISTRATION_NAME`
CodeBuild 会将自托管的运行器注册到指定为该环境变量值的企业名称。有关在企业级别注册运行器和必要权限的更多信息，请参阅[为企业 just-in-time运行器创建配置](https://docs.github.com/en/enterprise-server/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-enterprise)。
默认情况下，企业运行程序不可用于组织存储库。要让自托管运行程序承担工作流程作业，您可能需要配置运行程序组访问权限设置。有关更多信息，请参阅 [Making enterprise runners available to repositories](https://docs.github.com/en/enterprise-server/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#making-enterprise-runners-available-to-repositories)。
`CODEBUILD_CONFIG_GITHUB_ACTIONS_RUNNER_GROUP_ID`
CodeBuild 会将自托管的运行器注册到存储为该环境变量值的整数运行器组 ID。默认情况下，该值为 1。有关自托管运行程序组的更多信息，请参阅 [Managing access to self-hosted runners using groups](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-organization)。
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME`
要使用 GitHub操作工作流程 YAML 文件配置组织级别的运行器注册，可以使用以下语法：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
organization-registration-name:myOrganization
steps:
- run: echo "Hello World!"
```
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ENTERPRISE_REGISTRATION_NAME`
要使用 GitHub操作工作流程 YAML 文件配置企业级运行器注册，可以使用以下语法：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
enterprise-registration-name:myEnterprise
steps:
- run: echo "Hello World!"
```
`CODEBUILD_CONFIG_GITHUB_ACTIONS_RUNNER_GROUP_ID`
要使用 GitHub 操作工作流程 YAML 文件配置将运行器注册到特定的运行器组 ID，可以使用以下语法：
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
registration-group-id:3
steps:
- run: echo "Hello World!"
```
## 筛选 GitHub 操作 webhook 事件 ()CloudFormation
CloudFormation 模板的以下 YAML 格式部分创建一个筛选条件组，该组在计算结果为 true 时会触发构建。以下筛选器组指定了工作流名称与正则表达式匹配的 Actions 工作流任务请求`\[CI-CodeBuild\]`。 GitHub
```
CodeBuildProject:
Type: AWS::CodeBuild::Project
Properties:
Name: MyProject
ServiceRole: service-role
Artifacts:
Type: NO_ARTIFACTS
Environment:
Type: LINUX_CONTAINER
ComputeType: BUILD_GENERAL1_SMALL
Image: aws/codebuild/standard:5.0
Source:
Type: GITHUB
Location: CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION
Triggers:
Webhook: true
ScopeConfiguration:
Name: organization-name
Scope: GITHUB_ORGANIZATION
FilterGroups:
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
## 筛选 GitHub 操作 webhook 事件 ()AWS CDK
以下 AWS CDK 模板创建了一个筛选器组，当生成结果为 true 时会触发构建。以下筛选器组指定了 GitHub 操作工作流程任务请求。
```
import { aws_codebuild as codebuild } from 'aws-cdk-lib';
import {EventAction, FilterGroup} from "aws-cdk-lib/aws-codebuild";
const source = codebuild.Source.gitHub({
owner: 'owner',
repo: 'repo',
webhook: true,
webhookFilters: [FilterGroup.inEventOf(EventAction.WORKFLOW_JOB_QUEUED)],
})
```
## 筛选 GitHub 操作 webhook 事件 (Terraform)
以下 Terraform 模板创建一个筛选条件组，该组在计算结果为 true 时会触发构建。以下筛选器组指定了 GitHub 操作工作流程任务请求。
```
resource "aws_codebuild_webhook" "example" {
project_name = aws_codebuild_project.example.name
build_type = "BUILD"
filter_group {
filter {
type = "EVENT"
pattern = "WORKFLOW_JOB_QUEUED"
}
}
}
```
## 筛选 GitHub 操作 webhook 事件 ()AWS CLI
以下 AWS CLI 命令创建一个自托管 GitHub 的 Actions 运行器项目，其中包含一个 Acti GitHub ons 工作流任务请求筛选器组，该筛选器组在计算结果为 true 时触发构建。
```
aws codebuild create-project \
--name \
--source "{\"type\":\"GITHUB\",\"location\":\"\",\"buildspec\":\"\"}" \
--artifacts {"\"type\":\"NO_ARTIFACTS\""} \
--environment "{\"type\": \"LINUX_CONTAINER\",\"image\": \"aws/codebuild/amazonlinux-x86_64-standard:5.0\",\"computeType\": \"BUILD_GENERAL1_MEDIUM\"}" \
--service-role ""
```
```
aws codebuild create-webhook \
--project-name \
--filter-groups "[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"}]]"
```