如何在 Code Stream 中使用 Git 觸發器執行管線

身為 Code Stream 管理員或開發人員，您可以使用 Git 觸發器將 Code Stream 與 Git 生命週期整合。當您在 GitHub、GitLab 或 Bitbucket Enterprise 中進行代碼變更時，事件會透過 Webhook 與 Code Stream 進行通訊並觸發管線。當 Cloud Assembly 和企業版本在同一個網路上可以連線時，Webhook 則適用於 GitLab、GitHub 和 Bitbucket 內部部署企業版本。

在 Code Stream 中新增 Git 的 webhook 時，它還會在 GitHub、GitLab 或 Bitbucket 存放庫中建立 webhook。如果稍後更新或刪除 Webhook，該動作也會更新或刪除 GitHub、GitLab 或 Bitbucket 中的 Webhook。

Webhook 定義必須包含將要監控的存放庫的分支上的 Git 端點。若要建立 Webhook， Code Stream 會使用 Git 端點。如果不存在端點，您可以在新增 webhook 時建立端點。此範例假設在 GitHub 中您有預先定義的 Git 端點。

備註：若要建立 Webhook，Git 端點必須使用私人 Token 進行驗證，不能使用密碼。

透過使用相同的 Git 端點並在 Webhook 組態頁面中為分支名稱提供不同的值，可以為不同的分支建立多個 Webhook。若要為相同 Git 存放庫中的其他分支建立其他 Webhook，無需針對多個分支複製 Git 端點多次。而是在 Webhook 中提供分支名稱，以便重複使用 Git 端點。如果 Git Webhook 中的分支與端點中的分支相同，則無需在 Git Webhook 頁面中提供分支名稱。

此範例顯示如何將 Git 觸發器與 GitHub 存放庫搭配使用，但必要條件包括使用另一個 Git 伺服器類型時所需的準備工作。

必要條件

確認您是 Code Stream 中的專案的成員。如果您不是管理員，請要求 Code Stream 管理員將您新增為專案成員。請參閱如何在 Code Stream 中新增專案。
確認要監控的 GitHub 分支上存在 Git 端點。請參閱如何整合 Code Stream 與 Git。
確認您具有在 Git 存放庫中建立 webhook 的權限。
如果在 GitLab 中設定 Webhook，請在 GitLab Enterprise 中變更預設網路設定，以啟用輸出請求並允許建立本機 Webhook。
備註：僅 GitLab Enterprise 需要進行此變更。這些設定不適用於 GitHub 或 Bitbucket。
1. 以管理員身分登入 GitLab Enterprise 執行個體。
2. 使用 URL (例如，http://{gitlab-server}/admin/application_settings/network) 移至網路設定。
3. 展開輸出請求，然後按一下：
  - 允許從 Web hook 和服務向本機網路發出請求。
  - 允許從系統 hook 向本機網路發出請求。
對於您想要觸發的管線，確認您已將輸入內容設定為在管線執行時插入 Git 參數。
如需輸入參數的相關資訊，請參閱手動新增工作前在 Code Stream 中規劃 CICD 原生建置。

程序

在 Code Stream 中，按一下觸發器 > Git。
依序按一下適用於 Git 的 Webhook 索引標籤和新增適用於 Git 的 Webhook。
1. 選取專案。
2. 為 webhook 輸入有意義的名稱和說明。
3. 選取針對要監控的分支設定的 Git 端點。
  當您建立 webhook 時，webhook 定義將包含目前端點詳細資料。
  - 如果稍後在端點中變更 Git 類型、Git 伺服器類型或 Git 存放庫 URL，則 webhook 將無法再觸發管線，因為它會嘗試使用原始端點詳細資料存取 Git 存放庫。您必須刪除 webhook，然後再次建立包含該端點的 webhook。
  - 如果您稍後在端點中變更驗證類型、使用者名稱或私人 Token，則 webhook 將繼續運作。
  - 如果使用的是 BitBucket 存放庫，則存放庫的 URL 必須採用以下格式之一：https://api.bitbucket.org/{user}/{repo name} 或 http(s)://{bitbucket-enterprise-server}/rest/api/1.0/users/{username}/repos/{repo name}。
  備註：如果先前建立的 webhook 使用的 Git 端點是使用密碼進行基本驗證，則您必須將其刪除並透過使用私人 Token 進行驗證的 Git 端點重新定義 webhook。
  請參閱如何整合 Code Stream 與 Git。
4. (選擇性) 輸入您想讓 webhook 監控的分支。
  如果未指定分支，則 Webhook 會監控為 Git 端點設定的分支。
5. (選擇性) 為 webhook 產生密碼 Token。
  如果使用密碼 Token， Code Stream 將為 Webhook 產生隨機字串 Token。然後，當 Webhook 收到 Git 事件資料時，它會使用密碼 Token 傳送資料。 Code Stream 會使用資訊來判定呼叫是否來自預期來源，例如設定的 GitHub 執行個體、存放庫和分支。密碼 Token 提供一層額外的安全性，用來確認 Git 事件資料來自於正確的來源。
6. (選擇性) 提供檔案包含或排除做為觸發器的條件。
  - 檔案包含。如果認可中的任何檔案與包含路徑或 Regex 中指定的檔案相符，則認可將觸發管線。透過指定規則運算式， Code Stream 僅在變更集中的檔案名稱與提供的運算式相符時觸發管線。為單一存放庫中的多個管線設定觸發器時，規則運算式篩選器很有用。
  - 檔案排除。如果認可中的所有檔案與排除路徑或 Regex 中指定的檔案相符，則不會觸發管線。
  - 排除優先。開啟 [排除優先] 時，可確保即使認可中的任何檔案與排除路徑或 Regex 中指定的檔案相符，也不會觸發管線。預設設定為關閉。
  如果條件同時滿足檔案包含和檔案排除，則管線不會觸發。
  在下列範例中，檔案包含和檔案排除都是觸發器的條件。
  - 對於檔案包含，認可對 runtime/src/main/a.java 或任何 Java 檔案的任何變更都將觸發事件組態中設定的管線。
  - 對於檔案排除，僅認可這兩個檔案中的變更不會觸發事件組態中設定的管線。
7. 對於 Git 事件，選取推送或提取請求。
8. 輸入 API Token。
  CSP API Token 會向您驗證與 Code Stream 的外部 API 連線。取得 API Token：
  1. 按一下產生 Token。
  2. 輸入與使用者名稱和密碼相關聯的電子郵件地址，然後按一下產生。
    您產生的 Token 有效期為六個月。它也稱為重新整理 Token。
    
    若要將 Token 保留為變數供日後使用，請按一下建立變數，輸入變數的名稱，然後按一下儲存。
    
    若要將 Token 保留為文字值供日後使用，請按一下複製，然後將 Token 貼到文字檔中以在本機儲存。
    
    您可以選擇建立變數並將 Token 儲存在文字檔中，以供日後使用。
  3. 按一下關閉。
9. 選取 webhook 要觸發的管線。
  如果管線包括自訂新增的輸入參數，[輸入參數] 清單會顯示參數和值。您可以輸入透過觸發事件傳遞到管線的輸入參數的值。或者，您可以將這些值保留空白，或使用預設值 (如果已定義)。
  如需 Git 觸發器的自動插入輸入參數的相關資訊，請參閱必要條件。
10. 按一下建立。
  webhook 會顯示為新卡。
按一下 Webhook 卡。
重新顯示 Webhook 資料表單時，您會看到 Webhook URL 已新增至表單的頂端。Git Webhook 透過該 Webhook URL 連線至 GitHub 存放庫。
在新的瀏覽器視窗中，開啟透過 Webhook 連線的 GitHub 存放庫。
1. 若要查看在 Code Stream 中新增的 Webhook，請按一下設定索引標籤，然後選取 Webhook。
  在 Webhook 清單的底端，您會看到相同的 Webhook URL。
2. 若要變更代碼，請按一下代碼索引標籤，然後在分支上選取檔案。編輯檔案後，請認可變更。
3. 若要確認 Webhook URL 是否正在工作，請按一下設定索引標籤，然後再次選取 Webhook。
  在 Webhook 清單的底端，Webhook URL 旁會顯示一個綠色打勾標記。
返回至 Code Stream 以檢視 Git Webhook 上的活動。按一下觸發器 > Git > 活動。
在執行狀態下，確認管線執行已啟動。
按一下執行，並在管線執行時追蹤管線。
若要觀察管線執行，可以按 [重新整理]。

結果

恭喜您！您已成功使用適用於 Git 的觸發器！