本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學課程：設定 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\"}]]"
```