步骤 1：创建带有 webhook 的 CodeBuild 项目步骤 2：在存储库中创建 .gitlab-ci.yml 文件步骤 3：检查您的结果筛选 GitLab Webhook 事件（Amazon CloudFormation）

教程：配置 CodeBuild 托管的 GitLab 运行器

本教程演示了如何配置 CodeBuild 项目来运行 GitLab CI/CD 管线作业。有关将 GitLab 或 GitLab 自行管理与 CodeBuild 配合使用的更多信息，请参阅Amazon CodeBuild 中的自行管理 GitLab 运行器。

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

通过 CodeConnections 建立与 OAuth 应用程序的连接。请注意，在连接 OAuth 应用程序时，必须使用 CodeBuild 控制台来进行。有关更多说明，请参阅 CodeBuild 中的 GitLab 访问权限。
将 CodeBuild 连接到您的 GitLab 账户。为此，您可以在控制台中将 GitLab 添加为源提供商。有关说明，请参阅CodeBuild 中的 GitLab 访问权限。

注意
仅当您的账户尚未连接到 GitLab 时，才需要执行此操作。
使用此特征时，CodeBuild 需要额外权限，例如 GitLab OAuth 应用程序的 create_runner 和 manage_runner 权限。如果特定 GitLab 账户已有 CodeConnections，则不会自动请求权限更新。为此，您可以前往 CodeConnections 控制台并创建一个指向同一 GitLab 账户的虚拟连接，以便触发重新授权来获得额外权限。这样，所有现有的连接都可以使用运行器特征。完成后，您可以删除虚拟连接。

步骤 1：创建带有 webhook 的 CodeBuild 项目

在此步骤中，您将创建一个带有 webhook 的 CodeBuild 项目，并在 GitLab 控制台中进行检查。

创建带有 webhook 的 CodeBuild 项目

从 https://console.aws.amazon.com/codesuite/codebuild/home 打开 Amazon CodeBuild 控制台。
创建构建项目。有关信息，请参阅创建构建项目（控制台）和运行构建（控制台）。

在项目类型中，选择运行程序项目。
- 在运行程序中：
  - 对于运行程序提供商，选择 GitLab。
  - 对于凭证，选择以下选项之一：
    
    选择默认来源凭证。默认连接将在所有项目中应用默认 GitLab 连接。
    
    选择自定义来源凭证。自定义连接会应用自定义 GitLab 连接，该连接会覆盖您账户的默认设置。
    
    注意
    如果您尚未创建与提供程序的连接，则必须创建新的 GitLab 连接。有关说明，请参阅将 CodeBuild 连接到 GitLab。
  - 对于运行程序位置，请选择存储库。
  - 对于存储库，通过指定带命名空间的项目路径，选择 GitLab 中您的项目的名称。
- 在环境中：
  - 选择支持的环境映像和计算。请注意，您可以选择在 GitLab CI/CD 管线 YAML 中使用标签来覆盖映像和实例设置。有关更多信息，请参阅步骤 2：在存储库中创建 .gitlab-ci.yml 文件。
- 在 Buildspec (构建规范) 中：
  - 请注意，除非将 buildspec-override:true 作为标签添加，否则系统会忽略 buildspec。相反，CodeBuild 将覆盖它，以便使用特定命令来设置自行管理运行器。
继续使用默认值，然后选择创建构建项目。
在 https://gitlab.com/user-name/repository-name/-/hooks 打开 GitLab 控制台，确认已创建一个 webhook，并已启用来传递工作流作业事件。

步骤 2：在存储库中创建 .gitlab-ci.yml 文件

在此步骤中，您将在 GitLab 中创建一个 .gitlab-ci.yml 文件来配置构建环境，并在 CodeBuild 中使用 GitLab 自行管理的运行器。有关更多信息，请参阅使用自行管理的运行器。

更新 GitLab CI/CD 管线 YAML

导航到 https://gitlab.com/user-name/project-name/-/tree/branch-name 并在您的存储库中创建 .gitlab-ci.yml 文件。您可以执行下列操作之一来配置构建环境：

您可以指定 CodeBuild 项目名称，在这种情况下，构建将使用计算、映像、映像版本和实例大小的现有项目配置。需要有项目名称才能将 GitLab 作业的 Amazon 相关设置链接到特定 CodeBuild 项目。通过在 YAML 中包括项目名称，CodeBuild 可以调用具有正确项目设置的作业。
```
tags:
    - codebuild-<codebuild-project-name>-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
```
需要使用 $CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME 将构建映射到特定的管线作业运行，并在取消管线运行时停止构建。

注意
确保您的 <project-name> 与您在 CodeBuild 中创建的项目名称匹配。如果不匹配，CodeBuild 将无法处理 webhook，GitLab CI/CD 管线可能会挂起。

以下是 GitLab CI/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 运行器支持的映像。有关使用自定义映像，请参阅CodeBuild 托管的 GitLab 运行器支持的标签覆盖。标签中的计算类型和映像将覆盖项目上的环境设置。要覆盖 Amazon EC2 计算构建的环境设置，请使用以下语法：
```
tags:
    - codebuild-<codebuild-project-name>-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
    - image:<environment-type>-<image-identifier>
    - instance-size:<instance-size>
```
以下是 GitLab CI/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
```

您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅在预留容量实例集上运行构建。要覆盖 Amazon EC2 计算构建的实例集设置，请使用以下语法：


tags:
    - codebuild-<codebuild-project-name>-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
    - fleet:<fleet-name>

要同时覆盖构建所用的实例集和映像，请使用以下语法：


tags:
    - codebuild-<codebuild-project-name>-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
    - fleet:<fleet-name>                    
    - image:<environment-type>-<image-identifier>

以下是 GitLab CI/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_BUILD 和 POST_BUILD 阶段运行 buildspec 命令

默认情况下，在运行自行管理的 GitLab 构建时，CodeBuild 会忽略任何 buildspec 命令。要在构建期间运行 buildspec 命令，可以将 buildspec-override:true 作为后缀添加到 tags：


tags:
    - codebuild-<codebuild-project-name>-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
    - buildspec-override:true

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

在自行管理的 GitLab 构建中使用 buildspec 覆盖有几个限制：

因为自行管理的运行器在 BUILD 阶段运行，CodeBuild 不会在 BUILD 阶段运行 buildspec 命令。
在 DOWNLOAD_SOURCE 阶段，CodeBuild 不会下载任何主源或辅助源。如果您配置了 buildspec 文件，则只会从项目的主源下载该文件。
如果构建命令在 PRE_BUILD 或 INSTALL 阶段失败，则 CodeBuild 将不会启动自行管理的运行器，并且需要手动取消 GitLab CI/CD 管线作业。
CodeBuild 将在 DOWNLOAD_SOURCE 阶段获取运行器令牌，该阶段的过期时间为一小时。如果 PRE_BUILD 或 INSTALL 阶段超过一小时，则运行器令牌可能会在 GitLab 自行管理的运行器启动之前过期。

步骤 3：检查您的结果

每当 GitLab CI/CD 管线运行时，CodeBuild 都会通过 webhook 接收 CI/CD 管线作业事件。对于 CI/CD 管线中的每项作业，CodeBuild 都会启动一个构建来运行临时的 GitLab 运行器。该运行器负责执行单个 CI/CD 管线作业。作业完成后，运行器和关联的构建过程会立即终止。

要查看您的 CI/CD 管线作业日志，请在 GitLab 中导航到您的存储库，依次选择构建、作业，然后选择要查看其日志的特定作业。

在 CodeBuild 中等待自行管理的运行器提取作业时，您可以在日志中查看请求的标签。

筛选 GitLab Webhook 事件（Amazon CloudFormation）

Amazon CloudFormation 模板的以下 YAML 格式部分创建一个筛选条件组，该组在计算结果为 true 时会触发构建。以下筛选条件组指定 GitLab CI/CD 管线作业请求，其 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\]

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

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

关于 CodeBuild 托管的 GitLab 运行器

支持的标签覆盖