本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 教學課程：設定 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`，以防止來源登入資料載入建置環境。