本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 教程：配置 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\] ```