Amazon CodeCatalyst 不再向新客戶開放。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[如何從 CodeCatalyst 遷移](migration.md)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用觸發程序自動啟動工作流程執行 您可以使用工作流程觸發來自動啟動 Amazon CodeCatalyst 工作流程執行。 *工作流程觸發*或只是*觸發*，可讓您在特定事件發生時自動啟動工作流程執行，例如程式碼推送。您可能想要設定觸發條件，讓您的軟體開發人員無需透過 CodeCatalyst 主控台手動啟動工作流程執行。 您可以使用三種類型的觸發： + **推送** – 程式碼推送觸發會在推送遞交時啟動工作流程執行。 + **提取請求** – 提取請求觸發會在建立、修訂或關閉提取請求時啟動工作流程執行。 + **排程** – 排程觸發程序會導致工作流程執行從您定義的排程開始。考慮使用排程觸發條件來執行軟體的夜間組建，以便軟體開發人員可以在隔天早上使用最新的組建。 您可以單獨使用推送、提取請求和排程觸發，或在相同的工作流程中結合使用。 觸發是選用的，如果您未設定任何 ，您只能手動啟動工作流程。 **提示** 若要查看執行中的觸發條件，請使用藍圖啟動專案。大多數藍圖都包含具有觸發條件的工作流程。在藍圖的工作流程定義檔案中尋找 `Trigger` 屬性。如需有關藍圖的詳細資訊，請參閱 [使用藍圖建立專案](projects-create.md#projects-create-console-template)。 **Topics** + [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md) + [觸發和分支的使用準則](workflows-add-trigger-considerations.md) + [將觸發條件新增至工作流程](workflows-add-trigger-add.md) # 範例：工作流程中的觸發條件 下列範例示範如何在 Amazon CodeCatalyst 工作流程定義檔案中新增不同類型的觸發。 關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。 **Topics** + [範例：簡單的程式碼推送觸發程序](#workflows-add-trigger-examples-push-simple) + [範例：簡單的「推送至主要」觸發](#workflows-add-trigger-examples-push-main) + [範例：簡易的提取請求觸發程序](#workflows-add-trigger-examples-pull-simple) + [範例：簡單的排程觸發](#workflows-add-trigger-examples-schedule-simple) + [範例：具有排程和分支的觸發](#workflows-add-trigger-examples-schedule-branches) + [範例：具有排程、推送和分支的觸發](#workflows-add-trigger-examples-schedule-push-branches) + [範例：具有提取和分支的觸發](#workflows-add-trigger-examples-pull-branches) + [範例：具有提取、分支和「關閉」事件的觸發](#workflows-add-trigger-examples-push-pull-close) + [範例：具有推送、分支和檔案的觸發](#workflows-add-trigger-examples-push-multi) + [範例：手動觸發](#workflows-add-trigger-examples-manual) + [範例：CI/CD 多工作流程設定中的觸發](#workflows-add-trigger-usecases) ## 範例：簡單的程式碼推送觸發程序 下列範例顯示每當程式碼推送到來源儲存庫中的任何**分支時，啟動工作流程執行的觸發。 啟用此觸發時，CodeCatalyst 會使用您推送*到*的分支 （即目的地分支） 中的檔案啟動工作流程執行。 例如，如果您將遞交推送至 `main`，CodeCatalyst 會使用 Workfow 定義檔案和 上的其他來源檔案啟動工作流程執行`main`。 另一個範例是，如果您將遞交推送至 `feature-branch-123`，CodeCatalyst 會使用 Workfow 定義檔案和 上的其他來源檔案啟動工作流程執行`feature-branch-123`。 ``` Triggers: - Type: PUSH ``` **注意** 如果您希望工作流程執行只在您推送至 時啟動`main`，請參閱 [範例：簡單的「推送至主要」觸發](#workflows-add-trigger-examples-push-main)。 ## 範例：簡單的「推送至主要」觸發 下列範例顯示觸發程序，會在程式碼推送至**`main`來源儲存庫中的`main`分支時啟動工作流程。 ``` Triggers: - Type: PUSH Branches: - main ``` ## 範例：簡易的提取請求觸發程序 下列範例顯示在來源儲存庫中建立或修改提取請求時啟動工作流程執行的觸發。 啟用此觸發時，CodeCatalyst 會使用工作流程定義檔案和您*從*中提取的分支 （即來源分支） 中的其他來源檔案啟動工作流程執行。 例如，如果您使用名為 的來源分支`feature-123`和名為 的目的地分支建立提取請求`main`，CodeCatalyst 會使用 Workfow 定義檔案和 上的其他來源檔案啟動工作流程執行`feature-123`。 ``` Triggers: - Type: PULLREQUEST Events: - OPEN - REVISION ``` ## 範例：簡單的排程觸發 下列範例顯示的觸發會在每個週一至週五的午夜 (UTC\$10) 啟動工作流程執行。 啟用此觸發條件時，CodeCatalyst 會針對來源儲存庫中的每個分支啟動單一工作流程執行，其中包含具有此觸發條件的工作流程定義檔案。 例如，如果您的來源儲存庫中有三個分支，`main`、`release-v1``feature-123`、，且每個分支都包含一個工作流程定義檔案，其觸發條件如下，則 CodeCatalyst 會啟動三個工作流程執行：一個使用 中的檔案`main`，另一個使用 中的檔案`release-v1`，另一個使用 中的檔案`feature-123`。 ``` Triggers: - Type: SCHEDULE Expression: "0 0 ? * MON-FRI *" ``` 如需您可以在 `Expression` 屬性中使用的 cron 表達式的更多範例，請參閱 [Expression](workflow-reference.md#workflow.triggers.expression)。 ## 範例：具有排程和分支的觸發 下列範例顯示的觸發會在每天下午 6：15 (UTC\$10) 啟動工作流程執行。 啟用此觸發時，CodeCatalyst 會使用`main`分支中的檔案啟動工作流程執行，並針對以 開頭的每個分支啟動額外的執行`release-`。 例如，如果您的來源儲存庫`bugfix-2`中有名為 `main`、`bugfix-1`、 `release-v1`和 的分支，CodeCatalyst 會啟動兩個工作流程執行：一個使用 中的檔案`main`，另一個使用 中的檔案`release-v1`。它*不會*啟動 `bugfix-1`和 `bugfix-1`分支的工作流程執行。 ``` Triggers: - Type: SCHEDULE Expression: "15 18 * * ? *" Branches: - main - release\-.* ``` 如需您可以在 `Expression` 屬性中使用的 cron 表達式的更多範例，請參閱 [Expression](workflow-reference.md#workflow.triggers.expression)。 ## 範例：具有排程、推送和分支的觸發 下列範例顯示每天午夜 (UTC\$10) 開始工作流程執行的觸發，以及每當程式碼推送到`main`分支時。 在此範例中： + 工作流程執行會在每天午夜開始。工作流程執行會使用工作流程定義檔案和`main`分支中的其他來源檔案。 + 每當您將遞交推送到`main`分支時，工作流程執行也會開始。工作流程執行會使用目的地分支 () 中的工作流程定義檔案和其他來源檔案`main`。 ``` Triggers: - Type: SCHEDULE Expression: "0 0 * * ? *" Branches: - main - Type: PUSH Branches: - main ``` 如需您可以在 `Expression` 屬性中使用的 cron 表達式的更多範例，請參閱 [Expression](workflow-reference.md#workflow.triggers.expression)。 ## 範例：具有提取和分支的觸發 下列範例顯示觸發程序，會在有人開啟或修改具有名為 之目的地分支的提取請求時啟動工作流程執行`main`。雖然`Triggers`組態中指定的分支是 `main`，工作流程執行將使用工作流程定義檔案和來源分支 （您正在*提取*的分支） 中的其他*來源*檔案。 ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` ## 範例：具有提取、分支和「關閉」事件的觸發 下列範例顯示每當提取請求在開頭為 的分支上關閉時，啟動工作流程執行的觸發`main`。 在此範例中： + 當您以開頭為 的目的地分支關閉提取請求時`main`，工作流程執行會使用工作流程定義檔案和 （現在已關閉） 來源分支中的其他來源檔案自動啟動。 + 如果您已將來源儲存庫設定為在提取請求合併後自動刪除分支，則這些分支將永遠無法進入 `CLOSED` 狀態。這表示合併的分支不會啟用提取請求`CLOSED`觸發。在此案例中啟用`CLOSED`觸發程序的唯一方法是關閉提取請求而不合併。 ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - CLOSED ``` ## 範例：具有推送、分支和檔案的觸發 下列範例顯示觸發程序，會在對 `main` 分支上的 `filename.txt` 檔案或 `src`目錄中的任何檔案進行變更時啟動工作流程執行。 啟用此觸發時，CodeCatalyst 會使用工作流程定義檔案和`main`分支中的其他來源檔案啟動工作流程執行。 ``` Triggers: - Type: PUSH Branches: - main FilesChanged: - filename.txt - src\/.* ``` ## 範例：手動觸發 若要設定手動觸發，請省略工作流程定義檔案中的 `Triggers`區段。如果沒有本節，使用者在 CodeCatalyst 主控台中選擇**執行**按鈕，強制使用者手動啟動工作流程。如需詳細資訊，請參閱[手動啟動工作流程執行](workflows-manually-start.md)。 ## 範例：CI/CD 多工作流程設定中的觸發 此範例說明如何在想要使用單獨的 Amazon CodeCatalyst 工作流程進行持續整合 (CI) 和持續部署 (CD) 時設定觸發。 在此案例中，您會設定兩個工作流程： + **CI 工作流程** – 此工作流程會在建立或修改提取請求時建置和測試您的應用程式。 + **CD 工作流程** – 此工作流程會在提取請求合併時建置和部署您的應用程式。 **CI 工作流程**的定義檔案如下所示： ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION Actions: BuildAction: instructions-for-building-the-app TestAction: instructions-for-test-the-app ``` `Triggers` 程式碼指出每當軟體開發人員建立提取請求 （或修改[請求](pull-requests-update.md))，要求將其功能分支合併到`main`分支時， 會自動啟動工作流程執行。CodeCatalyst 會使用來源分支 （即功能分支） 中的來源碼啟動工作流程執行。 **CD 工作流程**的定義檔案如下所示： ``` Triggers: - Type: PUSH Branches: - main Actions: BuildAction: instructions-for-building-the-app DeployAction: instructions-for-deploying-the-app ``` `Triggers` 程式碼指出 會在合併`main`到 時自動啟動工作流程。CodeCatalyst 會使用`main`分支中的原始程式碼啟動工作流程執行。 # 觸發和分支的使用準則 本節說明設定包含分支的 Amazon CodeCatalyst 觸發條件時的一些主要準則。 關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。 + **準則 1：**對於推送和提取請求觸發，如果您要指定分支，您必須在觸發組態中指定目的地 （或 'to') 分支。切勿指定來源 （或 'from') 分支。 在下列範例中，從任何分支推送以`main`啟用工作流程。 ``` Triggers: - Type: PUSH Branches: - main ``` 在下列範例中，從任何分支提取請求到 會`main`啟用工作流程。 ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` + **準則 2：**對於推送觸發，在啟用工作流程之後，工作流程將使用*目的地*分支中的工作流程定義檔案和來源檔案執行。 + **準則 3：**對於提取請求觸發，在啟用工作流程之後，工作流程將使用*來源*分支中的工作流程定義檔案和來源檔案執行 （即使您在觸發組態中指定了目的地分支）。 + **準則 4：**一個分支中完全相同的觸發條件可能不會在另一個分支中執行。 請考慮下列推送觸發條件： ``` Triggers: - Type: PUSH Branches: - main ``` 如果包含此觸發條件的工作流程定義檔案存在於 中`main`，並複製到 `test`，則工作流程永遠不會使用 中的檔案自動啟動 `test`（雖然您可以*手動*啟動工作流程，讓它使用 中的檔案`test`)。檢閱**指導方針 2**，了解為什麼工作流程永遠不會使用 中的檔案自動執行`test`。 另請考慮下列提取請求觸發條件： ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` 如果包含此觸發條件的工作流程定義檔案存在於 中`main`，則工作流程永遠不會使用 中的檔案執行`main`。（不過，如果您從 建立`test`分支`main`，工作流程將使用 中的檔案執行`test`。) 檢閱**指南 3** 以了解原因。 # 將觸發條件新增至工作流程 使用下列指示，將推送、提取或排程觸發新增至 Amazon CodeCatalyst 工作流程。 關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。 ------ #### [ Visual ] **新增觸發條件 （視覺化編輯器）** 1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。 1. 選擇您的專案。 1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。 1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。 1. 選擇**編輯**。 1. 選擇**視覺化**。 1. 在工作流程圖表中，選擇**來源**和**觸發**方塊。 1. 在組態窗格中，選擇**新增觸發**條件。 1. 在**新增觸發**條件對話方塊中，提供欄位中的資訊，如下所示。 **觸發類型** 指定觸發的類型。您可以使用下列其中一個值： + **推送** （視覺化編輯器） 或 `PUSH`(YAML 編輯器） 當變更推送到您的來源儲存庫時，推送觸發會啟動工作流程執行。工作流程執行將使用您推送*到*的分支中的檔案 （即目的地分支）。 + **提取請求** （視覺化編輯器） 或 `PULLREQUEST`(YAML 編輯器） 提取請求觸發會在來源儲存庫中開啟、更新或關閉提取請求時啟動工作流程執行。工作流程執行將使用您*從*中提取的分支中的檔案 （即來源分支）。 + **排程** （視覺化編輯器） 或 `SCHEDULE`(YAML 編輯器） 排程觸發會根據您指定的 Cron 表達式所定義的排程啟動工作流程。將針對來源儲存庫中的每個分支，使用分支的 檔案啟動個別的工作流程執行。（若要限制觸發啟動的分支，請使用**分支**欄位 （視覺化編輯器） 或 `Branches` 屬性 (YAML 編輯器）。) 設定排程觸發時，請遵循下列準則： + 每個工作流程僅使用一個排程觸發。 + 如果您已在 CodeCatalyst 空間中定義多個工作流程，建議您排定最多 10 個工作流程同時啟動。 + 請務必在執行之間設定具有足夠時間的觸發條件 cron 表達式。如需詳細資訊，請參閱[Expression](workflow-reference.md#workflow.triggers.expression)。 如需範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 **提取請求的事件** 只有在您選取**提取請求**觸發類型時，才會顯示此欄位。 指定將啟動工作流程執行的提取請求事件類型。以下是有效值： + **提取請求已建立** （視覺化編輯器） 或 `OPEN`(YAML 編輯器） 建立提取請求時，會啟動工作流程執行。 + **提取請求已關閉** （視覺化編輯器） 或 `CLOSED`(YAML 編輯器） 關閉提取請求時，會啟動工作流程執行。`CLOSED` 事件的行為很棘手，最好透過範例了解。如需詳細資訊，請參閱[範例：具有提取、分支和「關閉」事件的觸發](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close)。 + **進行新的修訂以提取請求 **（視覺化編輯器） 或 `REVISION`(YAML 編輯器） 建立提取請求的修訂時，會啟動工作流程執行。第一個修訂會在建立提取請求時建立。之後，每次有人將新的遞交推送到提取請求中指定的來源分支時，都會建立新的修訂。如果您在提取請求觸發中包含`REVISION`事件，您可以省略該`OPEN`事件，因為 `REVISION` 是 的超集`OPEN`。 您可以在相同的提取請求觸發中指定多個事件。 如需範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 **排程** 只有在您選取**排程**觸發類型時，才會顯示此欄位。 指定 cron 表達式，描述您希望排程工作流程執行的時間。 CodeCatalyst 中的 Cron 表達式使用以下六欄位語法，其中每個欄位以空格分隔： *分鐘* *小時* *days-of-month* *日 年* ** *days-of-week* **Cron 表達式的範例** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/workflows-add-trigger-add.html) 在 CodeCatalyst 中指定 Cron 表達式時，請務必遵循下列準則： + 指定每個`SCHEDULE`觸發的單一 Cron 表達式。 + 在 YAML 編輯器中以雙引號 (`"`) 括住 Cron 表達式。 + 以國際標準時間 (UTC) 指定時間。不支援其他時區。 + 在執行之間設定至少 30 分鐘。不支援更快速的節奏。 + 指定*days-of-month*或*days-of-week*欄位，但不能同時指定兩者。如果您在其中一個欄位中指定值或星號 (`*`)，則必須在另一個欄位中使用問號 (`?`)。星號表示「全部」，問號表示「任何」。 如需 Cron 表達式的更多範例，以及 `?`、 `*`和 等萬用字元的相關資訊`L`，請參閱《*Amazon EventBridge 使用者指南*》中的 [Cron 表達式參考](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html)。EventBridge 和 CodeCatalyst 中的 Cron 表達式的運作方式完全相同。 如需排程觸發的範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 **分支**和**分支模式** (選用) 在您的來源儲存庫中指定觸發器監控的分支，以便知道何時啟動工作流程執行。您可以使用 regex 模式來定義分支名稱。例如，使用 `main.*` 來比對以 開頭的所有分支`main`。 要指定的分支會根據觸發類型而有所不同： + 對於推送觸發，指定您要推送*的*分支，也就是*目的地*分支。每個相符分支將使用相符分支中的檔案啟動一個工作流程執行。 範例: `main.*`, `mainline` + 對於提取請求觸發，指定您要推送*的*分支，也就是*目的地*分支。每個相符分支都會啟動一個工作流程執行，並使用來源分支 (*而非*相符分支） 中的工作流程定義檔案和**來源**檔案。 範例：`main.*`、`mainline`、 `v1\-.*`（符合開頭為 的分支`v1-`) + 針對排程觸發，指定包含您希望排程執行使用之檔案的分支。每個相符分支都會啟動一個工作流程執行，並使用相符分支中的工作流程定義檔案和來源檔案。 範例: `main.*`, `version\-1\.0` **注意** 如果您*未*指定分支，觸發會監控來源儲存庫中的所有分支，並將使用工作流程定義檔案和來源檔案啟動工作流程執行： 您推送*到*的分支 （適用於推送觸發）。如需詳細資訊，請參閱[範例：簡單的程式碼推送觸發程序](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple)。 您要*從中*提取的分支 （用於提取請求觸發）。如需詳細資訊，請參閱[範例：簡易的提取請求觸發程序](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple)。 所有分支 （用於排程觸發）。您的來源儲存庫中的每個分支都會啟動一個工作流程執行。如需詳細資訊，請參閱[範例：簡單的排程觸發](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple)。 如需分支和觸發程序的詳細資訊，請參閱 [觸發和分支的使用準則](workflows-add-trigger-considerations.md)。 如需更多範例，請參閱[範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 **檔案已變更** 只有在您選取**推送**或**提取請求**觸發類型時，才會顯示此欄位。 指定觸發器監控的來源儲存庫中的檔案或資料夾，以了解何時啟動工作流程執行。您可以使用規則表達式來比對檔案名稱或路徑。 如需範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。 1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。 ------ #### [ YAML ] **新增觸發 (YAML 編輯器）** 1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。 1. 選擇您的專案。 1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。 1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。 1. 選擇**編輯**。 1. 選擇 **YAML**。 1. 使用下列範例做為指南，新增`Triggers`區段和基礎屬性。如需詳細資訊，請參閱《[Triggers](workflow-reference.md#triggers-reference)》中的 [工作流程 YAML 定義](workflow-reference.md)。 程式碼推送觸發程序可能如下所示： ``` Triggers: - Type: PUSH Branches: - main ``` 提取請求觸發程序可能如下所示： ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - OPEN - REVISION - CLOSED ``` 排程觸發程序可能如下所示： ``` Triggers: - Type: SCHEDULE Branches: - main.* # Run the workflow at 1:15 am (UTC+0) every Friday until the end of 2023 Expression: "15 1 ? * FRI 2022-2023" ``` 如需您可以在 `Expression` 屬性中使用的 cron 表達式的更多範例，請參閱 [Expression](workflow-reference.md#workflow.triggers.expression)。 如需推送、提取請求和排程觸發程序的更多範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。 1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。 ------