本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 搭配 使用執行器 AWS CodeBuild
AWS CodeBuild 支援與 GitHub Actions 執行器、自我管理的 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 容器中設定自我託管的 GitHub Actions 執行器，以處理您的 GitHub Actions 工作流程任務。這可以透過使用 CodeBuild 專案設定 Webhook，並更新您的 GitHub Actions 工作流程 YAML 來使用 CodeBuild 機器上託管的自我託管執行器來完成。
設定 CodeBuild 專案以執行 GitHub Actions 任務的高階步驟如下：
1. 如果您尚未這麼做，請建立個人存取字符或連線至 OAuth 應用程式，將您的專案連線至 GitHub。
1. 導覽至 CodeBuild 主控台，並使用 Webhook 建立 CodeBuild 專案，並設定您的 Webhook 篩選條件。
1. 在 GitHub 中更新您的 GitHub 動作工作流程 YAML，以設定您的建置環境。
如需更詳細的程序，請參閱 [教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](action-runner.md)。
此功能可讓您的 GitHub Actions 工作流程任務取得與 的原生整合 AWS，透過 IAM AWS Secrets Manager AWS CloudTrail、整合和 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 Actions Runner 支援運算映像](sample-github-action-runners-update-yaml.images.md)
# 關於 CodeBuild 託管的 GitHub 動作執行器
以下是有關 CodeBuild 託管的 GitHub 動作執行器的一些常見問題。
## 我應該在標籤中何時包含映像和執行個體覆寫？
您可以在 標籤中包含映像和執行個體覆寫，以便為每個 GitHub Actions 工作流程任務指定不同的建置環境。這可以完成，無需建立多個 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 Actions 執行器。如需 CodeBuild 可用 AWS 區域 位置的詳細資訊，請參閱[AWS 依區域的服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。
## 哪些平台支援使用 CodeBuild 託管的 GitHub Actions 執行器？
Amazon EC2 和[AWS Lambda](lambda.md)運算都支援 CodeBuild 託管的 GitHub Actions 執行器。您可以使用下列平台：Amazon Linux 2、Amazon Linux 2023、Ubuntu 和 Windows Server Core 2019。如需詳細資訊，請參閱[EC2 運算映像](ec2-compute-images.md)及[Lambda 運算映像](lambda-compute-images.md)。
# 教學課程：設定 CodeBuild 託管的 GitHub 動作執行器
本教學課程說明如何設定 CodeBuild 專案以執行 GitHub Actions 任務。如需搭配 CodeBuild 使用 GitHub 動作的詳細資訊，請參閱 [教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](#action-runner)。
若要完成此教學課程，您必須先：
+ 使用個人存取字符、Secrets Manager 秘密、OAuth 應用程式或 GitHub 應用程式連線。如果您想要與 OAuth 應用程式連線，您必須使用 CodeBuild 主控台來執行此操作。如果您想要建立個人存取字符，您可以使用 CodeBuild 主控台或使用 [ImportSourceCredentials API](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ImportSourceCredentials.html)。如需更多說明，請參閱 [CodeBuild 中的 GitHub 和 GitHub Enterprise Server 存取](access-tokens-github-overview.md)。
+ 將 CodeBuild 連接至您的 GitHub 帳戶。若要這樣做，您可以執行下列其中一項操作：
+ 您可以在 主控台中新增 GitHub 做為來源提供者。您可以使用個人存取字符、Secrets Manager 秘密、OAuth 應用程式或 GitHub 應用程式來連線。如需說明，請參閱[CodeBuild 中的 GitHub 和 GitHub Enterprise Server 存取](access-tokens-github-overview.md)。
+ 您可以透過 [ImportSourceCredentials API](https://docs.aws.amazon.com/cli/latest/reference/codebuild/import-source-credentials.html) 匯入 GitHub 登入資料。這只能使用個人存取字符來完成。如果您使用 OAuth 應用程式進行連線，則必須改用 主控台進行連線。如需說明，請參閱[使用存取字符 (CLI) 連接 GitHub](access-tokens-github.md#access-tokens-github-cli)。
**注意**
只有在您尚未連線到您帳戶的 GitHub 時，才需要這麼做。
## 步驟 1：使用 Webhook 建立 CodeBuild 專案
在此步驟中，您將使用 Webhook 建立 CodeBuild 專案，並在 GitHub 主控台中檢閱。您也可以選擇 GitHub Enterprise 做為來源提供者。若要進一步了解如何在 GitHub Enterprise 中建立 Webhook，請參閱 [GitHub 手動 Webhook](github-manual-webhook.md)。
**使用 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)。
1. 在**專案類型**中，選擇**執行器專案**。
在**執行器**中：
1. 針對**執行器提供者**，選擇 **GitHub**。
1. 針對**執行器位置**，選擇**儲存庫**。
1. 針對儲存庫下的**儲存庫** URL，選擇 **https://github.com/user-name/repository-name**。
**注意**
根據預設，您的專案只會接收單一儲存庫`WORKFLOW_JOB_QUEUED`的事件。如果您想要接收組織或企業內所有儲存庫的事件，請參閱 [GitHub 全域和組織 Webhook](github-global-organization-webhook.md)。
1.
+ 在 **Environment (環境)** 中：
+ 選擇支援**的環境映像**和**運算**。請注意，您可以選擇使用 GitHub Actions 工作流程 YAML 中的標籤覆寫映像和執行個體設定。如需詳細資訊，請參閱[步驟 2：更新您的 GitHub 動作工作流程 YAML](#sample-github-action-runners-update-yaml)
+ 在 **Buildspec (建置規格)** 中：
+ 請注意，除非`buildspec-override:true`新增為標籤，否則您的 buildspec 將被忽略。反之，CodeBuild 會覆寫它，以使用設定自我託管執行器的命令。
1. 繼續執行預設值，然後選擇**建立建置專案**。
1. 在 開啟 GitHub 主控台`https://github.com/user-name/repository-name/settings/hooks`，確認 Webhook 已建立並啟用，以交付**工作流程任務**事件。
## 步驟 2：更新您的 GitHub 動作工作流程 YAML
在此步驟中，您將在 中更新 GitHub Actions 工作流程 YAML 檔案[https://github.com/](https://github.com/)，以設定您的建置環境，並在 CodeBuild 中使用 GitHub Actions 自我託管執行器。如需詳細資訊，請參閱[搭配自我託管執行器使用標籤](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 Actions 工作流程 YAML [https://github.com/](https://github.com/)並更新[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)設定，以設定您的建置環境。若要這樣做，您可以執行下列其中一項操作：
+ 您可以指定專案名稱和執行 ID，在這種情況下，組建會將您現有的專案組態用於運算、映像、映像版本和執行個體大小。需要專案名稱，才能將 GitHub Actions 任務的 AWS相關設定連結至特定的 CodeBuild 專案。透過在 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 Actions Runner 支援運算映像](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!"
```
+ 若要在自訂映像上執行 GitHub 動作任務，您可以在 CodeBuild 專案中設定自訂映像，並避免提供映像覆寫標籤。如果未提供影像覆寫標籤，CodeBuild 將使用專案中設定的影像。
+ 或者，您可以在 CodeBuild 支援的標籤之外提供標籤。為了覆寫組建的屬性，將忽略這些標籤，但 Webhook 請求不會失敗。例如，將 新增`testLabel`為標籤不會阻止組建執行。
**注意**
如果 CodeBuild 環境中無法使用 GitHub 託管執行器提供的相依性，您可以在工作流程執行中使用 GitHub 動作安裝相依性。例如，您可以使用 [https://github.com/actions/setup-python](https://github.com/actions/setup-python)動作為您的建置環境安裝 Python。
### 執行 buildspec 命令 INSTALL、PRE\$1BUILD 和 POST\$1BUILD 階段
根據預設，CodeBuild 會在執行自我託管的 GitHub Actions 組建時忽略任何 buildspec 命令。若要在建置期間執行 buildspec 命令， `buildspec-override:true` 可以新增為標籤的尾碼：
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
buildspec-override:true
```
透過使用此命令，CodeBuild `actions-runner` 將在容器的主要來源資料夾中建立名為 的資料夾。當 GitHub Actions 執行器在 `BUILD`階段期間啟動時，執行器將在 `actions-runner`目錄中執行。
在自我託管 GitHub 動作建置中使用 buildspec 覆寫時，有幾個限制：
+ CodeBuild 不會在`BUILD`階段期間執行 buildspec 命令，因為自我託管執行器會在`BUILD`階段中執行。
+ CodeBuild 不會在`DOWNLOAD_SOURCE`階段期間下載任何主要或次要來源。如果您已設定 buildspec 檔案，則只會從專案的主要來源下載該檔案。
+ 如果建置命令在 `PRE_BUILD`或 `INSTALL`階段失敗，CodeBuild 將不會啟動自我託管執行器，而且需要手動取消 GitHub Actions 工作流程任務。
+ CodeBuild 會在`DOWNLOAD_SOURCE`階段期間擷取執行器權杖，其過期時間為一小時。如果您的 `PRE_BUILD`或 `INSTALL`階段超過一小時，執行器字符可能會在 GitHub 自我託管執行器啟動之前過期。
## 步驟 3：檢閱您的結果
每當 GitHub Actions 工作流程執行時，CodeBuild 會透過 Webhook 接收工作流程任務事件。對於工作流程中的每個任務，CodeBuild 會啟動組建以執行暫時性 GitHub Actions 執行器。執行器負責執行單一工作流程任務。任務完成後，執行器和相關聯的建置程序將立即終止。
若要檢視工作流程任務日誌，請導覽至 GitHub 中的儲存庫、選擇**動作**、選擇所需的工作流程，然後選擇您要檢閱日誌的特定**任務**。
您可以在任務等待 CodeBuild 中的自我託管執行器提取時，檢閱日誌中請求的標籤。
![\[載入任務的日誌。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/hello-world-loading.png)
任務完成後，您就可以檢視任務的日誌。
![\[任務的日誌。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/hello-world-log.png)
## GitHub Actions 執行器組態選項
您可以在專案組態中指定下列環境變數，以修改自我託管執行器的設定組態。
`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)。
根據預設，企業執行器不適用於組織儲存庫。若要讓自我託管執行器接收工作流程任務，您可能需要設定執行器群組存取設定。如需詳細資訊，請參閱[讓企業執行器可供儲存庫使用](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。如需自我託管執行器群組的詳細資訊，請參閱[使用群組管理對自我託管執行器的存取](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 Actions 工作流程 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 Actions 工作流程 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 Actions 工作流程 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 時觸發組建。下列篩選條件群組會指定工作流程名稱符合規則表達式 的 GitHub Actions 工作流程任務請求`\[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 命令會使用 GitHub Actions 工作流程任務請求篩選條件群組來建立自我託管的 GitHub Actions 執行器專案，該群組會在評估為 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`
路由自我託管的 GitHub 動作任務時，GitHub 會將任務路由到具有所有任務指定標籤的任何執行器。此行為表示任務 **1** 可以由為任務 1 或**任務** **2 建立的執行器挑選**，但**任務 2** 只能由為**任務 2 **建立的執行器挑選，因為它具有額外的標籤。如果**任務 1** 是由為**任務 2 **建立的執行器接管，則**任務 2** 將會停滯，因為**任務 1** 執行器沒有`instance-size:medium`標籤。
**建議的解決方案： **
在相同的工作流程執行中建立多個任務時，請為每個任務使用相同數量的標籤覆寫，或為每個任務指派自訂標籤，例如 `job1`或 `job2`。
如果錯誤仍然存在，請使用下列指示來偵錯問題。
1. 開啟位於 的 GitHub 主控台`https://github.com/user-name/repository-name/settings/hooks`，以檢視儲存庫的 Webhook 設定。在此頁面上，您會看到為儲存庫建立的 Webhook。
1. 選擇**編輯**並確認已啟用 Webhook 以交付**工作流程任務**事件。
![\[工作流程任務事件會在 Webhook 中啟用。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/github-actions-workflow-jobs.png)
1. 導覽至**最近傳送**索引標籤，尋找對應的`workflow_job.queued`事件，然後展開事件。
1. 檢閱**承載**中的**標籤**欄位，並確認其如預期。
1. 最後，檢閱**回應**索引標籤，因為這包含 CodeBuild 傳回的回應或錯誤訊息。
![\[CodeBuild 傳回的回應或錯誤訊息。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/github-actions-workflow-jobs-response.png)
1. 或者，您可以使用 GitHub 的 APIs偵錯 Webhook 失敗。您可以使用[儲存庫 Webhook API 的列出交付來檢視 Webhook 的最新交付](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#list-deliveries-for-a-repository-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 API 的交付](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#get-a-delivery-for-a-repository-webhook)。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 會擷取與 GitHub 動作任務相關聯的部署和環境，如果它們存在，以驗證 是否已核准。如果 CodeBuild 無法擷取部署或環境，則 CodeBuild 建置可能會提早觸發。
**建議的解決方案：**確認與 CodeBuild 專案相關聯的登入資料具有 GitHub 內部署和動作的讀取許可。
# CodeBuild 託管的 GitHub 動作執行器支援標籤覆寫
在 GitHub Actions 工作流程 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 Actions 工作流程 YAMLs都需要。** 應等於設定自我託管執行器 Webhook 的專案名稱。
`image:-`
+ 範例：`image:arm-3.0`
+ 覆寫使用精選映像啟動自我託管執行器建置時所使用的映像和環境類型。若要了解支援的值，請參閱 [CodeBuild 託管的 GitHub Actions Runner 支援運算映像](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 Actions Runner 支援運算映像](sample-github-action-runners-update-yaml.images.md)。
`fleet:`
+ 範例：`fleet:myFleet`
+ 覆寫專案上設定的機群設定，以使用指定的機群。如需詳細資訊，請參閱[在預留容量機群上執行組建](fleets.md)。
`buildspec-override:`
+ 範例：`buildspec-override:true`
+ 如果設為 `PRE_BUILD`，允許組建在 `INSTALL`、 和 `POST_BUILD`階段中執行 buildspec 命令`true`。
## 單一標籤覆寫 （舊版）
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 Actions Runner 支援運算映像
在您在 中設定的標籤中[教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](action-runner.md)，您可以使用前三欄中的值覆寫 Amazon EC2 環境設定。CodeBuild 提供下列 Amazon EC2 運算映像。如需關於
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/codebuild/latest/userguide/sample-github-action-runners-update-yaml.images.html)
如需詳細資訊，請參閱[建置環境運算模式和類型](build-env-ref-compute-types.md)及[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)。
# 中的自我管理 GitLab 執行器 AWS CodeBuild
GitLab 提供兩種執行模式，可在 CI/CD 管道中執行 GitLab 任務。一種模式是 GitLab 託管的執行器，由 GitLab 管理並與 GitLab 完全整合。另一個模式是自我管理的執行器，可讓您將自己的自訂環境帶入 GitLab CI/CD 管道中執行任務。
設定 CodeBuild 專案以執行 GitLab CI/CD 管道任務的高階步驟如下：
1. 如果您尚未這麼做，請連線至 OAuth 應用程式，將您的專案連線至 GitLab。
1. 導覽至 CodeBuild 主控台，並使用 Webhook 建立 CodeBuild 專案，並設定您的 Webhook 篩選條件。
1. 在 GitLab 中更新您的 GitLab CI/CD 管道 YAML，以設定您的建置環境。
如需更詳細的程序，請參閱 [教學課程：設定 CodeBuild 託管的 GitLab 執行器](sample-gitlab-runners.md)。
此功能可讓您的 GitLab CI/CD 管道任務取得與 的原生整合 AWS，透過 IAM、 和 Amazon VPC 等功能提供安全性 AWS CloudTrail和便利性。您可以存取最新的執行個體類型，包括以 ARM 為基礎的執行個體。
**Topics**
+ [關於 CodeBuild 託管的 GitLab Runner](gitlab-runner-questions.md)
+ [教學課程：設定 CodeBuild 託管的 GitLab 執行器](sample-gitlab-runners.md)
+ [CodeBuild 託管的 GitLab Runner 支援標籤覆寫](gitlab-runners-update-labels.md)
+ [CodeBuild 託管的 GitLab Runner 支援的運算映像](sample-gitlab-runners-gitlab-ci.images.md)
# 關於 CodeBuild 託管的 GitLab Runner
以下是有關 CodeBuild 託管 GitLab 執行器的一些常見問題。
## CodeBuild 託管的 GitLab 執行器支援哪些來源類型？
`GITLAB` 和`GITLAB_SELF_MANAGED`來源類型支援 CodeBuild 託管的 GitLab 執行器。
## 我應該在標籤中何時包含映像和執行個體覆寫？
您可以在 標籤中包含映像和執行個體覆寫，以便為每個 GitLab CI/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 中執行 GitLab 自我管理執行器[，方法是使用自訂映像建立專案](create-project.md#environment-image.console)，或[覆寫檔案中的映像](sample-gitlab-runners.md#sample-gitlab-runners-gitlab-ci)。 `.gitlab-ci.yml`
## CodeBuild 中的自我管理執行器會搭配哪些執行器執行？
CodeBuild 中的自我管理執行器會使用 shell 執行器執行，其中建置會在本機執行，並搭配在 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 執行器。如需 CodeBuild 可用 AWS 區域 位置的詳細資訊，請參閱[AWS 依區域的服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。
## 哪些平台支援使用 CodeBuild 託管的 GitLab 執行器？
Amazon EC2 和[AWS Lambda](lambda.md)運算都支援 CodeBuild 託管的 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 專案以執行 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\]
```
# CodeBuild 託管的 GitLab Runner 支援標籤覆寫
在 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 Runner 支援的運算映像](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 Runner 支援的運算映像](sample-gitlab-runners-gitlab-ci.images.md)。
`fleet:`
+ 範例：`fleet:myFleet`
+ 覆寫專案上設定的機群設定，以使用指定的機群。如需詳細資訊，請參閱[在預留容量機群上執行組建](fleets.md)。
`buildspec-override:`
+ 範例：`buildspec-override:true`
+ 如果設為 `PRE_BUILD`，允許組建在 `INSTALL`、 和 `POST_BUILD`階段中執行 buildspec 命令`true`。
# CodeBuild 託管的 GitLab Runner 支援的運算映像
在您在 中設定的標籤中[教學課程：設定 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_tw/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_tw/codebuild/latest/userguide/sample-gitlab-runners-gitlab-ci.images.html)
如需詳細資訊，請參閱[建置環境運算模式和類型](build-env-ref-compute-types.md)及[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)。
# 中的自我管理 Buildkite 執行器 AWS CodeBuild
您可以設定專案在 CodeBuild 容器中設定自我託管的 Buildkite 執行器，以處理您的 Buildkite 任務。這可以透過使用 CodeBuild 專案設定 Webhook，並更新您的 Buildkite 管道 YAML 步驟來使用 CodeBuild 機器上託管的自我託管執行器來完成。
設定 CodeBuild 專案以執行 Buildkite 任務的高階步驟如下：
+ 導覽至 CodeBuild 主控台，並使用 Buildkite 執行器專案執行器類型組態建立 CodeBuild 專案
+ 將 `job.scheduled` Webhook 新增至您的 Buildkite 組織。
+ 在 Buildkite 中更新您的 Buildkite 管道 YAML 步驟，以設定您的建置環境。
如需更詳細的程序，請參閱 [教學課程：設定 CodeBuild 託管的 Buildkite 執行器](sample-runner-buildkite.md)。此功能可讓您的 Buildkite 任務與 原生整合 AWS，透過 IAM AWS Secrets Manager、 AWS CloudTrail、 和 Amazon VPC 等功能提供安全性和便利性。您可以存取最新的執行個體類型，包括以 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"
```
## CodeBuild 是否可以在 Buildkite 中自動建立 Webhook？
目前， Buildkite 要求使用其主控台手動建立所有 Webhook。您可以遵循 的教學課程[教學課程：設定 CodeBuild 託管的 Buildkite 執行器](sample-runner-buildkite.md)，在 Buildkite 主控台中手動建立 Buildkite Webhook。
## 我可以使用 CloudFormation 來建立 Buildkite Webhook 嗎？
CloudFormation 目前不支援 Buildkite 執行器 Webhook，因為 Buildkite 需要使用其主控台手動建立 Webhook。
## 哪些區域支援使用 CodeBuild 託管的 Buildkite 執行器？
所有 CodeBuild 區域都支援 CodeBuild 託管的 Buildkite 執行器。如需 CodeBuild 可用 AWS 區域的詳細資訊，請參閱[AWS 依區域提供服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。
# 教學課程：設定 CodeBuild 託管的 Buildkite 執行器
本教學課程說明如何設定 CodeBuild 專案以執行 Buildkite 任務。如需搭配 CodeBuild 使用 Buildkite 的詳細資訊，請參閱 [中的自我管理 Buildkite 執行器 AWS CodeBuild](buildkite-runner.md)。
若要完成此教學課程，您必須先：
+ 有權存取 Buildkite 組織。如需有關設定 Buildkite 帳戶和組織的詳細資訊，您可以遵循此[入門教學課程](https://buildkite.com/docs/pipelines/getting-started)。
+ 建立設定為使用自我託管執行器的 Buildkite 管道、叢集和佇列。如需有關設定這些資源的詳細資訊，您可以參考 [ Buildkite 管道設定教學課程](https://buildkite.com/docs/pipelines/create-your-own)。
![\[在 Buildkite 中建置專案\]](http://docs.aws.amazon.com/zh_tw/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_tw/codebuild/latest/userguide/images/buildkite-createtoken.png)
## 步驟 2：使用 Webhook 建立 CodeBuild 專案
**使用 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 供應商**，選擇 **Buildkite**。
+ 對於 **Buildkite 代理程式字符**，使用**建立秘密頁面選擇建立新的代理程式字符**。系統會提示您在 中建立新的秘密 AWS Secrets Manager ，秘密值等於您在上面產生的 Buildkite 代理程式字符。
+ （選用） 如果您想要為任務使用 CodeBuild 受管登入資料，請在 **Buildkite 來源登入資料選項下選取任務的來源**儲存庫提供者，並確認已為您的帳戶設定登入資料。此外，確認您的 Buildkite 管道使用 **HTTPS 的 Checkout**。
**注意**
Buildkite 需要建置環境中的來源登入資料，才能提取任務的來源。如需可用的來源登入資料選項[向私有儲存庫驗證 Buildkite](#sample-runner-buildkite-config)，請參閱 。
+ （選用） **在環境中**：
+ 選擇支援**的環境映像**和**運算**。
請注意，您可以選擇使用 Buildkite YAML 步驟中的標籤覆寫映像和執行個體設定。如需詳細資訊，請參閱[步驟 4：更新您的 Buildkite 管道步驟](#sample-runner-buildkite-update-pipeline)。
+ （選用） 在 **Buildspec** 中：
+ 除非`buildspec-override: "true"`新增為標籤，否則預設會忽略您的 buildspec。反之，CodeBuild 會覆寫它，以使用將設定自我託管執行器的命令。
**注意**
CodeBuild 不支援 Buildkite 自我託管執行器建置的 buildspec 檔案。對於內嵌 buildspec，如果您已設定 CodeBuild 受管來源憑證，則需要在 buildspec 中啟用 [ 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** 和**秘密**值，在 Buildkite 中建立新的 Webhook。當有效的 Buildkite 任務啟動時，此 Webhook 將用於觸發 CodeBuild 中的組建。
**在 Buildkite 中建立新的 Webhook**
1. 導覽至您 Buildkite 組織的**設定**頁面。
1. 在**整合**下，選取**通知服務**。
1. 選擇 **Webhook** 方塊旁的**新增**。在**新增 Webhook 通知**頁面中，使用下列組態：
1. 在 **Webhook URL** 下，新增已儲存的**承載 URL** 值。
1. 在**字符**下，確認已選取**以 X-Buildkite-Token 傳送字符**。將 Webhook **Secret** 值新增至 **Token** 欄位。
1. 在 下，確認已選取**以 X-Buildkite-Token 傳送權杖**。將 Webhook **Secret** 值新增至 **Token** 欄位。
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_tw/codebuild/latest/userguide/images/buildkite-steps.png)
1. 您至少需要指定參考 CodeBuild 管道名稱的 [ Buildkite 代理程式標籤](https://buildkite.com/docs/agent/v3/cli-start#agent-targeting)。需要專案名稱，才能將 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_tw/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 登入資料，請確認它們已正確設定。此外，如果您的專案已設定內嵌 buildspec，請確認 [ 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_tw/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. 將[新的 SSH 金鑰秘密](https://buildkite.com/docs/pipelines/hosted-agents/code-access#private-repositories-with-other-providers-add-the-ssh-key-secret)新增至 Buildkite 叢集。在 Buildkite 叢集中，選取**秘密** → **新秘密**。在**金鑰**欄位中新增秘密的名稱，並將私有 SSH 金鑰新增至**值**欄位中：
![\[檢閱結果。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/buildkite-secret.png)
1. 在 Buildkite 管道中，導覽至儲存庫設定，並將結帳設定為使用 **SSH**。
![\[檢閱結果。\]](http://docs.aws.amazon.com/zh_tw/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. 在 CodeBuild 中執行 Buildkite 自我託管執行器任務時，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 命令
根據預設，CodeBuild 會在執行自我託管的 Buildkite 執行器建置時忽略任何 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 為 `git-credential-helper` Buildkite 組建啟用 ：
```
version: 0.2
env:
git-credential-helper: yes
phases:
pre_build:
commands:
- echo "Hello World"
```
+ CodeBuild 不會在`BUILD`階段期間執行 buildspec 命令，因為自我託管執行器會在`BUILD`階段中執行。
+ CodeBuild 不支援 Buildkite Runner 組建的 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 進行故障診斷
**問題： **
您在 中設定的 Webhook [教學課程：設定 CodeBuild 託管的 Buildkite 執行器](sample-runner-buildkite.md) 無法運作，或您的工作流程任務在 Buildkite 中懸置。
**可能的原因： **
+ 您的 Webhook **job.scheduled** 事件可能無法觸發組建。檢閱**回應**日誌以檢視回應或錯誤訊息。
+ 您的 CodeBuild 組建會在啟動 Buildkite 自我託管執行器代理程式來處理任務之前失敗。
**建議的解決方案： **
若要偵錯失敗的 Buildkite Webhook 事件：
1. 在您的 Buildkite 組織設定中，導覽至 **Notification Services**，選取您的 CodeBuild Webhook，然後尋找**請求日誌**。
1. 尋找與您停滯的 Buildkite 任務相關聯的 `job.scheduled` Webhook 事件。您可以使用 Webhook 承載中的任務 ID 欄位，將 Webhook 事件與 Buildkite 任務建立關聯。
1. 選取**回應**索引標籤並檢查回應內文。確認**回應**狀態碼為 ，`200`且**回應**內文不包含任何非預期的訊息。
![\[Webhook 的回應。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/buildkite-request.png)
# 故障診斷 Webhook 許可問題
**問題： **
由於許可問題， Buildkite 任務無法簽出任務的來源儲存庫。
**可能的原因： **
+ CodeBuild 沒有足夠的許可來檢查任務的來源儲存庫。
+ 管道的儲存庫設定設定為使用 SSH for 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 代理程式佇列標籤](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"`
+ 如果設為 `PRE_BUILD`，允許組建在 `INSTALL`、 和 `POST_BUILD`階段中執行 buildspec 命令`true`。
# 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_tw/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_tw/codebuild/latest/userguide/buildkite-runner-update-yaml.images.html)
如需詳細資訊，請參閱[建置環境運算模式和類型](build-env-ref-compute-types.md)及[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)。