本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 連接 GitHub
<a name="connecting-to-cicd-pipelines-connecting-github"></a>

GitHub 整合可讓 AWS DevOps 代理程式在事件調查期間存取程式碼儲存庫並接收部署事件。此整合遵循兩個步驟：GitHub 的帳戶層級註冊，接著將特定儲存庫連線至個別的 Agent Spaces。

AWS DevOps Agent 支援 GitHub.com (SaaS)、具有資料駐留 (`*.ghe.com`) 的 GitHub Enterprise Cloud 和 GitHub Enterprise Server （自我託管） 執行個體。

## 先決條件
<a name="prerequisites"></a>

連接 GitHub 之前，請確定您已：
+ 存取 AWS DevOps Agent 管理員主控台
+ 具有管理員許可的 GitHub 使用者帳戶或組織
+ 在您的帳戶或組織中安裝 GitHub 應用程式的授權

對於 GitHub Enterprise Server，您也需要：
+ 透過 HTTPS 存取的 GitHub Enterprise Server 執行個體 (3.x 版或更新版本）
+ GitHub Enterprise Server 執行個體的 HTTPS URL （例如 `https://github.example.com`)
+ （選用） 如果您的 GitHub Enterprise Server 執行個體無法公開存取，則為私有連線

對於具有資料駐留的 GitHub Enterprise Cloud，您也需要：
+ 啟用資料駐留的 GitHub Enterprise Cloud 組織，託管在您的專用`*.ghe.com`子網域上
+ 組織管理員許可，包括建立和安裝 GitHub 應用程式的許可
+ 資料駐留執行個體的 HTTPS URL （例如 `https://octocorp.ghe.com`)

## 註冊 GitHub （帳戶層級）
<a name="registering-github-account-level"></a>

GitHub 已在 AWS 帳戶層級註冊，並在該帳戶中的所有客服人員空間之間共用。每個註冊對應至一個 GitHub 使用者、一個組織或一個 GitHub Enterprise Server 執行個體。

### 步驟 1：導覽至管道供應商
<a name="step-1-navigate-to-pipeline-providers"></a>

1. 登入 AWS 管理主控台

1. 導覽至 AWS DevOps 代理程式主控台

1. 前往**功能**索引標籤

1. 在**管道**區段中，選擇**新增**

1. 從可用提供者清單中選取 **GitHub** 

如果 GitHub 尚未註冊，系統會提示您先註冊。

### 步驟 2：選擇連線類型
<a name="step-2-choose-connection-type"></a>

在「註冊 GitHub 帳戶/組織」畫面上，選取您是以使用者或組織身分連線：
+ **使用者** – 具有使用者名稱和設定檔的個人 GitHub 帳戶
+ **組織** – 共用的 GitHub 帳戶，其中多個人員可以一次跨多個專案進行協作。如果您選取**組織**，請輸入 GitHub 組織名稱。名稱必須與 GitHub 組織名稱完全相符，因為您必須在下列步驟中授權該組織並安裝應用程式。

選取 **GitHub 應用程式的 GitHub 應用程式許可**。 GitHub 許可層級決定 GitHub 應用程式可在您的儲存庫中執行的動作：
+ **讀取和寫入** （預設）：GitHub 應用程式會同時請求讀取和寫入許可。這會啟用所有功能。DevOps 代理程式可以發佈內嵌提取請求評論、提議修正和觸發工作流程。
+ **唯讀**：GitHub 應用程式僅請求讀取許可。DevOps 代理程式可以檢視程式碼和提取請求，但無法發佈評論、提議修正或觸發工作流程。

如果您要連線至 GitHub Enterprise Server 執行個體，請選擇**使用 GitHub Enterprise**，然後輸入執行個體的 HTTPS URL （例如 `https://github.example.com`)。

如果您的 GitHub Enterprise Server 執行個體無法公開存取，您可以選擇設定私有連線，以允許 AWS DevOps 代理程式安全地連線到您的執行個體。如需詳細資訊，請參閱[連線至私有託管工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。

**注意**  
** 請勿在 URL 中包含 `/api/v3`或任何結尾路徑 — 請僅輸入基本 URL。

對於具有資料駐留的 GitHub Enterprise Cloud，選擇**使用 GitHub Enterprise**，然後輸入資料駐留執行個體的 HTTPS URL （例如 `https://octocorp.ghe.com`)。

### 步驟 3：設定 GitHub 應用程式
<a name="step-3-set-up-the-github-app"></a>

選擇**提交**以開始應用程式設定程序。後續步驟會因您是否使用資料駐留連線至 GitHub.com,、GitHub Enterprise Server 或 GitHub Enterprise Cloud 而有所不同。

#### 對於 GitHub.com
<a name="for-githubcom"></a>

1. GitHub 會將您重新導向至登入並授權 AWS DevOps 代理程式。

1. 檢閱授權請求並授權 AWS DevOps 代理程式。

1. 在您授權之後， AWS DevOps 代理程式會完成註冊。如果您指定的帳戶或組織尚未安裝 GitHub 應用程式，請繼續前往安裝頁面 （請參閱步驟 4)。如果應用程式已安裝，註冊會完成，而無需重新安裝。

1. 安裝後， AWS DevOps 代理程式會從連線的儲存庫接收事件，包括部署事件。

**注意**  
** 您必須在註冊期間指定的相同使用者或組織上授權並安裝應用程式。如果您在不同的帳戶或組織上授權或安裝 ，註冊會失敗，您必須重新啟動程序，選取正確的帳戶或組織。

**注意**  
** AWS DevOps 代理程式會針對每個許可層級 （讀取、寫入和唯讀） 使用個別的 GitHub 應用程式，而且每個應用程式都會獨立授權。GitHub 會記住授權，直到您在設定 > 應用程式 > 授權的 GitHub 應用程式下將其撤銷為止。如果您先前已在此許可層級授權應用程式，GitHub 可能會略過授權畫面。如果您變更許可層級，GitHub 會提示您第一次授權對應的應用程式。

#### 對於具有資料駐留的 GitHub Enterprise Server 和 GitHub Enterprise Cloud
<a name="for-github-enterprise-server-and-github-enterprise-cloud-with-data-residency"></a>

具有資料駐留的 GitHub Enterprise Server 和 GitHub Enterprise Cloud 都使用 GitHub 應用程式資訊清單流程，其會自動在您的執行個體上設定新的 GitHub 應用程式。在設定期間，您的瀏覽器會重新導向兩次：一次到執行個體，一次回到 AWS DevOps 代理程式。

1. AWS DevOps 代理程式會將您的瀏覽器重新導向至 GitHub Enterprise 執行個體的**建立 GitHub 應用程式**頁面。

1. 應用程式名稱已預先填入。視需要變更名稱，然後選擇**建立 GitHub 應用程式**。

1. After AWS DevOps 代理程式會將您的瀏覽器重新導向回去，它會交換資訊清單程式碼以取得應用程式登入資料。

### 步驟 4：選取儲存庫並完成安裝
<a name="step-4-select-repositories-and-complete-installation"></a>

如果您的 帳戶或組織已安裝 GitHub 應用程式，請略過此步驟。

1. 隨即顯示 GitHub 應用程式的**安裝與授權**頁面。

1. 選取要允許應用程式存取的儲存庫：
   + **所有儲存庫** – 授予所有目前和未來儲存庫的存取權
   + **僅選取儲存庫** – 從您的帳戶或組織選擇特定儲存庫

1. 選擇**安裝和授權**。

1. 系統會將您重新導向回 AWS DevOps 代理程式主控台，其中 GitHub 會在帳戶層級顯示為已註冊。

## 將儲存庫連線至 代理程式空間
<a name="connecting-repositories-to-an-agent-space"></a>

在帳戶層級註冊 GitHub 之後，您可以將特定儲存庫連線至個別客服人員空間：

1. 在 AWS DevOps 代理程式主控台中，選取您的代理程式空間

1. 前往**功能**索引標籤

1. 在**管道**區段中，選擇**新增**

1. 從可用提供者清單中選取 **GitHub** 

1. 選取包含您要使用之儲存庫的 GitHub 註冊

1. 選取與此客服人員空間相關的儲存庫子集

1. 選擇**新增**以完成連線

您可以根據您的組織需求，將不同的儲存庫集連接到不同的 Agent Spaces。單一客服人員空間可以使用來自多個註冊的儲存庫。若要從另一個註冊新增儲存庫，請重複這些步驟。

## 設定程式碼檢閱和自動化測試
<a name="configuring-code-review-and-automated-testing"></a>

當您在 GitHub 連線步驟中選取儲存庫時，儲存庫會自動新增至**程式碼檢閱和自動測試**區段。本節設定哪些儲存庫會自動觸發 [發行準備度程式碼檢閱](release-management-release-readiness-code-review.md)和自動化測試功能。

Code Review 和 Automated Testing 組態包括：
+ **功能** — 為每個儲存庫選擇程式碼檢閱和自動測試功能。本節提供兩個每個儲存庫的設定：
  + **自動觸發變更檢閱** — 為儲存庫啟用時，DevOps 代理程式[發行準備度程式碼檢閱](release-management-release-readiness-code-review.md)會在每次開啟或更新提取請求時自動執行 。檢閱問題清單會在提取請求上顯示為內嵌註解。根據預設，所有連線的儲存庫都會啟用此功能。
  + **自動化驗證測試** — 為儲存庫啟用時，DevOps 代理程式會在程式碼檢閱期間，在受管驗證環境中建置、執行和測試您的程式碼變更。這可提供靜態分析以外的功能驗證。如需詳細資訊，請參閱[自動化驗證測試](release-management-release-readiness-code-review.md)。根據預設，所有連線的儲存庫都會啟用此功能。
+ **儲存庫清單** — 顯示您在連線步驟期間選取的所有儲存庫。使用搜尋欄位依名稱篩選儲存庫。每個儲存庫都有兩個功能的獨立核取方塊。
+ **執行期角色** （選用） — 選擇 DevOps 代理程式擔任的 IAM 角色，以便在您選取的儲存庫上執行自動化功能。此角色用於存取建置期間所需的內部服務，例如私有套件登錄檔和成品儲存系統。我們建議您使用與主要客服人員角色不同的角色。

若要設定自動檢閱：

1. 連接儲存庫後，導覽至 GitHub 整合設定中的**程式碼檢閱和自動測試**區段。

1. 對於每個儲存庫，根據您是否要自動提取請求**檢閱，啟用或停用自動觸發變更**檢閱功能。

1. 對於每個儲存庫，根據您是否希望在受管**驗證**環境中[進行自動化驗證](release-management-release-readiness-code-review.md)測試，啟用或停用自動化驗證測試功能。

1. 或者，從**執行期角色下拉式清單中選取 IAM 角色，DevOps 代理程式會在您選取的儲存庫上執行自動化功能時擔任該角色**。 DevOps 

1. 選擇**儲存**以套用您的組態。

設定完成後，啟用**自動觸發變更檢閱**的儲存庫中任何新的提取請求都會自動觸發發行整備碼檢閱。如果也啟用**自動驗證測試**，則檢閱會在驗證環境中包含功能驗證。如需程式碼檢閱的詳細資訊，請參閱 [發行準備度程式碼檢閱](release-management-release-readiness-code-review.md)。

## 了解 GitHub 應用程式
<a name="understanding-the-github-app"></a>

The AWS DevOps Agent GitHub 應用程式：
+ 請求存取您的儲存庫 – 您可以在 GitHub 應用程式安裝期間檢閱特定許可
+ 接收部署事件和其他儲存庫事件
+ 允許 AWS DevOps 代理程式將程式碼變更與操作事件建立關聯
+ 您可以隨時透過 GitHub 設定解除安裝

對於具有資料駐留的 GitHub Enterprise Server 和 GitHub Enterprise Cloud， AWS DevOps 代理程式會在註冊期間自動在您的執行個體上建立 GitHub 應用程式。您可以透過**設定 > 應用程式 > 已安裝的 GitHub 應用程式**來管理應用程式的儲存庫存取權或將其解除安裝。若要完全刪除應用程式定義，請前往**設定 > 開發人員設定 > GitHub 應用程式**。

## GitHub 應用程式許可更新
<a name="github-app-permission-updates"></a>

在您安裝 GitHub 應用程式以支援新功能之後，AWS DevOps 代理程式可能會請求許可更新。發生這種情況時：

1. 您將從 GitHub 收到有關許可更新請求的通知。

1. 檢閱更新詳細資訊，以了解正在請求的新許可。

1. 選擇**接受新許可**以授予更新的許可。

您的服務或應用程式不需要變更。在您接受更新的許可後，下一個安裝存取權杖， AWS 即來自 GitHub 的 DevOps 代理程式請求會自動包含新的許可。 GitHub 

**注意**  
** 在您接受許可更新之前， AWS DevOps 代理程式會繼續使用先前授予的許可。在您核准請求之前，將無法使用依賴更新許可的新功能。如果您選擇不接受新的許可，應用程式會保留其目前的許可。

### 請求的許可
<a name="requested-permissions"></a>

下表說明 AWS DevOps 代理程式 GitHub 應用程式請求的每個許可，以及需要它的原因。

如果您在註冊期間選取**唯讀**，GitHub 應用程式只會針對下表中的每個許可請求讀取層級存取權。使用唯讀許可，GitHub 應用程式無法執行**目的**欄中列出的寫入層級動作。


| 權限 | 存取層級 | 用途 | 
| --- | --- | --- | 
| 檢查 | 讀取和寫入 | 當檢查在提取請求上執行時，發佈後整備性程式碼檢閱結果，允許檢閱狀態直接顯示在 GitHub UI 中。 | 
| 工作流程 | 讀取和寫入 | 讀取工作流程定義並觸發 GitHub 動作工作流程，以便在 CI/CD 管道中進行發行測試。 | 
| 動作 | 讀取和寫入 | 在事件調查和發行測試期間監控 GitHub Actions 工作流程執行和存取執行日誌。 | 
| 目錄 | 讀取和寫入 | 讀取儲存庫原始程式碼以進行程式碼檢閱分析和相依性映射。寫入存取可讓代理程式針對已識別的問題提出修正。 | 
| 提取請求 | 讀取和寫入 | 讀取提取請求詳細資訊以觸發自動程式碼檢閱。寫入存取權可讓您使用調查結果和建議的修正來張貼內嵌檢閱評論。 | 
| 組織管理 | 讀取 | 閱讀目標組織中安裝的應用程式清單，以確認已安裝 AWS DevOps Agent GitHub 應用程式。 | 

## 管理 GitHub 連線
<a name="managing-github-connections"></a>
+ **更新儲存庫存取** – 若要變更 GitHub 應用程式可存取的儲存庫，請前往您的 GitHub 帳戶或組織設定。對於具有資料駐留的 GitHub Enterprise Server 或 GitHub Enterprise Cloud，請前往您的執行個體設定。然後導覽至已安裝的 GitHub 應用程式，並修改 AWS DevOps Agent 應用程式組態。
+ **檢視連線的儲存庫** – 在 AWS DevOps 代理程式主控台中，選取您的代理程式空間，然後前往功能索引標籤，在管道區段中檢視連線的儲存庫。
+ **移除 GitHub 連線** – 若要中斷 GitHub 與客服人員空間的連線，請在管道區段中選擇連線，然後選擇**移除**。若要從您的帳戶移除 GitHub 註冊，請導覽至**功能提供者**頁面，在 **GitHub** 區段中尋找您的註冊，然後選擇**取消註冊**。

若要完全移除 GitHub 整合，請執行下列動作：
+ 若要解除安裝 GitHub 應用程式，請前往您的 GitHub 帳戶或組織設定。
+ 若要重新連線，請在 AWS DevOps Agent 主控台中重新註冊 GitHub。

對於具有資料駐留的 GitHub Enterprise Server 和 GitHub Enterprise Cloud， AWS DevOps 代理程式會在註冊期間在您的執行個體上建立 GitHub 應用程式。若要完全清除應用程式，請執行下列兩項操作：
+ **解除安裝應用程式** – 前往**設定 > 應用程式 > 安裝的 GitHub 應用程式**，選擇應用程式上的**設定**，然後解除安裝應用程式。
+ **刪除應用程式** – 前往**設定 > 開發人員設定 > GitHub 應用程式**、選擇應用程式、前往**進階**索引標籤，然後選擇**刪除 GitHub 應用程式**。**警告：**刪除 GitHub 應用程式是永久性的，無法復原。若要建立新的應用程式，請在 AWS DevOps Agent 主控台中重新註冊 GitHub。