本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 CodeBuild 中存取您的來源提供者 對於 GitHub 或 GitHub Enterprise Server，您可以使用個人存取字符、Secrets Manager 秘密、連線或 OAuth 應用程式來存取來源提供者。對於 Bitbucket，您可以使用存取字符、應用程式密碼、Secrets Manager 秘密、連線或 OAuth 應用程式來存取來源提供者。 **Topics** + [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md) + [CodeBuild 中的 GitHub 和 GitHub Enterprise Server 存取](access-tokens-github-overview.md) + [CodeBuild 中的 Bitbucket 存取](access-tokens-bitbucket-overview.md) + [CodeBuild 中的 GitLab 存取](access-tokens-gitlab-overview.md) # 在 Secrets Manager 秘密中建立和存放權杖 如果您選擇使用 來存放使用 Secrets Manager 的存取字符，您可以使用現有的秘密連線或建立新的秘密。若要建立新的秘密，請執行下列動作： ------ #### [ AWS 管理主控台 ] **在 中建立 Secrets Manager 秘密 AWS 管理主控台** 1. 針對**來源提供者**，選擇 **Bitbucket**、**GitHub** 或 **GitHub Enterprise**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇**預設來源登入**資料，以使用您帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線到來源提供者，請選擇**管理預設來源憑證**。 1. 針對**登入資料類型**，選擇 **CodeConnections** 以外的登入資料類型。 1. 針對**服務**，選擇 **Secrets Manager**，針對 **Secrets** 選擇**新秘密**。 1. 在**秘密名稱**中，輸入秘密的名稱。 1. 在**秘密描述 - 選用**中，輸入秘密的描述。 1. 根據您選擇的來源提供者，輸入您的字符或使用者名稱和應用程式密碼，然後選擇**儲存**。 + 選擇**自訂來源登入**資料，以使用自訂來源登入資料覆寫您帳戶的預設設定。 1. 針對**登入資料類型**，選擇 **CodeConnections** 以外的登入資料類型。 1. 在**連線**中，選擇**建立秘密**。 1. 在**秘密名稱**中，輸入秘密的名稱。 1. 在**秘密描述 - 選用**中，輸入秘密的描述。 1. 根據您選擇的來源提供者，輸入您的字符或使用者名稱和應用程式密碼，然後選擇**建立**。 ------ #### [ AWS CLI ] **在 中建立 Secrets Manager 秘密 AWS CLI** + 開啟終端機 (Linux、macOS 或 Unix) 或命令提示 (Windows)。使用 AWS CLI 執行 Secrets Manager **create-secret**命令。 ``` aws secretsmanager create-secret --region \ --name '' \ --description '' \ --secret-string '{ "ServerType":"", "AuthType":"", "Token":"" }' \ --tags Key=codebuild:source,Value='' \ Key=codebuild:source:type,Value= \ Key=codebuild:source:provider,Value= ``` CodeBuild 接受的 Secrets Manager 秘密必須與 CodeBuild 專案位於相同的帳戶和 AWS 區域，且必須是下列 JSON 格式： ``` { "ServerType": ServerType, "AuthType: AuthType, "Token": string, "Username": string // Optional and is only used for Bitbucket app password } ``` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/asm-create-secret.html) 此外，CodeBuild 會在秘密上使用下列資源標籤，以確保在建立或編輯專案時可輕鬆選取秘密。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/asm-create-secret.html) ------ # CodeBuild 中的 GitHub 和 GitHub Enterprise Server 存取 對於 GitHub，您可以使用個人存取字符、OAuth 應用程式、Secrets Manager 秘密或 GitHub 應用程式連線來存取來源提供者。對於 GitHub Enterprise Server，您可以使用個人存取字符、Secrets Manager 秘密或 GitHub 應用程式連線來存取來源提供者。 **Topics** + [GitHub 和 GitHub Enterprise Server 的 GitHub 應用程式連線](connections-github-app.md) + [GitHub 和 GitHub Enterprise Server 存取權杖](access-tokens-github.md) + [GitHub OAuth 應用程式](oauth-app-github.md) # GitHub 和 GitHub Enterprise Server 的 GitHub 應用程式連線 您可以使用 GitHub 應用程式與 CodeBuild 連線。透過 支援 GitHub 應用程式連線[AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html)。 來源提供者存取可讓您[GitHub Webhook 事件](github-webhook.md)使用 [ CreateWebhook](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateWebhook.html) 訂閱 或在 CodeBuild [教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](action-runner.md)中使用 來觸發組建。 **注意** CodeConnections 可在比 CodeBuild 更少的區域中使用。您可以在 CodeBuild 中使用跨區域連線。在選擇加入區域中建立的連線無法在其他區域中使用。如需詳細資訊，請參閱 [AWS CodeConnections 端點和配額](https://docs.aws.amazon.com/general/latest/gr/codestar_connections.html)。 **Topics** + [步驟 1：建立 GitHub 應用程式的連線 （主控台）](#connections-github-console) + [步驟 2：授予 CodeBuild 專案 IAM 角色存取權以使用連線](#connections-github-role-access) + [步驟 3：設定 CodeBuild 以使用新的連線](#connections-github-account-credential) + [故障診斷 GitHub 應用程式](#connections-github-troubleshooting) ## 步驟 1：建立 GitHub 應用程式的連線 （主控台） 使用這些步驟來使用 CodeBuild 主控台為 GitHub 中的專案新增連線。 **建立連至 GitHub 的連線** + 請遵循*開發人員工具使用者指南*中[建立 GitHub 連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html)的說明。 **注意** 您可以使用從另一個帳戶共用的連線，而不是在帳戶中建立或使用現有的連線 AWS 。如需詳細資訊，請參閱[與 AWS 帳戶共用連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html)。 ## 步驟 2：授予 CodeBuild 專案 IAM 角色存取權以使用連線 您可以授予 CodeBuild 專案 IAM 角色存取權，以使用連線提供的 GitHub 權杖。 **授予 CodeBuild 專案 IAM 角色存取權** 1. 遵循 CodeBuild 專案的 指示，為您的 CodeBuild 專案建立 [允許 CodeBuild 與其他 AWS 服務互動](setting-up-service-role.md) IAM 角色。 1. 遵循指示時，將下列 IAM 政策新增至 CodeBuild 專案角色，以授予連線的存取權。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [ "arn:aws:iam::*:role/Service*" ] } ] } ``` ------ ## 步驟 3：設定 CodeBuild 以使用新的連線 您可以將連線設定為帳戶層級登入資料，並在專案中使用。 ------ #### [ AWS 管理主控台 ] **若要在 中將連線設定為帳戶層級登入資料 AWS 管理主控台** 1. 針對 **Source provider (來源供應商)**，選擇 **GitHub**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇**預設來源登入**資料，以使用您帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 GitHub，請選擇**管理預設來源憑證**。 1. 針對**登入資料類型**，選擇 **GitHub 應用程式**。 1. 在**連線**中，選擇使用現有的連線或建立新的連線。 + 選擇**自訂來源登入**資料，以使用自訂來源登入資料覆寫您帳戶的預設設定。 1. 針對**登入資料類型**，選擇 **GitHub 應用程式**。 1. 在**連線**中，選擇使用現有的連線或建立新的連線。 ------ #### [ AWS CLI ] **若要在 中將連線設定為帳戶層級登入資料 AWS CLI** + 開啟終端機 (Linux、macOS 或 Unix) 或命令提示 (Windows)。使用 AWS CLI 執行 **import-source-credentials**命令，`--token`為您的連線指定 `--auth-type`、 `--server-type`和 。 使用下列命令： ``` aws codebuild import-source-credentials --auth-type CODECONNECTIONS --server-type GITHUB --token ``` ------ 您也可以為 CodeBuild 專案設定多個權杖。如需詳細資訊，請參閱[將多個字符設定為來源層級登入資料](multiple-access-tokens.md#asm-source-credential)。 ## 對 GitHub 應用程式的問題進行故障診斷 以下資訊可協助您對 GitHub 應用程式的常見問題進行故障診斷。 **Topics** + [在不需要的區域安裝 AWS Connector for GitHub 應用程式](#connections-github-troubleshooting.undesired-region) + [GitHub 應用程式連線無法存取儲存庫](#connections-github-troubleshooting.repo-access) + [AWS 服務的 IAM 角色缺少必要的 IAM 許可。](#connections-github-troubleshooting.iam-permissions) ### 在不需要的區域安裝 AWS Connector for GitHub 應用程式 **問題：**您從 GitHub Marketplace 安裝 AWS 了 Connector for GitHub，但連線是在不需要的區域建立的。如果您嘗試在 GitHub 網站上重新設定應用程式，它將無法運作，因為應用程式已安裝在您的 GitHub 帳戶。 **可能原因：**應用程式已安裝在您的 GitHub 帳戶中，因此您只能重新設定應用程式許可。 **建議的解決方案：**您可以使用所需區域中的安裝 ID 建立新的連線。 1. 在 https：//[https://console.aws.amazon.com/codesuite/settings/connections](https://console.aws.amazon.com/codesuite/settings/connections) 開啟 CodeConnections 主控台，並使用 AWS 主控台導覽列中的區域選擇器導覽至所需區域。 1. 請遵循*開發人員工具使用者指南*中[建立 GitHub 連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html)的說明。 **注意** 由於您已安裝 AWS Connector for GitHub 應用程式，因此可以選擇它，而不是安裝新的應用程式。 ### GitHub 應用程式連線無法存取儲存庫 **問題：**使用連線 AWS 的服務，例如 CodeBuild 或 CodePipeline，報告其無法存取儲存庫或儲存庫不存在。一些可能的錯誤訊息包括： + `Authentication required for primary source.` + `Unable to create webhook at this time. Please try again later.` + `Failed to create webhook. GitHub API limit reached. Please try again later.` ***可能原因：**您可能一直使用 GitHub 應用程式，但尚未授予 Webhook 許可範圍。* **建議的解決方案：**若要授予所需的許可範圍，請遵循[導覽至您要檢閱或修改的 GitHub 應用程式](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify)中的指示，以設定已安裝的應用程式。在許可區段下，您會看到應用程式沒有 Webhook 許可，而且您可以選擇檢閱新請求的許可。檢閱並接受新的許可。如需詳細資訊，請參閱[核准 GitHub 應用程式的更新許可](https://docs.github.com/en/apps/using-github-apps/approving-updated-permissions-for-a-github-app)。 ***可能原因：**連線如預期般運作，但突然無法存取儲存庫。* **可能的解決方案：**從檢閱您的[授權](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps)和[安裝](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps)開始，然後驗證 GitHub 應用程式是否已授權並安裝。如果 GitHub 應用程式安裝已暫停，則需要將其取消暫停。如果 GitHub 應用程式未獲授權進行 [UAT （使用者存取字符）](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) 連線，或未針對 [ IAT （安裝存取字符）](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) 連線安裝，則現有的連線將無法再使用，而且您將需要建立新的連線。請注意，重新安裝 GitHub 應用程式不會復原與舊安裝相關聯的先前連線。 **可能的解決方案：**如果連線是 UAT 連線，請確定未同時使用連線，例如在多個 CodeBuild 並行建置執行中使用 。這是因為如果連線重新整理過期權杖，GitHub 會立即使先前發行的 UAT 失效。如果您需要將 UAT 連線用於多個並行 CodeBuild 組建，您可以建立多個連線並獨立使用每個連線。 **可能的解決方案：**如果在過去 6 個月內未使用 UAT 連線，GitHub 會將連線失效。若要修正此問題，請建立新的連線。 ***可能原因：**您可能已在未安裝應用程式的情況下使用 UAT 連線。* **建議的解決方案：**雖然建立 UAT 連線不需要將連線與 GitHub 應用程式安裝建立關聯，但需要安裝才能存取儲存庫。依照指示[檢閱安裝](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps)，以確保已安裝 GitHub 應用程式。如果未安裝，請導覽至 [GitHub 應用程式頁面](https://github.com/marketplace/aws-connector-for-github)以安裝應用程式。如需 UAT 存取的詳細資訊，請參閱[關於使用者存取字符](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#about-user-access-tokens)。 ### AWS 服務的 IAM 角色缺少必要的 IAM 許可。 **問題：**您會看到下列任何錯誤訊息： + `Access denied to connection ` + `Failed to get access token from ` **建議的解決方案：**通常您使用 AWS 服務連線，例如 CodePipeline 或 CodeBuild。當您為 AWS 服務提供 IAM 角色時，該 AWS 服務可以使用該角色的許可來代表您採取行動。確定 IAM 角色具有必要的許可。如需必要 IAM 許可的詳細資訊，請參閱《 *開發人員工具主控台使用者指南*》中的[授予 CodeBuild 專案 IAM 角色存取權，以使用](#connections-github-role-access)[AWS CodeStar 通知和 CodeConnections 的連線和身分和存取管理](https://docs.aws.amazon.com/dtconsole/latest/userguide/security-iam.html)。 # GitHub 和 GitHub Enterprise Server 存取權杖 ## 存取字符先決條件 開始之前，您必須將適當的許可範圍新增至 GitHub 存取字符。 對於 GitHub，您的個人存取字符必須具有以下範圍。 + **repo**：授予私有儲存庫的完全控制。 + **repo：status**：授予公有和私有儲存庫遞交狀態的讀取/寫入存取權。 + **admin:repo\$1hook**：授予儲存庫勾點的完全控制。如果您的字符有 `repo` 範圍，則不需要此範圍。 + **admin：org\$1hook**：授予組織勾點的完整控制權。只有在您使用組織 Webhook 功能時，才需要此範圍。 如需詳細資訊，請參閱 GitHub 網站上的[了解 OAuth 應用程式的範圍](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/)。 如果您使用精細的個人存取字符，根據您的使用案例，您的個人存取字符可能需要以下許可： + **內容：唯讀**：授予私有儲存庫的存取權。如果您使用私有儲存庫做為來源，則需要此許可。 + **遞交狀態：讀取和寫入**：授予建立遞交狀態的許可。如果您的專案已設定 Webhook，或者您已啟用報告建置狀態功能，則需要此許可。 + **Webhooks：讀取和寫入**：授予管理 Webhook 的許可。如果您的專案已設定 Webhook，則需要此許可。 + **提取請求：唯讀**：授予存取提取請求的許可。如果您的 Webhook 具有提取請求事件的`FILE_PATH`篩選條件，則需要此許可。 + **管理：讀取和寫入**：如果您搭配 CodeBuild 使用自我託管的 GitHub 動作執行器功能，則需要此許可。如需詳細資訊，請參閱[建立儲存庫的註冊字符](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository)和 [教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](action-runner.md)。 **注意** 如果您想要存取組織儲存庫，請務必將組織指定為存取字符的資源擁有者。 如需詳細資訊，請參閱 GitHub [ 網站上的微調個人存取字符所需的許可](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)。 ## 使用存取字符連接 GitHub （主控台） 若要使用主控台，使用存取字符將專案連線至 GitHub，請在建立專案時執行下列動作。如需相關資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 1. 針對 **Source provider (來源供應商)**，選擇 **GitHub**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇使用帳戶登入資料，將帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 GitHub，請選擇**管理帳戶登入**資料。 1. 針對**登入資料類型**，選擇**個人存取字符**。 + 如果您選擇使用 **Service** 的帳戶層級登入資料，請選擇您要用來存放字符的服務，並執行下列動作： 1. 如果您選擇使用 **Secrets Manager**，您可以選擇使用現有的秘密連線或建立新的秘密，然後選擇**儲存**。如需如何建立新的秘密的詳細資訊，請參閱 [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md)。 1. 如果您選擇使用 **CodeBuild**，請輸入您的 GitHub 個人存取字符，然後選擇**儲存**。 + 選取**僅使用此專案的覆寫登入**資料來使用自訂來源登入資料來覆寫帳戶的登入資料設定。 1. 從填入的登入資料清單中，選擇**個人存取字符**下的其中一個選項。 1. 您也可以在描述中選取建立新的個人存取權杖**連線，以建立新的個人存取權杖**。 ## 使用存取字符 (CLI) 連接 GitHub 請依照下列步驟使用 AWS CLI ，使用存取字符將您的專案連線至 GitHub。如需 AWS CLI 搭配 使用 的詳細資訊 AWS CodeBuild，請參閱 [命令列參考](cmd-ref.md)。 1. 執行 **import-source-credentials** 命令： ``` aws codebuild import-source-credentials --generate-cli-skeleton ``` 即會在輸出中顯示 JSON 格式化資料。將資料複製到 AWS CLI 安裝 的本機電腦或執行個體位置中的檔案 （例如 `import-source-credentials.json`)。如下所示修改複製的資料，並儲存您的結果。 ``` { "serverType": "server-type", "authType": "auth-type", "shouldOverwrite": "should-overwrite", "token": "token", "username": "username" } ``` 取代以下項目： + *server-type*：必要值。用於此登入資料的來源供應商。有效值為 GITHUB、BITBUCKET、GITHUB\$1ENTERPRISE、GITLAB 和 GITLAB\$1SELF\$1MANAGED。 + *auth-type*：必要值。用於連線至儲存庫的身分驗證類型。有效值為 OAUTH、BASIC\$1AUTH、Personal\$1ACCESS\$1TOKEN、CODECONNECTIONS 和 SECRETS\$1MANAGER。對於 GitHub，僅允許使用 Personal\$1ACCESS\$1TOKEN。BASIC\$1AUTH 僅允許使用 Bitbucket 應用程式密碼。 + *should-overwrite*：選用值。設為 `false` 可防止覆寫儲存庫來源登入資料。設為 `true` 可覆寫儲存庫來源登入資料。預設值為 `true`。 + *token*：必要值。對於 GitHub 或 GitHub Enterprise Server，這是個人存取字符。對於 Bitbucket，這是個人存取字符或應用程式密碼。對於 auth-type CODECONNECTIONS，這是連線 ARN。對於身分驗證類型 SECRETS\$1MANAGER，這是秘密 ARN。 + *username*：選用值。GitHub 和 GitHub Enterprise Server 來源提供者會忽略此參數。 1. 若要使用存取字符連接您的帳戶，請切換到包含您在步驟 1 中儲存的 `import-source-credentials.json` 檔案的目錄，並再次執行 **import-source-credentials** 命令。 ``` aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json ``` JSON 格式的資料會出現在 Amazon Resource Name (ARN) 的輸出中。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` **注意** 如果您使用相同的伺服器類型和身分驗證類型執行 **import-source-credentials** 命令第二次，即會更新存放的存取字符。 您的帳戶與存取字符連線後，您可以使用 `create-project` 來建立 CodeBuild 專案。如需詳細資訊，請參閱[建立建置專案 (AWS CLI)](create-project.md#create-project-cli)。 1. 若要檢視連接的存取字符，請執行 **list-source-credentials** 命令。 ``` aws codebuild list-source-credentials ``` 輸出中即會顯示 JSON 格式的 `sourceCredentialsInfos` 物件： ``` { "sourceCredentialsInfos": [ { "authType": "auth-type", "serverType": "server-type", "arn": "arn" } ] } ``` `sourceCredentialsObject` 包含連接的來源登入資料資訊的清單： + `authType` 是登入資料使用的身分驗證類型。這可以是 `OAUTH`、`BASIC_AUTH`、`CODECONNECTIONS`、 `PERSONAL_ACCESS_TOKEN`或 `SECRETS_MANAGER`。 + `serverType` 是來源供應商的類型。這可以是 `GITHUB`、`GITHUB_ENTERPRISE`、`GITLAB`、 `BITBUCKET`或 `GITLAB_SELF_MANAGED`。 + `arn` 為字符的 ARN。 1. 若要與來源供應商中斷連接並移除其存取字符，請使用其 ARN 執行 **delete-source-credentials** 命令。 ``` aws codebuild delete-source-credentials --arn arn-of-your-credentials ``` JSON 格式的資料會隨著所刪除登入資料的 ARN 傳回。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` # GitHub OAuth 應用程式 ## 使用 OAuth 連接 GitHub （主控台） 若要使用 主控台，使用 OAuth 應用程式將專案連線至 GitHub，請在建立專案時執行下列動作。如需相關資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 1. 針對 **Source provider (來源供應商)**，選擇 **GitHub**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇使用帳戶登入資料，將帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 GitHub，請選擇**管理帳戶登入**資料。 1. 針對**登入資料類型**，選擇 **OAuth 應用程式**。 + 如果您選擇使用 **Service** 的帳戶層級登入資料，請選擇您要用來存放字符的服務，並執行下列動作： 1. 如果您選擇使用 **Secrets Manager**，您可以選擇使用現有的秘密連線或建立新的秘密，然後選擇**儲存**。如需如何建立新的秘密的詳細資訊，請參閱 [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md)。 1. 如果您選擇使用 **CodeBuild**，然後選擇**儲存**。 + 選取**僅使用此專案的覆寫登入**資料來使用自訂來源登入資料來覆寫帳戶的登入資料設定。 1. 從填入的登入資料清單中，選擇 **OAuth 應用程式**下的其中一個選項。 1. 您也可以在描述中選取建立新的 Oauth 應用程式字符連線，以建立新的 OAuth 應用程式字符。 **** 若要檢閱授權的 OAuth 應用程式，請導覽至 GitHub 上的[應用程式](https://github.com/settings/applications)，並確認已列出由 [aws-codesuite](https://github.com/aws-codesuite) `AWS CodeBuild (region)`擁有且名為 的應用程式。 # CodeBuild 中的 Bitbucket 存取 對於 Bitbucket，您可以使用存取字符、應用程式密碼、OAuth 應用程式或 Bitbucket 連線來存取來源提供者。 **Topics** + [Bitbucket 應用程式連線](connections-bitbucket-app.md) + [Bitbucket 應用程式密碼或存取權杖](access-tokens-bitbucket.md) + [Bitbucket OAuth 應用程式](oauth-app-bitbucket.md) # Bitbucket 應用程式連線 您可以使用 Bitbucket 與 CodeBuild 連線。透過 支援 Bitbucket 應用程式連線[AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html)。 **注意** CodeConnections 可在比 CodeBuild 更少的區域中使用。您可以在 CodeBuild 中使用跨區域連線。在選擇加入區域中建立的連線無法在其他區域中使用。如需詳細資訊，請參閱 [AWS CodeConnections 端點和配額](https://docs.aws.amazon.com/general/latest/gr/codestar_connections.html)。 **Topics** + [步驟 1：建立與 Bitbucket 的連線 （主控台）](#connections-bitbucket-console) + [步驟 2：授予 CodeBuild 專案 IAM 角色存取權以使用連線](#connections-bitbucket-role-access) + [步驟 3：設定 CodeBuild 以使用新的連線](#connections-bitbucket-account-credential) ## 步驟 1：建立與 Bitbucket 的連線 （主控台） 使用這些步驟來使用 CodeBuild 主控台為 Bitbucket 中的專案新增連線。 **建立連至 Bitbucket 的連線** + 請遵循*開發人員工具使用者指南*中[建立 Bitbucket 連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-bitbucket.html)的說明。 **注意** 您可以使用從另一個帳戶共用的連線，而不是在帳戶中建立或使用現有的連線 AWS 。如需詳細資訊，請參閱[與 AWS 帳戶共用連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html)。 ## 步驟 2：授予 CodeBuild 專案 IAM 角色存取權以使用連線 您可以授予 CodeBuild 專案 IAM 角色存取權，以使用連線提供的 Bitbucket 權杖。 **授予 CodeBuild 專案 IAM 角色存取權** 1. 遵循 CodeBuild 專案的 指示，為您的 CodeBuild 專案建立 [允許 CodeBuild 與其他 AWS 服務互動](setting-up-service-role.md) IAM 角色。 1. 遵循指示時，將下列 IAM 政策新增至 CodeBuild 專案角色，以授予連線的存取權。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [ "arn:aws:iam::*:role/Service*" ] } ] } ``` ------ ## 步驟 3：設定 CodeBuild 以使用新的連線 您可以將連線設定為帳戶層級登入資料，並在專案中使用它。 ------ #### [ AWS 管理主控台 ] **若要在 中將連線設定為帳戶層級登入資料 AWS 管理主控台** 1. 對於 **Source provider (來源供應商)**，選擇 **Bitbucket**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇**預設來源登入**資料，以使用您帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 Bitbucket，請選擇**管理預設來源憑證**。 1. 針對**登入資料類型**，選擇 **CodeConnections**。 1. 在**連線**中，選擇使用現有的連線或建立新的連線。 + 選擇**自訂來源登入**資料，以使用自訂來源登入資料覆寫您帳戶的預設設定。 1. 針對**登入資料類型**，選擇 **CodeConnections**。 1. 在**連線**中，選擇使用現有的連線或建立新的連線。 ------ #### [ AWS CLI ] **若要在 中將連線設定為帳戶層級登入資料 AWS CLI** + 開啟終端機 (Linux、macOS 或 Unix) 或命令提示 (Windows)。使用 AWS CLI 執行 **import-source-credentials**命令，`--token`為您的連線指定 `--auth-type`、 `--server-type`和 。 使用下列命令： ``` aws codebuild import-source-credentials --auth-type CODECONNECTIONS --server-type BITBUCKET --token ``` ------ 如需在 CodeBuild 專案中設定多個字符的詳細資訊，請參閱 [將多個字符設定為來源層級登入資料](multiple-access-tokens.md#asm-source-credential)。 # Bitbucket 應用程式密碼或存取權杖 ## 先決條件 開始之前，您必須將適當的許可範圍新增至 Bitbucket 應用程式密碼或存取權杖。 對於 Bitbucket，您的應用程式密碼或存取權杖必須具有下列範圍。 + **repository:read**：授予獲授權使用者可存取的所有儲存庫之讀取存取權。 + **pullrequest:read**：授予提取請求的讀取存取權。如果您的專案具有 Bitbucket Webhook，則您的應用程式密碼或存取權杖必須具有此範圍。 + **webhook**：授予 Webhook 的存取權。如果您的專案具有 Webhook 操作，則您的應用程式密碼或存取權杖必須具有此範圍。 + **帳戶**：授予使用者帳戶資訊的讀取存取權。 如需詳細資訊，請參閱 Bitbucket 網站上的 [Bitbucket Cloud REST API 的範圍](https://developer.atlassian.com/cloud/bitbucket/bitbucket-cloud-rest-api-scopes/)和 [Bitbucket Cloud 上的 OAuth](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html)。 ## 使用應用程式密碼連接 Bitbucket （主控台） 若要使用主控台，使用應用程式密碼將專案連線至 Bitbucket，請在建立專案時執行下列動作。如需相關資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 1. 對於 **Source provider (來源供應商)**，選擇 **Bitbucket**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇使用帳戶登入資料，將帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 Bitbucket，請選擇**管理帳戶登入**資料。 1. 針對**登入資料類型**，選擇**應用程式密碼**。 + 如果您選擇使用 **Service** 的帳戶層級登入資料，請選擇您要用來存放字符的服務，並執行下列動作： 1. 如果您選擇使用 **Secrets Manager**，您可以選擇使用現有的秘密連線或建立新的秘密，然後選擇**儲存**。如需如何建立新的秘密的詳細資訊，請參閱 [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md)。 1. 如果您選擇使用 **CodeBuild**，請輸入您的 Bitbucket 使用者名稱和密碼，然後選擇**儲存**。 + 選取**僅使用此專案的覆寫登入**資料來使用自訂來源登入資料來覆寫帳戶的登入資料設定。 1. 從填入的登入資料清單中，選擇**應用程式密碼**下的其中一個選項。 1. 您也可以在描述中選取建立新的應用程式密碼**連線，以建立新的應用程式密碼**字符。 ## 使用存取字符連接 Bitbucket （主控台） 若要使用 主控台，使用存取字符將專案連線至 Bitbucket，請在建立專案時執行下列動作。如需相關資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 1. 對於 **Source provider (來源供應商)**，選擇 **Bitbucket**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇使用帳戶登入資料，將帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 Bitbucket，請選擇**管理帳戶登入**資料。 1. 針對**登入資料類型**，選擇**個人存取字符**。 + 如果您選擇使用 **Service** 的帳戶層級登入資料，請選擇您要用來存放字符的服務，並執行下列動作： 1. 如果您選擇使用 **Secrets Manager**，您可以選擇使用現有的秘密連線或建立新的秘密，然後選擇**儲存**。如需如何建立新的秘密的詳細資訊，請參閱 [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md)。 1. 如果您選擇使用 **CodeBuild**，請輸入您的 Bitbucket 個人存取字符，然後選擇**儲存**。 + 選取**僅使用此專案的覆寫登入**資料來使用自訂來源登入資料來覆寫帳戶的登入資料設定。 1. 從填入的登入資料清單中，選擇**個人存取字符**下的其中一個選項。 1. 您也可以在描述中選取建立新的個人存取權杖**連線，以建立新的個人存取權杖**。 ## 使用應用程式密碼或存取權杖 (CLI) 連接 Bitbucket 請依照下列步驟使用 AWS CLI ，使用應用程式密碼或存取權杖將您的專案連線至 Bitbucket。如需 AWS CLI 搭配 使用 的詳細資訊 AWS CodeBuild，請參閱 [命令列參考](cmd-ref.md)。 1. 執行 **import-source-credentials** 命令： ``` aws codebuild import-source-credentials --generate-cli-skeleton ``` 即會在輸出中顯示 JSON 格式化資料。將資料複製到 AWS CLI 安裝 的本機電腦或執行個體位置中的檔案 （例如 `import-source-credentials.json`)。如下所示修改複製的資料，並儲存您的結果。 ``` { "serverType": "BITBUCKET", "authType": "auth-type", "shouldOverwrite": "should-overwrite", "token": "token", "username": "username" } ``` 取代以下項目： + *server-type*：必要值。用於此登入資料的來源供應商。有效值為 GITHUB、BITBUCKET、GITHUB\$1ENTERPRISE、GITLAB 和 GITLAB\$1SELF\$1MANAGED。 + *auth-type*：必要值。用於連線至儲存庫的身分驗證類型。有效值為 OAUTH、BASIC\$1AUTH、Personal\$1ACCESS\$1TOKEN、CODECONNECTIONS 和 SECRETS\$1MANAGER。對於 GitHub，僅允許使用 Personal\$1ACCESS\$1TOKEN。BASIC\$1AUTH 僅允許使用 Bitbucket 應用程式密碼。 + *should-overwrite*：選用值。設為 `false` 可防止覆寫儲存庫來源登入資料。設為 `true` 可覆寫儲存庫來源登入資料。預設值為 `true`。 + *token*：必要值。對於 GitHub 或 GitHub Enterprise Server，這是個人存取字符。對於 Bitbucket，這是個人存取字符或應用程式密碼。對於身分驗證類型 CODECONNECTIONS，這是連線 ARN。對於身分驗證類型 SECRETS\$1MANAGER，這是秘密 ARN。 + *username*：選用值。GitHub 和 GitHub Enterprise Server 來源提供者會忽略此參數。 1. 若要使用應用程式密碼或存取字符來連接您的帳戶，請切換到包含您在步驟 1 中儲存之`import-source-credentials.json`檔案的目錄，然後再次執行 **import-source-credentials**命令。 ``` aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json ``` JSON 格式的資料會出現在 Amazon Resource Name (ARN) 的輸出中。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` **注意** 如果您使用相同的伺服器類型和身分驗證類型執行 **import-source-credentials** 命令第二次，即會更新存放的存取字符。 您的帳戶與應用程式密碼連線後，您可以使用 `create-project` 來建立 CodeBuild 專案。如需詳細資訊，請參閱[建立建置專案 (AWS CLI)](create-project.md#create-project-cli)。 1. 若要檢視連線的應用程式密碼或存取權杖，請執行 **list-source-credentials**命令。 ``` aws codebuild list-source-credentials ``` 輸出中即會顯示 JSON 格式的 `sourceCredentialsInfos` 物件： ``` { "sourceCredentialsInfos": [ { "authType": "auth-type", "serverType": "BITBUCKET", "arn": "arn" } ] } ``` `sourceCredentialsObject` 包含連接的來源登入資料資訊的清單： + `authType` 是登入資料使用的身分驗證類型。這可以是 `OAUTH`、`BASIC_AUTH`、`CODECONNECTIONS`、 `PERSONAL_ACCESS_TOKEN`或 `SECRETS_MANAGER`。 + `serverType` 是來源供應商的類型。這可以是 `GITHUB`、`GITHUB_ENTERPRISE`、`GITLAB`、 `BITBUCKET`或 `GITLAB_SELF_MANAGED`。 + `arn` 為字符的 ARN。 1. 若要中斷與來源提供者的連線並移除其應用程式密碼或存取權杖，請使用其 ARN 執行 **delete-source-credentials**命令。 ``` aws codebuild delete-source-credentials --arn arn-of-your-credentials ``` JSON 格式的資料會隨著所刪除登入資料的 ARN 傳回。 ``` { "arn": "arn:aws:codebuild:region:account-id:token/server-type" } ``` # Bitbucket OAuth 應用程式 ## 使用 OAuth 連接 Bitbucket （主控台） 若要使用 主控台，使用 OAuth 應用程式將專案連線至 Bitbucket，請在建立專案時執行下列動作。如需相關資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 1. 對於 **Source provider (來源供應商)**，選擇 **Bitbucket**。 1. 對於**登入**資料，請執行下列其中一項操作： + 選擇使用帳戶登入資料，將帳戶的預設來源登入資料套用至所有專案。 1. 如果您未連線至 Bitbucket，請選擇**管理帳戶登入**資料。 1. 針對**登入資料類型**，選擇 **OAuth 應用程式**。 + 如果您選擇使用 **Service** 的帳戶層級登入資料，請選擇您要用來存放字符的服務，並執行下列動作： 1. 如果您選擇使用 **Secrets Manager**，您可以選擇使用現有的秘密連線或建立新的秘密，然後選擇**儲存**。如需如何建立新的秘密的詳細資訊，請參閱 [在 Secrets Manager 秘密中建立和存放權杖](asm-create-secret.md)。 1. 如果您選擇使用 **CodeBuild**，然後選擇**儲存**。 + 選取**僅使用此專案的覆寫登入**資料來使用自訂來源登入資料來覆寫帳戶的登入資料設定。 1. 從填入的登入資料清單中，選擇 **OAuth 應用程式**下的其中一個選項。 1. 您也可以在描述中選取建立新的 Oauth 應用程式字符連線，以建立新的 OAuth 應用程式字符。 **** 若要檢閱授權的 OAuth 應用程式，請導覽至 Bitbucket [上的應用程式授權](https://bitbucket.org/account/settings/app-authorizations/)，並確認`AWS CodeBuild (region)`已列出名為 的應用程式。 # CodeBuild 中的 GitLab 存取 對於 GitLab，您可以使用 GitLab 連線來存取來源提供者。 **Topics** + [將 CodeBuild 連接至 GitLab](#connections-gitlab) ## 將 CodeBuild 連接至 GitLab 連線可讓您使用 授權和建立組態，將第三方供應商與您的 AWS 資源建立關聯 AWS CodeConnections。若要將第三方儲存庫關聯為建置專案的來源，請使用 連線。 若要在 CodeBuild 中新增 GitLab 或 GitLab 自我管理來源提供者，您可以選擇： + 使用 CodeBuild 主控台**建立建置專案**精靈或**編輯來源**頁面，選擇 **GitLab** 或 **GitLab 自我管理**提供者選項。請參閱 [建立連至 GitLab 的連線 (主控台)](#connections-gitlab-console) 以新增來源提供者。主控台可協助您建立連線資源。 + 使用 CLI 建立連線資源，請參閱[建立連至 GitLab 的連線 (CLI)](#connections-gitlab-cli)使用 CLI 建立連線資源。 **注意** 您也可以使用**設定**下的開發人員工具主控台建立連線。請參閱[建立連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create.html)。 **注意** 在 GitLab 中授權此連線安裝，即表示您授予我們的服務透過存取您的帳戶處理您的資料的許可，您隨時可以解除安裝應用程式以撤銷許可。 ### 建立連至 GitLab 的連線 本節說明如何將 GitLab 連線至 CodeBuild。如需 GitLab 連線的詳細資訊，請參閱 [將 CodeBuild 連接至 GitLab](#connections-gitlab)。 開始之前： + 您必須已在 GitLab 建立帳戶。 **注意** 連線只能存取用於建立和授權連線之帳戶擁有的儲存庫。 **注意** 您可以建立與 GitLab 中擁有**擁有者**角色之儲存庫的連線，然後該連線可與具有 CodeBuild 等資源的儲存庫搭配使用。如果是群組中的儲存庫，您不需要為群組擁有者。 + 若要指定建置專案的來源，您必須已在 GitLab 上建立儲存庫。 **Topics** + [建立連至 GitLab 的連線 (主控台)](#connections-gitlab-console) + [建立連至 GitLab 的連線 (CLI)](#connections-gitlab-cli) #### 建立連至 GitLab 的連線 (主控台) 使用這些步驟來使用 CodeBuild 主控台，在 GitLab 中為您的專案 （儲存庫） 新增連線。 **注意** 您可以使用從另一個帳戶共用的連線，而不是在帳戶中建立或使用現有的連線 AWS 。如需詳細資訊，請參閱[與 AWS 帳戶共用連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html)。 **建立或編輯您的建置專案** 1. 登入 CodeBuild 主控台。 1. 選擇下列其中一項。 + 選擇 以建立建置專案。依照 中的步驟[建立組建專案 (主控台)](create-project.md#create-project-console)完成第一個畫面，然後在**來源****提供者下的來源**區段中，選擇 **GitLab**。 + 選擇 以編輯現有的建置專案。選擇**編輯**，然後選擇**來源**。在**編輯來源**頁面的**來源提供者**下，選擇 **GitLab**。 1. 選擇下列其中一項： + 在**連線**下，選擇**預設連線**。預設連線會將預設 GitLab 連線套用至所有專案。 + 在**連線**下，選擇**自訂連線**。自訂連線會套用自訂 GitLab 連線，覆寫您帳戶的預設設定。 1. 執行以下任意一項： + 在**預設連線**或**自訂連線**下，如果您尚未建立與提供者的連線，請選擇**建立新的 GitLab 連線**。繼續進行步驟 5 以建立連線。 + 在**連線**下，如果您已建立與供應商的連線，請選擇連線。繼續進行步驟 10。 **注意** 如果您在建立 GitLab 連線之前關閉快顯視窗，則需要重新整理頁面。 1. 若要建立連至 GitLab 儲存庫的連線，請在**選取供應商**底下選擇 **GitLab**。在 **Connection name (連線名稱)** 底下，輸入您要建立的連線名稱。選擇**連線至 GitLab**。 ![\[主控台螢幕擷取畫面中顯示針對 GitLab 選擇的連線選項。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/connections-create-gitlab.png) 1. 當 GitLab 的登入頁面顯示時，使用您的登入資料登入，然後選擇**登入**。 1. 如果這是您第一次授權連線，則會顯示授權頁面，其中包含請求連線授權以存取 GitLab 帳戶的訊息。 選擇 **Authorize** (授權)。 ![\[螢幕擷取畫面中顯示授權您的 GitLab 帳戶連線的訊息。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/gitlab-authorization.png) 1. 瀏覽器會返回連線主控台頁面。在 **GitLab 連線設定**下，新的連線會顯示在**連線名稱**中。 1. 選擇**連線**。 成功建立 GitLab 連線後，頂端會顯示成功橫幅。 1. 在**建立建置專案**頁面**的預設連線**或**自訂連線**下拉式清單中，確定已列出您的連線 ARN。如果沒有，請選擇重新整理按鈕使其出現。 1. 在**儲存庫**中，使用 命名空間指定專案路徑，以選擇 GitLab 中的專案名稱。例如，針對群組層級儲存庫，以下列格式輸入儲存庫名稱：`group-name/repository-name`。如需路徑和命名空間的詳細資訊，請參閱 https：//[https://docs.gitlab.com/ee/api/projects.html\$1get-single-project](https://docs.gitlab.com/ee/api/projects.html#get-single-project) 中的 `path_with_namespace` 欄位。如需 GitLab 中命名空間的詳細資訊，請參閱 https：//[https://docs.gitlab.com/ee/user/namespace/](https://docs.gitlab.com/ee/user/namespace/)。 **注意** 對於 GitLab 中的群組，您必須使用 命名空間手動指定專案路徑。例如，針對群組 `myrepo`中名為 的儲存庫`mygroup`，輸入下列項目：`mygroup/myrepo`。您可以在 GitLab 的 URL 中找到具有 命名空間的專案路徑。 1. 在**來源版本 - 選用**中，輸入提取請求 ID、分支、遞交 ID、標籤或參考和遞交 ID。如需詳細資訊，請參閱[使用 的來源版本範例 AWS CodeBuild](sample-source-version.md)。 **注意** 我們建議您選擇看起來不像遞交 IDs的 Git 分支名稱，例如 `811dd1ba1aba14473856cee38308caed7190c0d`或 `5392f7`。這可協助您避免 Git 結帳與實際遞交的衝突。 1. 在 **Git 複製深度 - 選用**中，您可以使用截斷至指定遞交數量的歷史記錄來建立淺複製。如果您想要完整複製，請選擇 **Full (完整)**。 1. 在**建置狀態 - 選用**中，如果您希望**向來源提供者回報建置的開始和完成狀態，請選取在建置開始和完成時**向來源提供者報告建置狀態。 若要能夠向來源提供者報告建置狀態，與來源提供者相關聯的使用者必須具有儲存庫的寫入存取權。如果使用者沒有寫入存取權，則無法更新建置狀態。如需詳細資訊，請參閱[來源提供者存取](access-tokens.md)。 #### 建立連至 GitLab 的連線 (CLI) 您可以使用 AWS Command Line Interface (AWS CLI) 來建立連線。 若要這麼做，請使用 **create-connection** 命令。 **重要** 根據預設，透過 AWS CLI 或 建立的連線 AWS CloudFormation 處於 `PENDING` 狀態。建立與 CLI 或 的連線後 CloudFormation，請使用 主控台來編輯連線，使其成為狀態 `AVAILABLE`。 **建立連線** + 請遵循*開發人員工具主控台使用者指南*中[建立 GitLab (CLI) 連線](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gitlab.html#connections-create-gitlab-cli)的說明。