本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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)。