本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學課程：設定 CodeBuild 託管的 GitLab 執行器
本教學課程說明如何設定 CodeBuild 專案以執行 GitLab CI/CD 管道任務。如需使用 GitLab 或 GitLab Self Managed with CodeBuild 的詳細資訊，請參閱 [中的自我管理 GitLab 執行器 AWS CodeBuild](gitlab-runner.md)。
若要完成此教學課程，您必須先：
+ 使用 CodeConnections 與 OAuth 應用程式連線。請注意，與 OAuth 應用程式連線時，您必須使用 CodeBuild 主控台來執行此操作。如需更多說明，請參閱 [CodeBuild 中的 GitLab 存取](access-tokens-gitlab-overview.md)。
+ 將 CodeBuild 連接至您的 GitLab 帳戶。若要這樣做，您可以在 主控台中新增 GitLab 做為來源提供者。如需說明，請參閱[CodeBuild 中的 GitLab 存取](access-tokens-gitlab-overview.md)。
**注意**
只有在您尚未連線到您帳戶的 GitLab 時，才需要這麼做。
透過此功能，CodeBuild 需要額外的許可。例如`manage_runner`來自 GitLab OAuth 應用程式的 `create_runner`和 。如果特定 GitLab 帳戶有現有的 CodeConnections，則不會自動請求許可更新。若要這麼做，您可以前往 CodeConnections 主控台，並建立與相同 GitLab 帳戶的虛擬連線，以觸發重新授權以取得額外的許可。如此一來，所有現有的連線都可以使用執行器功能。完成後，您可以刪除虛擬連線。
## 步驟 1：使用 Webhook 建立 CodeBuild 專案
在此步驟中，您將使用 Webhook 建立 CodeBuild 專案，並在 GitLab 主控台中檢閱。
**使用 Webhook 建立 CodeBuild 專案**
1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。
1. 建立建置專案。如需詳細資訊，請參閱 [建立組建專案 (主控台)](create-project.md#create-project-console) 及 [執行建置 (主控台)](run-build-console.md)。
在**專案類型**中，選擇**執行器專案**。
+ 在**執行器**中：
+ 針對 **Runner 提供者**，選擇 **GitLab**。
+ 針對**登入**資料，選擇下列其中一項：
+ 選擇**預設來源憑證**。預設連線會將預設 GitLab 連線套用至所有專案。
+ 選擇**自訂來源憑證**。自訂連線會套用自訂 GitLab 連線，覆寫您帳戶的預設設定。
**注意**
如果您尚未建立與供應商的連線，則必須建立新的 GitLab 連線。如需說明，請參閱[將 CodeBuild 連接至 GitLab](access-tokens-gitlab-overview.md#connections-gitlab)。
+ 針對**執行器位置**，選擇**儲存庫**。
+ 對於**儲存庫**，使用 命名空間指定專案路徑，在 GitLab 中選擇專案的名稱。
+ 在 **Environment (環境)** 中：
+ 選擇支援**的環境映像**和**運算**。請注意，您可以選擇使用 GitLab CI/CD 管道 YAML 中的標籤覆寫映像和執行個體設定。如需詳細資訊，請參閱[步驟 2：在您的儲存庫中建立 .gitlab-ci.yml 檔案](#sample-gitlab-runners-gitlab-ci)。
+ 在 **Buildspec (建置規格)** 中：
+ 請注意，除非`buildspec-override:true`新增為標籤，否則您的 buildspec 將被忽略。反之，CodeBuild 會覆寫它，以使用設定自我管理執行器的命令。
1. 繼續執行預設值，然後選擇**建立建置專案**。
1. 在 開啟 GitLab 主控台`https://gitlab.com/user-name/repository-name/-/hooks`，確認 webhook 已建立並啟用，以交付**工作流程任務**事件。
## 步驟 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，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 Runner 支援的運算映像](sample-gitlab-runners-gitlab-ci.images.md)請參閱 。如需使用自訂映像，請參閱 [CodeBuild 託管的 GitLab Runner 支援標籤覆寫](gitlab-runners-update-labels.md)。標籤中的運算類型和映像會覆寫專案上的環境設定。若要覆寫 Amazon EC2 運算建置的環境設定，請使用下列語法：
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- image:-
- 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
```
+ 您可以在 標籤中覆寫用於組建的機群。這將覆寫在專案上設定的機群設定，以使用指定的機群。如需詳細資訊，請參閱[在預留容量機群上執行組建](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:-
```
以下是 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 中開始建置。
### 執行 buildspec 命令 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 階段
根據預設，CodeBuild 會在執行自我管理的 GitLab 組建時忽略任何 buildspec 命令。若要在建置期間執行 buildspec 命令， `buildspec-override:true` 可以新增為 的尾碼`tags`：
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- buildspec-override:true
```
透過使用此命令，CodeBuild `gitlab-runner` 將在容器的主要來源資料夾中建立名為 的資料夾。當 GitLab Runner 在 `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 管道執行時，CodeBuild 會透過 Webhook 接收 CI/CD 管道任務事件。針對 CI/CD 管道中的每個任務，CodeBuild 會啟動組建以執行暫時性 GitLab 執行器。執行器負責執行單一 CI/CD 管道任務。任務完成後，執行器和相關聯的建置程序將立即終止。
若要檢視 CI/CD 管道任務日誌，請導覽至 GitLab 中的儲存庫，選擇**建置**、**任務**，然後選擇您要檢閱日誌的特定**任務**。
您可以在任務等待 CodeBuild 中的自我管理執行器提取時，檢閱日誌中請求的標籤。
## 篩選 GitLab Webhook 事件 (CloudFormation)
範本的 CloudFormation 下列 YAML 格式部分會建立篩選條件群組，在評估為 true 時觸發組建。下列篩選條件群組會使用符合規則表達式 的 CI/CD 管道名稱，指定 GitLab 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\]
```