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

身為 Code Stream 管理員或開發人員，您可以使用 Gerrit 觸發器將 Code Stream 與 Gerrit 代碼檢閱生命週期整合。當您在 Gerrit 專案上建立修補程式集、發佈草稿、合併程式碼變更或直接在 Git 分支上推送變更時，事件會觸發管線執行。

新增 Gerrit 觸發器時，請選取 Gerrit 接聽程式、Gerrit 伺服器上的 Gerrit 專案，並設定 Gerrit 事件。在 Gerrit 接聽程式定義中，選取 Gerrit 端點。如果需要在連線接聽程式後更新 Gerrit 端點，必須先中斷接聽程式的連線，然後再更新端點。

在此範例中，您先設定 Gerrit 接聽程式，然後在三個不同管線上有兩個事件的 Gerrit 觸發器中使用該接聽程式。

必要條件

確認您是 Code Stream 中的專案的成員。如果您不是管理員，請要求 Code Stream 管理員將您新增為專案成員。請參閱如何在 Code Stream 中新增專案。
確認您已在 Code Stream 中設定 Gerrit 端點。請參閱如何整合 Code Stream 與 Gerrit。
確認您知道 Gerrit 發行版本。
對於要觸發的管線，請確認已將管線的輸入內容設定為 Gerrit，這將允許管線在管線執行時將 Gerrit 參數作為輸入接收。
如需輸入參數的相關資訊，請參閱手動新增工作前在 Code Stream 中規劃 CICD 原生建置。

程序

在 Code Stream 中，按一下觸發器 > Gerrit。
(選擇性) 按一下接聽程式索引標籤，然後按一下新增接聽程式。

備註：如果已定義您打算用於 Gerrit 觸發器的 Gerrit 接聽程式，請略過此步驟。
1. 選取專案。
2. 輸入 Gerrit 接聽程式的名稱。
3. 選取 Gerrit 端點。
4. 輸入 API Token。
  CSP API Token 會向您驗證與 Code Stream 的外部 API 連線。取得 API Token：
  1. 按一下產生 Token。
  2. 輸入與使用者名稱和密碼相關聯的電子郵件地址，然後按一下產生。
    您產生的 Token 有效期為六個月。它也稱為重新整理 Token。
    
    若要將 Token 保留為變數供日後使用，請按一下建立變數，輸入變數的名稱，然後按一下儲存。
    
    若要將 Token 保留為文字值供日後使用，請按一下複製，然後將 Token 貼到文字檔中以在本機儲存。
    
    您可以選擇建立變數並將 Token 儲存在文字檔中，以供日後使用。
  3. 按一下關閉。
  如果您已建立變數，則 API Token 會顯示使用貨幣繫結輸入的變數名稱。如果您已複製 Token，則 API Token 會顯示已遮罩的 Token。
5. 若要驗證 Token 和端點詳細資料，請按一下驗證。
  您的 Token 將在 90 天後到期。
6. 按一下建立。
7. 在接聽程式卡上，按一下連線。
  接聽程式會開始監控 Gerrit 伺服器上的所有活動，並接聽該伺服器上任何已啟用的觸發器。若要停止接聽該伺服器上的觸發器，請停用觸發器。
  備註：若要更新連線到接聽程式的 Gerrit 端點，必須先中斷接聽程式的連線，然後再更新端點。
  - 按一下設定 > 觸發器 > Gerrit。
  - 按一下接聽程式索引標籤。
  - 在要更新且已連線到端點的接聽程式上按一下中斷連線。
按一下觸發器索引標籤，然後按一下新增觸發器。
選取 Gerrit 伺服器上的專案。
輸入名稱。
Gerrit 觸發器名稱必須是唯一的。
選取已設定的 Gerrit 接聽程式。
透過使用 Gerrit 接聽程式， Code Stream 會提供伺服器上可用的 Gerrit 專案的清單。
選取 Gerrit 伺服器上的專案。
輸入 Gerrit 接聽程式將監控的存放庫中的分支。
(選擇性) 提供檔案包含或排除做為觸發器的條件。
- 提供檔案包含以觸發管線。當 commit 中的任何檔案與包含路徑或 Regex 指定的檔案相符時，會觸發管線。指定 Regex 時， Code Stream 只會觸發變更集中檔案名稱與提供的運算式相符的管線。為單一存放庫中的多個管線設定觸發器時，規則運算式篩選器很有用。
- 提供檔案排除以使管線不會觸發。當 commit 中的所有檔案與排除路徑或 Regex 中指定的檔案相符時，管線不會觸發。
- 排除優先開啟時，可確保管線不會觸發。即使認可中的任何檔案與排除路徑或 Regex 中指定的檔案相符，管線也不會觸發。排除優先的預設設定已關閉。
如果條件同時滿足檔案包含和檔案排除，則管線不會觸發。
在下列範例中，檔案包含和檔案排除都是觸發器的條件。
- 對於檔案包含，認可對 runtime/src/main/a.java 或任何 Java 檔案的任何變更都將觸發事件組態中設定的管線。
- 對於檔案排除，僅認可這兩個檔案中的變更不會觸發事件組態中設定的管線。
按一下新增組態。
1. 對於 Gerrit 事件，選取已建立修補程式集、已發佈草稿或已合併變更。或者，若要繞過 Gerrit 直接推送至 Git，則選取直接 Git 推送。
  
  備註：從 Gerrit 發行版本 2.15 開始，不再支援草稿變更和草稿變更集。因此，如果執行的是 Gerrit 發行版本 2.15 或更新版本，則已發佈草稿不是受支援的事件。
2. 選取將觸發的管線。
  如果管線包括自訂新增的輸入參數，[輸入參數] 清單會顯示參數和值。您可以輸入將透過觸發事件傳遞到管線的輸入參數的值。或者，您可以將這些值保留空白，或使用預設值。
  備註：如果已定義預設值：
  - 針對輸入參數輸入的任何值都將覆寫管線模型中定義的預設值。
  - 如果管線模型中的參數值發生變更，觸發器組態中的預設值不會變更。
  如需 Gerrit 觸發器的自動插入輸入參數的相關資訊，請參閱必要條件。
3. 對於已建立修補程式集、已發佈草稿或已合併變更，某些動作預設會與標籤一起出現。您可以變更標籤或新增註解。然後，當管線執行時，標籤或註解會在活動索引標籤中針對管線顯示為已採取動作。
  Gerrit 事件組態可讓您使用針對成功註解或失敗註解的變數輸入註解。例如： ${var.success} 和 ${var.failure}。
4. 按一下儲存。
若要在多個管線上新增多個觸發事件，請再次按一下新增組態。
在下列範例中，您會看到三個管線的事件：
- 如果 Gerrit 專案中發生已合併變更事件，會觸發名為 Gerrit-Pipeline 的管線。
- 如果 Gerrit 專案中發生已建立修補程式集事件，會觸發名為 Gerrit-Trigger-Pipeline 和 Gerrit-Demo-Pipeline 的管線。
按一下建立。
Gerrit 觸發器在觸發器索引標籤上顯示為新卡，且預設設定為已停用。
在觸發器卡上，按一下啟用。
啟用觸發器後，它會使用 Gerrit 接聽程式，該接聽程式將開始監控 Gerrit 專案分支上發生的事件。

若要建立具有相同檔案包含條件或檔案排除條件但存放庫不同於建立觸發器時所包括的存放庫的觸發器，請在觸發器卡上按一下動作 > 複製。然後，在複製的觸發器上，按一下開啟，然後變更參數。

結果

恭喜您！您已成功設定在三個不同管線上有兩個事件的 Gerrit 觸發器。

下一步

認可 Gerrit 專案中的代碼變更之後，在 Code Stream 的活動索引標籤中觀察 Gerrit 事件。請確認活動清單是否包含與觸發器組態中的每個管線執行對應的項目。

發生事件時，僅 Gerrit 觸發器中與特定事件類型相關的管線可以執行。在此範例中，如果已建立修補程式集，僅會執行 Gerrit-Trigger-Pipeline 和 Gerrit-Demo-Pipeline。

活動索引標籤上的資料行中的資訊說明了每個 Gerrit 觸發器事件。可以按一下資料表下方顯示的資料行圖示來選取顯示的資料行。

如果觸發器是直接 Git 推送，則變更主題和執行資料行為空白。
適用於 Gerrit 的觸發器資料行顯示已建立事件的觸發器。
接聽程式資料行預設為關閉狀態。選取該資料行時，資料行將顯示接收事件的 Gerrit 接聽程式。單一接聽程式可能會顯示為與多個觸發器相關聯。
觸發器類型資料行預設為關閉狀態。選取該資料行時，資料行將觸發器類型顯示為 [自動] 或 [手動]。
其他資料行包括認可時間、變更編號、狀態、訊息、已採取動作、使用者、Gerrit 專案、分支和事件。

Gerrit 觸發器的活動索引標籤顯示所有選取的資料行，以及每個資料行中所有活動項目的相關資訊。

若要控制完成或失敗的管線執行的活動，請按一下 [活動] 畫面上任何項目左側的三個點。

如果此管線因管線模型錯誤或其他問題而無法執行，請更正錯誤，然後選取重新執行以再次執行管線。
如果此管線因網路連線問題或其他問題而無法執行，請選取繼續以重新啟動相同的管線執行並節省執行時間。
使用檢視執行以開啟管線執行視圖。請參閱如何執行管線和查看結果。
使用刪除從 [活動] 畫面中刪除項目。

如果 Gerrit 事件無法觸發管線，可以按一下手動觸發，然後選取適用於 Gerrit 的觸發器，輸入 Change-Id，並按一下執行。

備註：手動觸發僅適用於有效的 Gerrit 事件，如修補程式集已建立、變更已合併和草稿已發佈。