第 1 步：使用 webhook 创建 CodeBuild 项目第 2 步：更新您的 GitHub 操作工作流程 YAML 步骤 3：检查您的结果 GitHub 操作运行器配置选项筛选 GitHub 操作 webhook 事件 (CloudFormation)筛选 GitHub 操作 webhook 事件 (AWS CDK)筛选 GitHub 操作 webhook 事件 (Terraform)筛选 GitHub 操作 webhook 事件 (AWS CLI)

教程：配置 CodeBuild-hosted GitHub 操作运行器

本教程向您展示如何配置 CodeBuild 项目以运行 GitHub 操作作业。有关使用 GitHub 操作的更多信息， CodeBuild 请参阅教程：配置 CodeBuild-hosted GitHub 操作运行器。

要完成本教程，您首先必须：

使用个人访问令牌、密钥管理器密钥、OAuth 应用程序或 GitHub 应用程序进行连接。如果您想连接 OAuth 应用程序，则必须使用 CodeBuild 控制台进行连接。如果你想创建个人访问令牌，你可以使用 CodeBuild 控制台或使用 ImportSourceCredentials API 。有关更多说明，请参阅 GitHub 然后进入 GitHub 企业服务器访问权限 CodeBuild。
CodeBuild 连接到您的 GitHub 账户。为此，您可以执行以下操作之一：
- 您可以在控制台中添加 GitHub 为来源提供商。您可以使用个人访问令牌、密钥管理器密钥、OAuth 应用程序或 GitHub 应用程序进行连接。有关说明，请参阅GitHub 然后进入 GitHub 企业服务器访问权限 CodeBuild。
- 您可以通过 ImportSourceCredentials API 导入您的 GitHub 证书。只有使用个人访问令牌才能执行此操作。如果您使用 OAuth 应用程序来连接，则必须改用控制台进行连接。有关说明，请参阅GitHub 使用访问令牌连接 (CLI)。
注意
只有在您尚未连接到您的账户时才需要执行此操作。 GitHub

第 1 步：使用 webhook 创建 CodeBuild 项目

在此步骤中，您将使用 webhook 创建一个 CodeBuild 项目并在 GitHub 控制台中对其进行审查。您也可以选择 GitHub 企业作为来源提供商。要了解有关在 GitHub 企业内创建 webhook 的更多信息，请参阅GitHub 手动网络挂钩。

使用 webhook 创建 CodeBuild 项目

在处打开 AWS CodeBuild 控制台https://console.aws.amazon.com/codesuite/codebuild/home。
创建构建项目。有关信息，请参阅创建构建项目（控制台）和运行构建（控制台）。
在项目类型中，选择运行程序项目。

在运行程序中：
1. 对于跑步者提供商，选择GitHub。
2. 对于运行程序位置，请选择存储库。
3. 在 “存储库” 下的 “存储库 URL” 中，选择https://github.com/user-name/repository-name。
注意
默认情况下，您的项目将仅接收单个存储库的 WORKFLOW_JOB_QUEUED 事件。如果您想接收组织或企业内所有存储库的事件，请参阅GitHub 全球和组织网络挂钩。
- 在环境中：
  - 选择支持的环境映像和计算。请注意，您可以选择在 Act GitHub ions 工作流程 YAML 中使用标签来覆盖图像和实例设置。有关更多信息，请参阅第 2 步：更新您的 GitHub 操作工作流程 YAML。
- 在 Buildspec (构建规范) 中：
  - 请注意，除非将 buildspec-override:true 作为标签添加，否则系统会忽略 buildspec。相反， CodeBuild 将覆盖它以使用用于设置自托管运行器的命令。
继续使用默认值，然后选择创建构建项目。
在https://github.com/user-name/repository-name/settings/hooks处打开 GitHub 控制台，验证是否已创建 Webhook 并启用了交付 Webhook 任务事件的功能。

第 2 步：更新您的 GitHub 操作工作流程 YAML

在此步骤中，您将在中更新 GitHub 操作工作流程 YAML 文件GitHub以配置您的构建环境并在中使用 Act GitHub ions 自托管运行器。 CodeBuild有关更多信息，请参阅在自托管运行器中使用标签和CodeBuild-hosted GitHub 操作运行器支持标签覆盖。

更新您的 GitHub 操作工作流程 YAML

导航到 GitHub 操作工作流程 YAML 中的runs-on设置GitHub并更新该设置，以配置您的构建环境。为此，您可以执行以下操作之一：

您可以指定项目名称和运行 ID，在这种情况下，构建将使用计算、映像、映像版本和实例大小的现有项目配置。需要项目名称才能将 Act GitHub ions 作业的 AWS相关设置链接到特定 CodeBuild项目。通过在 YAML 中包含项目名称 CodeBuild ，可以调用具有正确项目设置的任务。通过提供运行 ID，将您的生成 CodeBuild 映射到特定的工作流程运行，并在工作流程运行取消时停止构建。有关更多信息，请参阅 github 上下文。
```
runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
```
注意
确保您的名称与您在上一步中创建的项目名称<project-name>相匹配。如果不匹配， 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-hosted GitHub 操作运行器支持的图像。有关使用自定义映像，请参阅CodeBuild-hosted GitHub 操作运行器支持标签覆盖。标签中的计算类型和映像将覆盖项目的环境设置。要覆盖 CodeBuild EC2 或 Lambda 计算版本的环境设置，请使用以下语法：
```
runs-on:
  - codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
    image:<environment-type>-<image-identifier>
    instance-size:<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!"
```

您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅在预留容量实例集上运行构建。要覆盖 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 操作工作流程 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!"

为了在自定义图像上运行 Act GitHub ions 作业，您可以在 CodeBuild 项目中配置自定义镜像，避免提供图像覆盖标签。 CodeBuild 如果未提供图像覆盖标签，则将使用项目中配置的图像。
或者，您可以在 CodeBuild 支持的标签之外提供标签。在覆盖构建的属性时会忽略这些标签，但不会导致 webhook 请求失败。例如，添加 testLabel 作为标签不会阻止构建运行。

注意

如果 GitHub-hosted 运行器提供的依赖项在 CodeBuild环境中不可用，则可以在工作流程运行中使用 Act GitHub ions 安装该依赖项。例如，您可以使用 setup-python 操作为构建环境安装 Python。

在 INSTALL、PRE_BUILD 和 POST_BUILD 阶段运行 buildspec 命令

默认情况下，在运行自托管 GitHub 操作编译版本时 CodeBuild 忽略所有 buildspec 命令。要在构建期间运行 buildspec 命令，可以将 buildspec-override:true 作为后缀添加到标签中：


runs-on:
  - codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
    buildspec-override:true

通过使用此命令， CodeBuild 将在容器的主源文件夹actions-runner中创建一个名为的文件夹。当 GitHub 操作运行器在该BUILD阶段启动时，运行器将在actions-runner目录中运行。

在自托管的 Act GitHub ions 编译版本中使用编译规范替代时，存在一些限制：

CodeBuild 在此阶段不会运行 buildspec 命令，因为自托管运行器在该BUILDBUILD阶段运行。
CodeBuild 在此DOWNLOAD_SOURCE阶段不会下载任何主要或次要来源。如果您配置了 buildspec 文件，则只会从项目的主源下载该文件。
如果构建命令在PRE_BUILD或INSTALL阶段失败， CodeBuild 将无法启动自托管运行器，并且需要手动取消 Act GitHub ions 工作流程作业。
CodeBuild 在该阶段获取跑步者令牌，该DOWNLOAD_SOURCE阶段的到期时间为一小时。如果您的PRE_BUILD或INSTALL阶段超过一个小时，则运行器令牌可能会在 GitHub 自托管运行器启动之前过期。

步骤 3：检查您的结果

每当 GitHub 操作工作流程运行时， CodeBuild 都会通过 webhook 接收工作流程作业事件。对于工作流程中的每项作业， CodeBuild 启动构建以运行临时 GitHub 操作运行器。该运行器负责执行单个工作流作业。作业完成后，运行器和关联的构建过程会立即终止。

要查看工作流程作业日志，请导航到中的存储库 GitHub，选择操作，选择所需的工作流程，然后选择要查看日志的特定作业。

当任务等待自托管运行器接管时，您可以在日志中 CodeBuild查看请求的标签。

作业完成后，您将能够查看该作业的日志。

GitHub 操作运行器配置选项

您可以在项目配置中指定以下环境变量，以修改自托管运行程序的设置配置。

CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME

CodeBuild 将使用指定为该环境变量值的组织名称注册自托管运行器。有关在组织级别注册运行程序和必要权限的更多信息，请参阅 Create configuration for a just-in-time runner for an organization。

CODEBUILD_CONFIG_GITHUB_ACTIONS_ENTERPRISE_REGISTRATION_NAME

CodeBuild 将使用指定为该环境变量值的企业名称注册自托管运行器。有关在企业级别注册运行程序和必要权限的更多信息，请参阅 Create configuration for a just-in-time runner for an Enterprise。

注意

默认情况下，企业运行程序不可用于组织存储库。要让自托管运行程序承担工作流程作业，您可能需要配置运行程序组访问权限设置。有关更多信息，请参阅 Making enterprise runners available to repositories。

CODEBUILD_CONFIG_GITHUB_ACTIONS_RUNNER_GROUP_ID

CodeBuild 会将自托管运行器注册到存储为该环境变量值的整数运行器组 ID。默认情况下，该值为 1。有关自托管运行程序组的更多信息，请参阅 Managing access to self-hosted runners using groups。

CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME

要使用 Act GitHub ions 工作流程 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

要使用 Act GitHub ions 工作流程 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

要使用 Act GitHub ions 工作流程 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-formatted 部分创建了一个筛选器组，该筛选组在计算结果为 true 时触发构建。以下筛选器组使用与正则表达式匹配的工作流名称来指定 GitHub 操作工作流任务请求\[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
        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 命令使用 Act GitHub ions 工作流程任务请求筛选器组创建自托管的 Act GitHub ions 运行器项目，当编译结果为 true 时触发构建。


aws codebuild create-project \
--name <project name> \
--source "{\"type\":\"GITHUB\",\"location\":\"<repository 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 "<service role ARN>"


aws codebuild create-webhook \
--project-name <project name> \
--filter-groups "[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"}]]"

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

关于 Act CodeBuild-hosted GitHub ions 运行器

排查 webhook 的问题