本教程演示了如何配置 CodeBuild 项目来运行 GitHub Actions 作业。有关将 GitHub Actions 与 CodeBuild 结合使用的更多信息,请参阅教程:配置 CodeBuild 托管的 GitHub Actions 运行器。
要完成本教程,您首先必须:
-
使用个人访问令牌、Secrets Manager 密钥、OAuth 应用程序或 GitHub 应用程序进行连接。如果您想使用 OAuth 应用程序来连接,则必须使用 CodeBuild 控制台进行。如果您想创建个人访问令牌,可以使用 CodeBuild 控制台,也可以使用 ImportSourceCredentials API。有关更多说明,请参阅 CodeBuild 中的 GitHub 和 GitHub Enterprise Server 访问。
-
将 CodeBuild 连接到您的 GitHub 账户。为此,您可以执行以下操作之一:
-
您可以以源提供商的身份在控制台中添加 GitHub。您可以使用个人访问令牌、Secrets Manager 密钥、OAuth 应用程序或 GitHub 应用程序进行连接。有关说明,请参阅 CodeBuild 中的 GitHub 和 GitHub Enterprise Server 访问。
-
您可以通过 ImportSourceCredentials API 导入 GitHub 凭证。只有使用个人访问令牌才能执行此操作。如果您使用 OAuth 应用程序来连接,则必须改用控制台进行连接。有关说明,请参阅 使用访问令牌连接 GitHub (CLI) 。
注意
仅当您的账户尚未连接到 GitHub 时,才需要执行此操作。
-
步骤 1:创建带有 webhook 的 CodeBuild 项目
在此步骤中,您将创建一个带有 webhook 的 CodeBuild 项目,并在 GitHub 控制台中进行检查。您也可以选择 GitHub Enterprise 作为源提供商。要了解有关在 GitHub Enterprise 中创建 webhook 的更多信息,请参阅GitHub 手动 webhook。
创建带有 webhook 的 CodeBuild 项目
-
从 https://console.aws.amazon.com/codesuite/codebuild/home
打开 AWS CodeBuild 控制台。 -
创建构建项目。有关信息,请参阅创建构建项目(控制台)和运行构建(控制台)。
-
在源中:
-
对于源提供商,选择 GitHub。
-
在存储库中,选择我的 GitHub 账户中的存储库。
-
对于存储库 URL,输入
https://github.com/
。user-name
/repository-name
注意
默认情况下,您的项目将仅接收单个存储库的
WORKFLOW_JOB_QUEUED
事件。如果您想接收组织或企业内所有存储库的事件,请参阅GitHub 全局和组织 webhook。 -
-
在主要源 Webhook 事件中:
-
在 Webhook - 可选中,选择每次将代码更改推送到此存储库时都会重新构建。
-
在事件类型中,选择 WORKFLOW_JOB_QUEUED。启用此功能后,只能由 GitHub Actions 工作流作业事件触发构建。
注意
只有当 webhook 具有包含 WORKFLOW_JOB_QUEUED 事件筛选条件的筛选条件组时,CodeBuild 才会处理 GitHub Actions 工作流作业事件。
-
-
在环境中:
-
选择支持的环境映像和计算。请注意,您可以选择在 GitHub Actions 工作流 YAML 中使用标签来覆盖映像和实例设置。有关更多信息,请参阅 步骤 2:更新 GitHub Actions 工作流 YAML
-
-
在 Buildspec (构建规范) 中:
-
请注意,除非将
buildspec-override:true
作为标签添加,否则系统会忽略 buildspec。相反,CodeBuild 将覆盖它,以便使用特定命令来设置自托管运行器。
-
-
-
继续使用默认值,然后选择创建构建项目。
-
在
https://github.com/
打开 GitHub 控制台,确认已创建一个 webhook,并已启用来传递工作流作业事件。user-name
/repository-name
/settings/hooks
步骤 2:更新 GitHub Actions 工作流 YAML
在此步骤中,您将在 GitHub
更新 GitHub Actions 工作流 YAML
导航至 GitHub
runs-on
-
您可以指定项目名称和运行 ID,在这种情况下,构建将使用计算、映像、映像版本和实例大小的现有项目配置。需要有项目名称才能将 GitHub Actions 作业的 AWS 相关设置链接到特定 CodeBuild 项目。通过在 YAML 中包括项目名称,CodeBuild 可以调用具有正确项目设置的作业。通过提供运行 ID,CodeBuild 会将您的构建映射到特定的工作流运行,并在工作流运行取消时停止构建。有关更多信息,请参阅
github
上下文。 runs-on: codebuild-
<project-name>
-${{ github.run_id }}-${{ github.run_attempt }}注意
确保您的
<project-name>
与您在上一步中创建的项目名称匹配。如果不匹配,CodeBuild 将无法处理 webhook,GitHub Actions 工作流可能会挂起。以下是 GitHub Actions 工作流 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 Actions 运行器支持的映像。标签中的计算类型和映像将覆盖项目的环境设置。要覆盖 CodeBuild EC2 或 Lambda 计算构建的环境设置,请使用以下语法:
runs-on: - codebuild-
<project-name>
-${{ github.run_id }}-${{ github.run_attempt }} - image:<environment-type>
-<image-identifier>
- instance-size:<instance-size>
以下是 GitHub Actions 工作流 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!"
-
您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置,以便使用指定的实例集。有关更多信息,请参阅 在预留容量实例集上运行构建。要覆盖 Amazon EC2 计算构建的实例集设置,请使用以下语法:
runs-on: - codebuild-
<project-name>
-${{ github.run_id }}-${{ github.run_attempt }} - fleet:<fleet-name>
要同时覆盖构建所用的实例集和映像,请使用以下语法:
runs-on: - codebuild-
<project-name>
-${{ github.run_id }}-${{ github.run_attempt }} - fleet:<fleet-name>
- image:<environment-type>
-<image-identifier>
以下是 GitHub Actions 工作流 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!"
-
要在自定义映像中运行 GitHub Actions 作业,您可以在 CodeBuild 项目中配置自定义映像,这样就不需要提供映像覆盖标签。如果未提供映像覆盖标签,CodeBuild 将使用项目中配置的映像。
-
(可选)您可以提供 CodeBuild 支持的标签以外的其他标签。在覆盖构建的属性时会忽略这些标签,但不会导致 webhook 请求失败。例如,添加
testLabel
作为标签不会阻止构建运行。
注意
如果 GitHub 托管的运行器提供的依赖项在 CodeBuild 环境中不可用,则可以在工作流运行中使用 GitHub Actions 安装依赖项。例如,您可以使用 setup-python
在 INSTALL、PRE_BUILD 和 POST_BUILD 阶段运行 buildspec 命令
默认情况下,在运行自托管 GitHub Actions 构建时,CodeBuild 会忽略任何 buildspec 命令。要在构建期间运行 buildspec 命令,可以将 buildspec-override:true
作为后缀添加到标签中:
runs-on: - codebuild-
<project-name>
-${{ github.run_id }}-${{ github.run_attempt }} - buildspec-override:true
通过使用此命令,CodeBuild 将在容器的主源文件夹中创建一个名为 actions-runner
的文件夹。当 GitHub Actions 运行器在 BUILD
阶段启动时,运行器将在 actions-runner
目录中运行。
在自托管 GitHub Actions 构建中使用 buildspec 覆盖有几个限制:
-
因为自托管运行器在
BUILD
阶段运行,CodeBuild 不会在BUILD
阶段运行 buildspec 命令。 -
在
DOWNLOAD_SOURCE
阶段,CodeBuild 不会下载任何主源或辅助源。如果您配置了 buildspec 文件,则只会从项目的主源下载该文件。 -
如果构建命令在
PRE_BUILD
或INSTALL
阶段失败,则 CodeBuild 将不会启动自托管运行器,并且需要手动取消 GitHub Actions 工作流作业。 -
CodeBuild 将在
DOWNLOAD_SOURCE
阶段获取运行器令牌,该阶段的过期时间为一小时。如果PRE_BUILD
或INSTALL
阶段超过一小时,则运行器令牌可能会在 GitHub 自托管运行器启动之前过期。
步骤 3:检查您的结果
每当 GitHub Actions 工作流运行时,CodeBuild 都会通过 webhook 接收工作流作业事件。对于工作流中的每项作业,CodeBuild 都会启动一个构建来运行临时的 GitHub Actions 运行器。该运行器负责执行单个工作流作业。作业完成后,运行器和关联的构建过程会立即终止。
要查看工作流作业日志,请在 GitHub 中导航到您的存储库,选择操作,选择所需的工作流,然后选择要查看日志的特定作业。
在 CodeBuild 中等待自托管运行器提取作业时,您可以在日志中查看请求的标签。
![正在加载作业的日志。](images/hello-world-loading.png)
作业完成后,您将能够查看该作业的日志。
![作业的日志。](images/hello-world-log.png)
筛选 GitHub Actions webhook 事件(AWS CloudFormation)
AWS CloudFormation 模板的以下 YAML 格式部分创建一个筛选条件组,该组在计算结果为 true 时会触发构建。以下筛选条件组指定 GitHub Actions 工作流作业请求,其工作流名称与正则表达式 \[CI-CodeBuild\]
匹配。
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
FilterGroups:
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
筛选 GitHub Actions webhook 事件(AWS CDK)
以下 AWS CDK 模板创建一个筛选条件组,该组在计算结果为 true 时会触发构建。以下筛选条件组指定 GitHub Actions 工作流作业请求。
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 Actions webhook 事件(Terraform)
以下 Terraform 模板创建一个筛选条件组,该组在计算结果为 true 时会触发构建。以下筛选条件组指定 GitHub Actions 工作流作业请求。
resource "aws_codebuild_webhook" "example" {
project_name = aws_codebuild_project.example.name
build_type = "BUILD"
filter_group {
filter {
type = "EVENT"
pattern = "WORKFLOW_JOB_QUEUED"
}
}
}