本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 将跑步器搭配使用 AWS CodeBuild AWS CodeBuild 支持与 Action GitHub s 运行器、自我管理的 GitLab 运行器和 Buildkite 运行器集成。 **Topics** + [ # 自托管的 GitHub 操作运行器在 AWS CodeBuild ](action-runner-overview.md) + [ # 自我管理的 GitLab 跑步者在 AWS CodeBuild ](gitlab-runner.md) + [ # 自我管理的 Buildkite 运行器进来了 AWS CodeBuild ](buildkite-runner.md) # 自托管的 GitHub 操作运行器在 AWS CodeBuild 您可以将项目配置为在 CodeBuild容器中设置自托管的 Action GitHub s 运行器来处理您的 Actions 工作流程 GitHub 作业。这可以通过使用您的 CodeBuild 项目设置 webhook，然后更新 GitHub 操作工作流程 YAML 以使用托管在计算机上的自托管运行器来完成。 CodeBuild 配置 CodeBuild 项目以运行 GitHub 操作作业的高级步骤如下： 1. 如果您还没有这样做，请创建个人访问令牌或连接 OAuth 应用程序以将您的项目连接到该应用程序 GitHub。 1. 导航到 CodeBuild 控制台并使用 webhook 创建 CodeBuild 项目，然后设置 webhook 过滤器。 1. 更新您的 GitHub 操作工作流程 YAML GitHub 以配置您的构建环境。 有关更详细的过程，请参阅[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。 此功能允许您的 A GitHub ctions 工作流程任务与之进行原生集成 AWS，从而通过 IAM AWS CloudTrail、 AWS Secrets Manager 集成和 Amazon VPC 等功能提供安全性和便利性。您可以访问最新的实例类型，包括基于 ARM 的实例。 **Topics** + [ # 关于 CodeBuild托管的 GitHub 操作运行器 ](action-runner-questions.md) + [ # 教程：配置 CodeBuild托管的 GitHub 操作运行器 ](action-runner.md) + [ # 排查 webhook 的问题 ](action-runner-troubleshoot-webhook.md) + [ # CodeBuild托管的操作运行器支持的 GitHub 标签覆盖 ](sample-github-action-runners-update-labels.md) + [ # 计算 CodeBuild托管的 GitHub 操作运行器支持的图像 ](sample-github-action-runners-update-yaml.images.md) # 关于 CodeBuild托管的 GitHub 操作运行器 以下是有关 CodeBuild托管 GitHub 操作运行器的一些常见问题。 ## 我应该何时在标签中包括映像和实例覆盖？ 您可以在标签中包含图像和实例覆盖，以便为每个 Actions 工作流程任务指定不同的构建环境。 GitHub 无需创建多个 CodeBuild 项目或 webhook 即可完成此操作。例如，当您需要[为工作流作业使用矩阵](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs)时，这很有用。 ``` name: Hello World on: [push] jobs: Hello-World-Job: runs-on: - codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }} image:${{ matrix.os }} instance-size:${{ matrix.size }} strategy: matrix: include: - os: arm-3.0 size: small - os: linux-5.0 size: large steps: - run: echo "Hello World!" ``` **注意** 如果`runs-on`有多个包含 GitHub 操作上下文的标签，则可能需要使用引号。 ## 我可以 CloudFormation 用这个功能吗？ 是的，您可以在 CloudFormation 模板中包含一个筛选器组，用于在项目 webhook 中指定 GitHub操作工作流程作业事件过滤器。 ``` Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED ``` 有关更多信息，请参阅 [筛选 GitHub webhook 事件 ()CloudFormation](github-webhook-events-cfn.md)。 如果您在 CloudFormation 模板中设置项目凭证时需要帮助，请参阅*AWS CloudFormation 用户指南[AWS::CodeBuild::SourceCredential](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-sourcecredential.html)*中的了解更多信息。 ## 使用此特征时如何屏蔽密钥？ 默认情况下，系统不会屏蔽日志中显示的密钥。如果您想屏蔽密钥，可以使用以下语法：`::add-mask::value`。以下是如何在 YAML 中使用此语法的示例： ``` name: Secret Job on: [push] jobs: Secret-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }} env: SECRET_NAME: "secret-name" steps: - run: echo "::add-mask::$SECRET_NAME" ``` 有关更多信息，请参阅[屏蔽登录 GitHub中的值](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#masking-a-value-in-a-log)。 ## 我能否在一个项目中接收 GitHub 来自多个存储库的 Actions webhook 事件？ CodeBuild 支持组织和全局级 webhook，它们接收来自指定组织或企业的事件。有关更多信息，请参阅 [GitHub 全球和组织 webhook](github-global-organization-webhook.md)。 ## 哪些区域支持使用 CodeBuild托管的 GitHub 操作运行器？ CodeBuild所有 CodeBuild 区域都支持托管的 GitHub 操作运行器。有关 AWS 区域 何处 CodeBuild 可用的更多信息，请参阅[按地区划分的AWS 服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。 ## 哪些平台支持使用 CodeBuild托管的 GitHub 操作运行器？ CodeBuildAmazon EC2 和[AWS Lambda](lambda.md)计算均支持托管的 GitHub 操作运行器。您可以使用以下平台：Amazon Linux 2、Amazon Linux 2023、Ubuntu 和 Windows Server Core 2019。有关更多信息，请参阅[EC2 计算映像](ec2-compute-images.md)和[Lambda 计算映像](lambda-compute-images.md)。 # 教程：配置 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\"}]]" ``` # 排查 webhook 的问题 **问题：**您在中设置的 webhook [教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md) 无法正常工作或您的工作流程任务暂停。 GitHub **可能的原因：** + 您的 webhook **工作流程作业**事件可能无法触发构建。检查**响应**日志以查看响应或错误消息。 + 由于标签配置，您的作业分配给了不正确的运行程序代理。当单个工作流程运行中一个作业的标签少于另一个作业时，就会出现此问题。例如，如果您在同一个工作流程运行中具有两个带有以下标签的作业： + **作业 1**：`codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}` + **作业 2**：`codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}`、`instance-size:medium` 路由自托管的 Ac GitHub tions 作业时， GitHub 会将该任务路由到具有所有作业指定标签的任何运行器。此行为意味着为**作业 1** 或**作业 2** 创建的运行程序可以承担**作业 1**，但是由于**作业 2** 有附加标签，因此只能由为**作业 2** 创建的运行程序承担该作业。如果为**作业 2** 创建的运行程序承担了**作业 1**，则**作业 2** 将卡住，因为**作业 1** 运行程序没有 `instance-size:medium` 标签。 **推荐的解决方案：** 在同一个工作流程运行中创建多个作业时，请为每个作业使用相同数量的标签覆盖，或者为每个作业分配一个自定义标签，例如 `job1` 或 `job2`。 如果错误仍然存在，请按照以下说明调试问题。 1. 打开 GitHub 控制台，查看存储库的 webhook 设置。`https://github.com/user-name/repository-name/settings/hooks`在此页面上，您将看到为您的存储库创建的 webhook。 1. 选择**编辑**并确认已启用该 webhook 来传递**工作流作业**事件。 ![\[工作流作业事件已在您的 webhook 中启用。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-actions-workflow-jobs.png) 1. 导航至**最近传输**选项卡，找到相应的 `workflow_job.queued` 事件，然后展开该事件。 1. 查看**负载**中的**标签**字段，并确保该字段符合预期。 1. 最后，查看 “**响应**” 选项卡，因为其中包含返回的响应或错误消息 CodeBuild。 ![\[返回的响应或错误消息 CodeBuild。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-actions-workflow-jobs-response.png) 1. 或者，你可以使用 GitHub's APIs 调试 webhook 故障。您可以使用[列出存储库 webhook 的传输](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#list-deliveries-for-a-repository-webhook) API 来查看 webhook 的近期传输： ``` gh api \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2022-11-28" \ /repos/owner/repo/hooks/hook-id/deliveries ``` 找到要调试的 webhook 交付并记下交付 ID 后，您可以使用[获取存储库 webhook 的交付](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#get-a-delivery-for-a-repository-webhook) API。 CodeBuild对 webhook 交付有效负载的响应可以在以下`response`部分中找到： ``` gh api \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2022-11-28" \ /repos/owner/repo/hooks/hook-id/deliveries/delivery-id ``` **问题：**启用[部署保护](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments)规则的 GitHub 操作会在部署获得批准 CodeBuild 之前在内部生成触发器。 **可能的原因：** CodeBuild 获取与 Actions 作业关联的 GitHub 部署和环境（如果存在），以验证是否获得批准。如果 CodeBuild 无法获取部署或环境，则可能会过早触发 CodeBuild 构建。 **推荐的解决方案：**验证与您的 CodeBuild 项目关联的凭证是否具有内部部署和操作的读取权限 GitHub。 # CodeBuild托管的操作运行器支持的 GitHub 标签覆盖 在你的 A GitHub ctions 工作流程 YAML 中，你可以提供各种标签覆盖来修改你的自托管运行器构建。任何未被识别的版本都 CodeBuild 将被忽略，但不会使您的 webhook 请求失败。例如，以下工作流程 YAML 包括映像、实例大小、实例集和 buildspec 的覆盖： ``` name: Hello World on: [push] jobs: Hello-World-Job: runs-on: - codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }} image:${{ matrix.os }} instance-size:${{ matrix.size }} fleet:myFleet buildspec-override:true strategy: matrix: include: - os: arm-3.0 size: small - os: linux-5.0 size: large steps: - run: echo "Hello World!" ``` **注意** 如果您的工作流程任务处于暂停 GitHub状态，请参阅[排查 webhook 的问题](action-runner-troubleshoot-webhook.md)和[使用自定义标签路由作业](https://docs.github.com/en/enterprise-server@3.12/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow?learn=hosting_your_own_runners&learnProduct=actions#using-custom-labels-to-route-jobs)。 `codebuild--${{github.run_id}}-${{github.run_attempt}}`（必需） + 示例：`codebuild-fake-project-${{ github.run_id }}-${{ github.run_attempt }}` + 所有 GitHub 操作工作流程均为必填项 YAMLs。 **应等于为其配置自托管运行器 webhook 的项目的名称。 `image:-` + 示例：`image:arm-3.0` + 覆盖在通过精选映像启动自托管运行程序构建时使用的映像和环境类型。要了解支持的值，请参阅[计算 CodeBuild托管的 GitHub 操作运行器支持的图像](sample-github-action-runners-update-yaml.images.md)。 + 要覆盖与自定义映像结合使用的映像和环境类型，请使用 `image:custom--` + 示例：`image:custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0` **注意** 如果自定义映像位于私有注册表中，请参阅[为自托管运行程序配置私有注册表凭证](private-registry-sample-configure-runners.md)。 `instance-size:` + 示例：`instance-size:medium` + 覆盖在启动自托管运行器构建时使用的实例类型。要了解支持的值，请参阅[计算 CodeBuild托管的 GitHub 操作运行器支持的图像](sample-github-action-runners-update-yaml.images.md)。 `fleet:` + 示例：`fleet:myFleet` + 覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅 [在预留容量实例集上运行构建](fleets.md)。 `buildspec-override:` + 示例：`buildspec-override:true` + 如果设置为 `true`，则允许构建以在 `INSTALL`、`PRE_BUILD` 和 `POST_BUILD` 阶段运行 buildspec 命令。 ## 单个标签覆盖（旧版） CodeBuild 允许您使用以下方法在单个标签中提供多个覆盖： + 要覆盖 Amazon EC2/Lambda 计算构建的环境设置，请使用以下语法： ``` runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}--- ``` + 要覆盖 Amazon EC2 计算构建的实例集设置，请使用以下语法： ``` runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}-fleet- ``` + 要同时覆盖构建所用的实例集和映像，请使用以下语法： ``` runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}-image--fleet- ``` + 要在构建期间运行 buildspec 命令，可以将 `-with-buildspec` 作为后缀添加到标签中： ``` runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}----with-buildspec ``` + 或者，您也可以提供实例大小覆盖，而不覆盖映像。对于 Amazon EC2 构建，您可以排除环境类型和映像标识符。对于 Lambda 构建，您可以排除映像标识符。 # 计算 CodeBuild托管的 GitHub 操作运行器支持的图像 在中配置的标签中[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)，您可以使用前三列中的值来覆盖您的 Amazon EC2 环境设置。 CodeBuild 提供了以下 Amazon EC2 计算映像。有关 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/sample-github-action-runners-update-yaml.images.html) 此外，您还可以使用以下值来覆盖 Lambda 环境设置。有关 CodeBuild Lambda 计算的更多信息，请参阅。[在 AWS Lambda 计算基础上运行构建](lambda.md) CodeBuild 支持以下 Lambda 计算映像： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/sample-github-action-runners-update-yaml.images.html) 有关更多信息，请参阅[构建环境计算模式和类型](build-env-ref-compute-types.md)和[提供的 Docker 镜像 CodeBuild](build-env-ref-available.md)。 # 自我管理的 GitLab 跑步者在 AWS CodeBuild GitLab 提供了两种执行模式来运行 CI/CD 管道中的 GitLab 作业。一种模式是 GitLab托管的运行器，它由托管运行器管理 GitLab 并与 GitLab之完全集成。另一种模式是自我管理的运行器，它允许您使用自己的自定义环境来运行 GitLab CI/CD 管道中的作业。 配置 CodeBuild 项目以运行 C GitLab I/CD 管道作业的高级步骤如下： 1. 如果你还没有这样做，请连接一个 OAuth 应用程序来连接你的项目 GitLab。 1. 导航到 CodeBuild 控制台并使用 webhook 创建 CodeBuild 项目，然后设置 webhook 过滤器。 1. 更新您的 GitLab CI/CD 管道 YAML GitLab 以配置您的构建环境。 有关更详细的过程，请参阅[教程：配置 CodeBuild托管的运行器 GitLab](sample-gitlab-runners.md)。 此功能允许您的 GitLab CI/CD 管道任务与之进行原生集成 AWS，从而通过 IAM 和 Amazon VPC 等功能提供安全性和便利性。 AWS CloudTrail您可以访问最新的实例类型，包括基于 ARM 的实例。 **Topics** + [ # 关于 CodeBuild托管的运行器 GitLab ](gitlab-runner-questions.md) + [ # 教程：配置 CodeBuild托管的运行器 GitLab ](sample-gitlab-runners.md) + [ # 托管的运行器支持的标签覆盖 CodeBuild GitLab ](gitlab-runners-update-labels.md) + [ # 计算 CodeBuild托管运行器支持的 GitLab 映像 ](sample-gitlab-runners-gitlab-ci.images.md) # 关于 CodeBuild托管的运行器 GitLab 以下是有关 CodeBuild托管 GitLab运行器的一些常见问题。 ## CodeBuild托管的 GitLab 运行器支持哪些源类型？ CodeBuild`GITLAB`和`GITLAB_SELF_MANAGED`源类型支持托管的 GitLab 运行器。 ## 我应该何时在标签中包括映像和实例覆盖？ 您可以在标签中包含映像和实例替换，以便为每个 C GitLab I/CD 管道任务指定不同的构建环境。无需创建多个 CodeBuild 项目或 webhook 即可完成此操作。 ## 我可以 CloudFormation 用这个功能吗？ 是的，您可以在 CloudFormation 模板中包含一个筛选器组，用于在项目 webhook 中指定 GitLab 工作流程作业事件过滤器。 ``` Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED ``` 有关更多信息，请参阅 [筛选 GitLab webhook 事件 ()CloudFormation](gitlab-webhook-events-cfn.md)。 如果您在 CloudFormation 模板中设置项目凭证时需要帮助，请参阅*AWS CloudFormation 用户指南[AWS::CodeBuild::SourceCredential](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-sourcecredential.html)*中的了解更多信息。 ## 使用此特征时如何屏蔽密钥？ 默认情况下，系统不会屏蔽日志中显示的密钥。如果你想掩盖你的秘密，你可以通过更新你的 CI/CD 环境变量设置来实现： **掩盖秘密 GitLab** 1. 在 **GitLab “设置”** 中，选择 **CI/CD**。 1. 在**变量**中，为要屏蔽的密钥选择**编辑**。 1. 在**可见性**中，选择**屏蔽变量**，然后选择**更新变量**来保存更改。 ## 我能否在一个群组中接收来自多个项目的 GitLab webhook 事件？ CodeBuild 支持群组 webhook，用于接收来自指定 GitLab 群组的事件。有关更多信息，请参阅 [GitLab 群组 webhook](gitlab-group-webhook.md)。 ## 我能否在 Docker 执行器中为自行管理的运行器执行作业？ 例如，我想在特定映像上运行管线作业，以便在单独和隔离的容器中维护相同的构建环境。 您可以通过 CodeBuild 使用[自定义映像创建项目或覆盖文件中的镜像来运行带有特定映像](create-project.md#environment-image.console)[的 GitLab ](sample-gitlab-runners.md#sample-gitlab-runners-gitlab-ci)自管理运行`.gitlab-ci.yml`器。 ## 自我管理的跑步者与哪个执行者一起 CodeBuild 运行？ 中的自管理运行器与 shell 执行器一起 CodeBuild 运行，其中构建与在 docker 容 GitLab 器内运行的运行器一起在本地运行。 ## 我能否在使用自行管理的运行器时提供 buildspec 命令？ 是的，可以将 buildspec 命令与自行管理的运行器一起添加。你可以在 GitLab 仓库中提供 buildspec.yml 文件，然后在作业的 “`buildspec-override:true`标签” 部分使用**标签**。有关更多信息，请参阅 [buildspec 文件名称和存储位置](build-spec-ref.md#build-spec-ref-name-storage)。 ## 哪些区域支持使用 CodeBuild托管的 GitLab 运行器？ CodeBuild所有 CodeBuild 区域都支持托管的 GitLab 运行器。有关 AWS 区域 何处 CodeBuild 可用的更多信息，请参阅[按地区划分的AWS 服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。 ## 哪些平台支持使用 CodeBuild托管的 GitLab 运行器？ CodeBuildAmazon EC2 和[AWS Lambda](lambda.md)计算均支持托管的 GitLab 运行器。您可以使用以下平台：Amazon Linux 2、Amazon Linux 2023、Ubuntu 和 Windows Server Core 2019。有关更多信息，请参阅[EC2 计算映像](ec2-compute-images.md)和[Lambda 计算映像](lambda-compute-images.md)。 # 教程：配置 CodeBuild托管的运行器 GitLab 本教程向您展示如何配置 CodeBuild 项目以运行 C GitLab I/CD 管道作业。有关使用 GitLab 或使用 GitLab 自助管理的更多信息 CodeBuild，请参阅[自我管理的 GitLab 跑步者在 AWS CodeBuild](gitlab-runner.md)。 要完成本教程，您首先必须： + 使用 Connect 与 OAuth 应用程序连接 CodeConnections。请注意，连接 OAuth 应用程序时，必须使用 CodeBuild 控制台进行连接。有关更多说明，请参阅 [GitLab 进入 CodeBuild](access-tokens-gitlab-overview.md)。 + Connect CodeBuild 到您的 GitLab 账户。为此，您可以在控制台中添加 GitLab 为源提供商。有关说明，请参阅[GitLab 进入 CodeBuild](access-tokens-gitlab-overview.md)。 **注意** 只有当你的账户还没有连接时， GitLab 才需要这样做。 使用此功能， CodeBuild 需要其他权限。例如`create_runner`和`manage_runner`来自应用程序。 GitLab OAuth 如果特定 GitLab 账户已 CodeConnections 有权限，则它不会自动请求权限更新。为此，您可以访问 CodeConnections 控制台并创建与同一 GitLab 账户的虚拟连接，以触发重新授权以获得额外权限。这样，所有现有的连接都可以使用运行器特征。完成后，您可以删除虚拟连接。 ## 第 1 步：使用 webhook 创建 CodeBuild 项目 在此步骤中，您将创建一个带有 webhook 的 CodeBuild 项目，并在 GitLab 控制台中对其进行审核。 **使用 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)。 在**项目类型**中，选择**运行程序项目**。 + 在**运行程序**中： + 对于**跑步者提供商**，请选择**GitLab**。 + 对于**凭证**，选择以下选项之一： + 选择**默认来源凭证**。默认连接将默认 GitLab 连接应用于所有项目。 + 选择**自定义来源凭证**。自定义连接应用的自定义 GitLab 连接会覆盖您账户的默认设置。 **注意** 如果您尚未创建与提供商的连接，则必须创建一个新的 GitLab 连接。有关说明，请参阅[Connect t CodeBuild o GitLab](access-tokens-gitlab-overview.md#connections-gitlab)。 + 对于**运行程序位置**，请选择**存储库**。 + 对**于 Reposit** ory， GitLab 通过使用命名空间指定项目路径来选择项目名称。 + 在**环境**中： + 选择支持的**环境映像**和**计算**。请注意，您可以选择在 CI GitLab /CD 管道 YAML 中使用标签来覆盖映像和实例设置。有关更多信息，请参阅 [步骤 2：在存储库中创建 .gitlab-ci.yml 文件](#sample-gitlab-runners-gitlab-ci)。 + 在 **Buildspec (构建规范)** 中： + 请注意，除非将 `buildspec-override:true` 作为标签添加，否则系统会忽略 buildspec。取而代之的是， CodeBuild 将覆盖它以使用将设置自我管理的运行器的命令。 1. 继续使用默认值，然后选择**创建构建项目**。 1. 打开 GitLab 控制台，验证是否已创建一个 webhook 并已启用 webhook 来传送**工作流作业**事件。`https://gitlab.com/user-name/repository-name/-/hooks` ## 步骤 2：在存储库中创建 .gitlab-ci.yml 文件 在此步骤中，您将在中创建一个`.gitlab-ci.yml`文件[https://gitlab.com/](https://gitlab.com/)来配置您的构建环境并在中 CodeBuild使用 GitLab 自我管理的运行器。有关更多信息，请参阅[使用自行管理的运行器](https://docs.gitlab.com/runner/#use-self-managed-runners)。 ### 更新你的 GitLab CI/CD 管道 YAML 导航到 `https://gitlab.com/user-name/project-name/-/tree/branch-name` 并在您的存储库中创建 `.gitlab-ci.yml` 文件。您可以执行下列操作之一来配置构建环境： + 您可以指定 CodeBuild 项目名称，在这种情况下，构建版本将使用您现有的项目配置来计算计算、映像、映像版本和实例大小。需要项目名称才能将 GitLab 作业的 AWS相关设置链接到特定 CodeBuild项目。通过在 YAML 中包含项目名称 CodeBuild ，可以调用具有正确项目设置的作业。 ``` tags: - codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME ``` 需要使用 `$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME` 将构建映射到特定的管线作业运行，并在取消管线运行时停止构建。 **注意** 请确保您的名称与您在中创建的项目的名称**相匹配 CodeBuild。如果不匹配， CodeBuild 将无法处理 webhook，C GitLab I/CD 管道可能会挂起。 以下是 C GitLab I/CD 管道 YAML 的示例： ``` workflow: name: HelloWorld stages: # List of stages for jobs, and their order of execution - build build-job: # This job runs in the build stage, which runs first. stage: build script: - echo "Hello World!" tags: - codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME ``` + 您也可以在标签中覆盖映像和计算类型。有关精选映像的列表，请参阅[计算 CodeBuild托管运行器支持的 GitLab 映像](sample-gitlab-runners-gitlab-ci.images.md)。有关使用自定义映像，请参阅[托管的运行器支持的标签覆盖 CodeBuild GitLab](gitlab-runners-update-labels.md)。标签中的计算类型和映像将覆盖项目上的环境设置。要覆盖 Amazon EC2 计算构建的环境设置，请使用以下语法： ``` tags: - codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - image:- - instance-size: ``` 以下是 C GitLab I/CD 管道 YAML 的示例： ``` stages: - build build-job: stage: build script: - echo "Hello World!" tags: - codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - image:arm-3.0 - instance-size:small ``` + 您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅 [在预留容量实例集上运行构建](fleets.md)。要覆盖 Amazon EC2 计算构建的实例集设置，请使用以下语法： ``` tags: - codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - fleet: ``` 要同时覆盖构建所用的实例集和映像，请使用以下语法： ``` tags: - codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - fleet: - image:- ``` 以下是 C GitLab I/CD 管道 YAML 的示例： ``` stages: - build build-job: stage: build script: - echo "Hello World!" tags: - codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - fleet:myFleet - image:arm-3.0 ``` + 要在自定义映像上运行 GitLab CI/CD 管道作业，您可以在 CodeBuild 项目中配置自定义映像，避免提供图像覆盖标签。 CodeBuild 如果未提供图像覆盖标签，则将使用项目中配置的图像。 在您向提交更改后`.gitlab-ci.yml`，将触发 GitLab 管道，管道`build-job`将发送一个 webhook 通知，启动您的构建。 CodeBuild ### 在 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 阶段运行 buildspec 命令 默认情况下，在运行自 GitLab 管理版本时 CodeBuild 会忽略任何 buildspec 命令。要在构建期间运行 buildspec 命令，可以将 `buildspec-override:true` 作为后缀添加到 `tags`： ``` tags: - codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - buildspec-override:true ``` 通过使用此命令， CodeBuild 将在容器的主源文件夹`gitlab-runner`中创建一个名为的文件夹。当 GitLab 运行器在该`BUILD`阶段启动时，运行器将在`gitlab-runner`目录中运行。 在自管理 GitLab 版本中使用 buildspec 覆盖时有几个限制： + CodeBuild 在此`BUILD`阶段不会运行 buildspec 命令，因为自我管理的运行器将在该`BUILD`阶段运行。 + CodeBuild 在此`DOWNLOAD_SOURCE`阶段不会下载任何主要或次要来源。如果您配置了 buildspec 文件，则只会从项目的主源下载该文件。 + 如果构建命令在`PRE_BUILD`或`INSTALL`阶段失败， CodeBuild 则无法启动自管理的运行器，并且需要手动取 GitLab 消 CI/CD 管道作业。 + CodeBuild 在该阶段获取跑步者令牌，该`DOWNLOAD_SOURCE`阶段的到期时间为一小时。如果您的`PRE_BUILD`或`INSTALL`阶段超过一小时，则运行器令牌可能会在 GitLab 自我管理的运行器启动之前过期。 ## 步骤 3：检查您的结果 每当是 GitLab CI/CD pipeline run occurs, CodeBuild would receive the CI/CD pipeline job events through the webhook. For each job in the CI/CD pipeline, CodeBuild starts a build to run an ephemeral GitLab runner. The runner is responsible for executing a single CI/CD管道作业。作业完成后，运行器和关联的构建过程会立即终止。 要查看您的 CI/CD 管道作业日志，请导航到中的存储库 GitLab，选择 B **uild**、J **ob** s，然后选择要查看其日志的特定**作业**。 当作业等待中自我管理的运行者接管时，您可以在日志中 CodeBuild查看请求的标签。 ## 筛选 GitLab webhook 事件 ()CloudFormation CloudFormation 模板的以下 YAML 格式部分创建一个筛选条件组，该组在计算结果为 true 时会触发构建。以下筛选器组指定与正则表达式相匹配的 GitLab CI/CD pipeline job request with a CI/CD管道名称`\[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: GITLAB Location: CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION Triggers: Webhook: true ScopeConfiguration: Name: group-name Scope: GITLAB_GROUP FilterGroups: - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED - Type: WORKFLOW_NAME Pattern: \[CI-CodeBuild\] ``` # 托管的运行器支持的标签覆盖 CodeBuild GitLab 在你的 GitLab CI/CD 管道 YAML 中，你可以提供各种标签替换来修改你的自我管理的运行器构建。任何未被识别的版本都 CodeBuild 将被忽略，但不会使您的 webhook 请求失败。例如，以下 YAML 包括映像、实例大小、实例集和 buildspec 的覆盖： ``` workflow: name: HelloWorld stages: - build build-job: stage: build script: - echo "Hello World!" tags: - codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME - image:arm-3.0 - instance-size:small - fleet:myFleet - buildspec-override:true ``` `codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME`（必需） + 示例：`codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME` + 所有 GitLab CI/CD 管道均为必填项。 YAMLs **应等于为其配置自管理运行器 webhook 的项目的名称。 `image:-` + 示例：`image:arm-3.0` + 覆盖在启动自行管理运行器构建时使用的映像和环境类型。要了解支持的值，请参阅[计算 CodeBuild托管运行器支持的 GitLab 映像](sample-gitlab-runners-gitlab-ci.images.md)。 + 要覆盖与自定义映像结合使用的映像和环境类型，请使用 `image:custom--` + 示例：`image:custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0` **注意** 如果自定义映像位于私有注册表中，请参阅[为自托管运行程序配置私有注册表凭证](private-registry-sample-configure-runners.md)。 `instance-size:` + 示例：`instance-size:small` + 覆盖在启动自行管理运行器构建时使用的实例类型。要了解支持的值，请参阅[计算 CodeBuild托管运行器支持的 GitLab 映像](sample-gitlab-runners-gitlab-ci.images.md)。 `fleet:` + 示例：`fleet:myFleet` + 覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅 [在预留容量实例集上运行构建](fleets.md)。 `buildspec-override:` + 示例：`buildspec-override:true` + 如果设置为 `true`，则允许构建以在 `INSTALL`、`PRE_BUILD` 和 `POST_BUILD` 阶段运行 buildspec 命令。 # 计算 CodeBuild托管运行器支持的 GitLab 映像 在中配置的标签中[教程：配置 CodeBuild托管的运行器 GitLab](sample-gitlab-runners.md)，您可以使用前三列中的值来覆盖您的 Amazon EC2 环境设置。 CodeBuild 提供了以下 Amazon EC2 计算映像。有关 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/sample-gitlab-runners-gitlab-ci.images.html) 此外，您还可以使用以下值来覆盖 Lambda 环境设置。有关 CodeBuild Lambda 计算的更多信息，请参阅。[在 AWS Lambda 计算基础上运行构建](lambda.md) CodeBuild 支持以下 Lambda 计算映像： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/sample-gitlab-runners-gitlab-ci.images.html) 有关更多信息，请参阅[构建环境计算模式和类型](build-env-ref-compute-types.md)和[提供的 Docker 镜像 CodeBuild](build-env-ref-available.md)。 # 自我管理的 Buildkite 运行器进来了 AWS CodeBuild 你可以将项目配置为在 CodeBuild 容器中设置自托管的 Buildkite 运行器来处理你的 Buildkite 作业。这可以通过使用您的 CodeBuild项目设置 webhook，然后更新 Buildkite 管道 YAML 步骤以使用托管在计算机上的自托管运行器来完成。 CodeBuild 配置 CodeBuild 项目以运行 Buildkite 作业的高级步骤如下： + 导航到 CodeBuild 控制台并使用 Buildkite 运行器项目运行器类型配置创建项目 CodeBuild + 向 Buildkite 组织添加 `job.scheduled` webhook。 + 在 Buildkite 中更新 Buildkite 管道 YAML 步骤，以配置构建环境。 有关更详细的过程，请参阅[教程：配置 CodeBuild托管的 Buildkite 运行器](sample-runner-buildkite.md)。此功能允许您的 Buildkite 任务与之进行原生集成 AWS，从而通过 IAM、、和 Amazon VPC 等功能提供安全性和便利性。 AWS Secrets Manager AWS CloudTrail您可以访问最新的实例类型，包括基于 ARM 的实例。 # 关于 CodeBuild托管的 Buildkite 运行器 以下是有关 CodeBuild托管的 Buildkite 运行器的一些常见问题。 ## 我应该何时在标签中包括映像和实例覆盖？ 您可以在标签中包括映像和实例覆盖，以便为每个 Buildkite 作业指定不同的构建环境。无需创建多个 CodeBuild 项目或 webhook 即可完成此操作。例如，当您需要[为 Buildkite 作业使用矩阵](https://buildkite.com/docs/pipelines/configure/workflows/build-matrix)时，这很有用。 ``` agents: queue: "myQueue" steps: - command: "echo \"Hello World\"" agents: project: "codebuild-myProject" image: "{{matrix.os}}" instance-size: "{{matrix.size}}" matrix: setup: os: - "arm-3.0" - "al2-5.0" size: - "small" - "large" ``` ## 能否在 Buildkite 中自动 CodeBuild 创建 web 挂钩？ 目前，Buildkite 要求所有 webhook 都使用其控制台手动创建。您可以按照[教程：配置 CodeBuild托管的 Buildkite 运行器](sample-runner-buildkite.md)中的教程在 Buildkite 控制台中手动创建 Buildkite webhook。 ## 我可以用它 CloudFormation 来创建 Buildkite 网络挂钩吗？ CloudFormation Buildkite 运行器 webhook 目前不支持，因为 Buildkite 要求使用其控制台手动创建 webhook。 ## 哪些区域支持使用 CodeBuild托管的 Buildkite 运行器？ CodeBuild所有区域都支持托管的 Buildkite 运行器。 CodeBuild 有关可用 AWS 区域的更多信息，请参阅[按地区划分的AWS 服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。 CodeBuild # 教程：配置 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`，这将防止源凭证加载到构建环境中。 # 对于 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 阶段运行 buildspec 命令 默认情况下，在运行自托管 Buildkite 运行器版本时会 CodeBuild 忽略所有 buildspec 命令。要在构建期间中运行 buildspec 命令， ``` buildspec-override: "true" ``` 可作为后缀添加到标签： ``` agents: project: "codebuild-" buildspec-override: "true" ``` 通过使用此命令， CodeBuild 将在容器的主源文件夹`buildkite-runner`中创建一个名为的文件夹。当 Buildkite 运行程序在 `BUILD` 阶段启动时，运行程序将在 `buildkite-runner` 目录中运行。 在自托管 Buildkite 构建中使用 buildspec 覆盖具有若干限制： + Buildkite 代理要求构建环境中存在源凭证才能提取作业的源存储库。如果您使用 CodeBuild 源证书进行身份验证，则需要在 buildspec `git-credential-helper` 中启用。例如，可以使用以下 buildspec 为 Buildkite 构建启用 `git-credential-helper`： ``` version: 0.2 env: git-credential-helper: yes phases: pre_build: commands: - echo "Hello World" ``` + CodeBuild 在此`BUILD`阶段不会运行 buildspec 命令，因为自托管运行器将在该`BUILD`阶段运行。 + CodeBuild 不支持 Buildkite 运行器版本的 buildspec 文件。Buildlkite 自托管运行程序仅支持内联 buildspec + 如果构建命令在`PRE_BUILD`或`INSTALL`阶段失败， CodeBuild 则无法启动自托管运行器，并且需要手动取消 Buildkite 作业。 # 以编程方式设置 Buildkite 运行程序 为了以编程方式配置 Buildkite 运行程序项目，您将需要配置以下资源： **以编程方式创建 Buildkite 运行程序** 1. 创建 Buildkite 代理令牌并将该令牌以纯文本形式保存在 AWS Secrets Manager中。 1. 使用您的首选配置设置 CodeBuild 项目。您需要配置以下额外的属性： 1. 一个环境值，其名称为 `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`、类型为 `SECRETS_MANAGER`，而值等于与 Buildkite 集群关联的 Buildkite 代理令牌。 1. 等于 `NO_SOURCE` 的源类型 1. 以项目的服务角色访问在步骤 1 中创建的密钥的权限 例如，您可以通过 CLI 使用以下命令创建有效的 Buildkite 运行程序项目： ``` aws codebuild create-project \ --name buildkite-runner-project \ --source "{\"type\": \"NO_SOURCE\",\"buildspec\":\"\"}" \ --environment "{\"image\":\"aws/codebuild/amazonlinux-x86_64-standard:5.0\",\"type\":\"LINUX_CONTAINER\",\"computeType\":\"BUILD_GENERAL1_MEDIUM\",\"environmentVariables\":[{\"name\":\"CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN\",\"type\":\"SECRETS_MANAGER\",\"value\":\"\"}]}" \ --artifacts "{\"type\": \"NO_ARTIFACTS\"}" \ --service-role ``` 1. 在步骤 2 中创建的项目上创建 Buildkite 运行程序 webhook。创建 webhook 时，您需要使用以下配置选项： 1. **build-type** 应等于 `RUNNER_BUILDKITE_BUILD` 1. 类型为 `EVENT` 且模式等于 `WORKFLOW_JOB_QUEUED` 的筛选条件 例如，您可以通过 CLI 使用以下命令创建有效的 Buildkite 运行程序 webhook： ``` aws codebuild create-webhook \ --project-name buildkite-runner-project \ --filter-groups "[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"}]]" \ --build-type RUNNER_BUILDKITE_BUILD ``` 1. 保存由 `create-webhook` 调用返回的**有效载荷 URL** 和**密钥**值，然后使用凭证在 Buildkite 控制台中创建 webhook。您可以参考中的步骤 3：在 Buildkite 中创建 CodeBuild webhook，以[教程：配置 CodeBuild托管的 Buildkite 运行器](sample-runner-buildkite.md)获取有关如何设置此资源的指南。 # 针对失败的构建或挂起的作业对 webhook 进行故障排除 **问题: ** 您在[教程：配置 CodeBuild托管的 Buildkite 运行器](sample-runner-buildkite.md)中设置的 webhook 无法正常工作，或工作流程作业在 Buildkite 中挂起。 **可能的原因：** + 您的 **job.scheduled** 事件可能无法触发构建。检查**响应**日志以查看响应或错误消息。 + 在启动 Buildkite 自托管运行器代理来处理你的 CodeBuild 工作之前，你的构建失败了。 **推荐的解决方案：** 要调试失败的 Buildkite webhook 事件： 1. **在你的 Buildkite 组织设置中，导航到**通知服务**，选择你的 CodeBuild webhook，然后找到请求日志。** 1. 查找与卡住的 Buildkite 作业关联的 `job.scheduled` webhook 事件。可以使用 webhook 有效载荷中的作业 ID 字段将 webhook 事件与 Buildkite 作业相关联。 1. 选择**响应**选项卡并检查响应正文。确认**响应**状态代码为 `200` 且**响应**正文不包含任何意外的消息。 ![\[Webhook 的响应。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/buildkite-request.png) # 排查 webhook 权限问题 **问题: ** Buildkite 作业由于权限问题而无法签出作业的源存储库。 **可能的原因：** + CodeBuild 没有足够的权限来查看任务的源存储库。 + 管道的存储库设置设置为使用 SSH 签出 CodeBuild托管凭据。 **推荐的解决方案：** + 验证是否配置 CodeBuild 了足够的权限来查看作业的源存储库。此外，请验证 CodeBuild 项目的服务角色是否有足够的权限访问配置的源权限选项。 + 如果您使用的是 CodeBuild 托管源存储库凭据，请确认您的 Buildkite 管道已配置为使用 HTTPS 签出。 # CodeBuild托管的 Buildkite 运行器支持的标签覆盖 在 Buildkite 管道步骤代理标签标注中，您可以提供各种标注覆盖来修改自托管运行程序构建。任何未被识别的版本都 CodeBuild将被忽略，但不会使您的 webhook 请求失败。例如，以下工作流程 YAML 包括映像、实例大小、实例集和 buildspec 的覆盖： ``` agents: queue: "myQueue" steps: - command: "echo \"Hello World\"" agents: project: "codebuild-myProject" image: "{{matrix.os}}" instance-size: "{{matrix.size}}" buildspec-override: "true" matrix: setup: os: - "arm-3.0" - "al2-5.0" size: - "small" - "large" ``` `project:codebuild-`（必需） + 示例：`project: "codebuild-myProject"` + 所有 Buildkite 工作流步骤配置都是必需的。 **应等于为其配置自托管运行器 webhook 的项目的名称。 `queue: ""` + 示例：`queue: ""` + 用于将 Buildkite 作业路由到特定队列。有关更多信息，请参阅 [Buildkite Agent Queue Tag](https://buildkite.com/docs/agent/v3/cli-start#the-queue-tag)。 `image: "-"` + 示例：`image: "arm-3.0"` + 覆盖在通过精选映像启动自托管运行程序构建时使用的映像和环境类型。要了解支持的值，请参阅[计算 CodeBuild托管的 Buildkite 运行器支持的图像](buildkite-runner-update-yaml.images.md)。 1. 要覆盖与自定义映像结合使用的映像和环境类型，请使用 `image: "custom--"` 1. 示例： ``` image: "custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0" ``` **注意** 如果自定义映像位于私有注册表中，则必须在 CodeBuild 项目中配置相应的注册表凭据。 `instance-size: ""` + 示例：`instance-size: "medium"` + 覆盖在启动自托管运行器构建时使用的实例类型。要了解支持的值，请参阅[计算 CodeBuild托管的 Buildkite 运行器支持的图像](buildkite-runner-update-yaml.images.md)。 `fleet: ""` + 示例：`fleet: "myFleet"` + 覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅[在预留容量实例集上运行构建](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html)。 `buildspec-override: ""` + 示例：`buildspec-override: "true"` + 如果设置为 `true`，则允许构建以在 `INSTALL`、`PRE_BUILD` 和 `POST_BUILD` 阶段运行 buildspec 命令。 # 计算 CodeBuild托管的 Buildkite 运行器支持的图像 在中配置的标签中[自我管理的 Buildkite 运行器进来了 AWS CodeBuild](buildkite-runner.md)，您可以使用前三列中的值来覆盖您的 Amazon EC2 环境设置。 CodeBuild 提供了以下 Amazon EC2 计算映像。有关 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/buildkite-runner-update-yaml.images.html) 此外，您还可以使用以下值来覆盖 Lambda 环境设置。有关 CodeBuild Lambda 计算的更多信息，请参阅。[在 AWS Lambda 计算基础上运行构建](lambda.md) CodeBuild 支持以下 Lambda 计算映像： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/buildkite-runner-update-yaml.images.html) 有关更多信息，请参阅[构建环境计算模式和类型](build-env-ref-compute-types.md)和[提供的 Docker 镜像 CodeBuild](build-env-ref-available.md)。