Amazon CodeCatalyst 不再向新客戶開放。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[如何從 CodeCatalyst 遷移](migration.md)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 工作流程 YAML 定義 以下是工作流程定義檔案的參考文件。 *工作流程定義檔案*是描述工作流程的 YAML 檔案。根據預設，檔案會存放在[來源儲存庫](source-repositories.md)根目錄的`~/.codecatalyst/workflows/`資料夾中。檔案可以有 .yml 或 .yaml 副檔名，且副檔名必須為小寫。 若要建立和編輯工作流程定義檔案，您可以使用 vim 等編輯器，也可以使用 CodeCatalyst 主控台的視覺化編輯器或 YAML 編輯器。如需詳細資訊，請參閱[使用 CodeCatalyst 主控台的視覺效果和 YAML 編輯器](workflow.md#workflow.editors)。 **注意** 下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。 **Topics** + [ ## 工作流程定義檔案的範例 ](#workflow.anatomy) + [ ## 語法準則和慣例 ](#workflow.terms.syntax.conv) + [ ## 最上層屬性 ](#workflow.top.level) ## 工作流程定義檔案的範例 以下是簡單工作流程定義檔案的範例。它包含幾個最上層屬性、一個`Triggers`區段，以及具有兩個動作的 `Actions`區段： `Build`和 `Test`。如需詳細資訊，請參閱[關於工作流程定義檔案](workflow.md#workflow.example)。 ``` Name: MyWorkflow SchemaVersion: 1.0 RunMode: QUEUED Triggers: - Type: PUSH Branches: - main Actions: Build: Identifier: aws/build@v1 Inputs: Sources: - WorkflowSource Configuration: Steps: - Run: docker build -t MyApp:latest . Test: Identifier: aws/managed-test@v1 DependsOn: - Build Inputs: Sources: - WorkflowSource Configuration: Steps: - Run: npm install - Run: npm run test ``` ## 語法準則和慣例 本節說明工作流程定義檔案的語法規則，以及此參考文件中所使用的命名慣例。 ### YAML 語法準則 工作流程定義檔案是以 YAML 撰寫，並遵循 [YAML 1.1 規格](https://yaml.org/spec/)，因此工作流程 YAML 也允許該規格中允許的任何內容。如果您是 YAML 的新手，以下是一些快速準則，以確保您提供有效的 YAML 程式碼。 + **區分大小寫**：工作流程定義檔案區分大小寫，因此請務必使用本文件中顯示的大小寫。 + **特殊字元**：建議在包含下列任何特殊字元的屬性值中使用引號或雙引號：`{`、`}`、`[``]`、、、、`*``#``?``|`、`-`、、、＜、＞、`=`、`!`、`%``@`、、、`:`、 ```和 `,` 如果您未包含引號，先前列出的特殊字元可能會以非預期的方式解譯。 + **屬性名稱**：屬性*名稱* （相對於屬性*值*) 僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號或雙引號在屬性名稱中啟用特殊字元和空格。 不允許： `'My#Build@action'` `My#Build@action` `My Build Action` 允許： `My-Build-Action_1` + **逸出碼**：如果您的屬性值包含逸出碼 （例如 `\n`或 `\t`)，請遵循下列準則： + 使用單引號將逸出碼傳回為字串。例如， `'my string \n my string'`會傳回字串 `my string \n my string`。 + 使用雙引號來剖析逸出碼。例如，`"my string \n my new line"`， 會傳回： ``` my string my new line ``` + **註解**：使用 的字首註解`#`。 範例： ``` Name: MyWorkflow # This is a comment. SchemaVersion: 1.0 ``` + **三重破折號 (`---`)**：請勿在 YAML 程式碼`---`中使用 。CodeCatalyst 會忽略 之後的所有項目`---`。 ### 命名慣例 在本指南中，我們使用 術語*屬性* 和 *區段*來參考工作流程定義檔案中的主要項目。 + *屬性*是包含冒號 () 的任何項目`:`。例如，在以下程式碼片段中，下列所有都是屬性：`Name`、`SchemaVersion`、`RunMode`、`Triggers`、 `Type`和 `Branches`。 + *區段*是具有子屬性的任何屬性。在下列程式碼片段中，有一個`Triggers`區段。 **注意** 在本指南中，'sections' 有時稱為 'properties'，視內容而定。 ``` Name: MyWorkflow SchemaVersion: 1.0 RunMode: QUEUED Triggers: - Type: PUSH Branches: - main ``` ## 最上層屬性 以下是工作流程定義檔案中最上層屬性的參考文件。 ``` # Name Name: workflow-name # Schema version SchemaVersion: 1.0 # Run mode RunMode: QUEUED|SUPERSEDED|PARALLEL # Compute Compute: ... # Triggers Triggers: ... # Actions Actions: ... ``` ### Name (必要) 工作流程的名稱。工作流程名稱會顯示在工作流程清單中，並在通知和日誌中提及。工作流程名稱和工作流程定義檔案名稱可以相符，或者您可以用不同的名稱命名。工作流程名稱不需要是唯一的。工作流程名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在工作流程名稱中啟用特殊字元和空格。 對應的 UI：視覺化編輯器/工作流程屬性/**工作流程名稱** ### SchemaVersion (必要) 工作流程定義的結構描述版本。目前唯一有效的值為：`1.0`。 對應的 UI：*無* ### RunMode (選用) CodeCatalyst 如何處理多個執行。您可以使用下列其中一個值： + `QUEUED` – 多個執行會排入佇列，並依序執行。佇列中最多可以有 50 個執行。 + `SUPERSEDED` – 多個執行會排入佇列，並依序執行。佇列只能有一個執行，因此，如果兩個執行在同一佇列中一起執行，則稍後的執行會取代 （接管） 較早的執行，而較早的執行會取消。 + `PARALLEL` – 同時進行多次執行。 如果省略此屬性，則預設值為 `QUEUED`。 如需詳細資訊，請參閱[設定執行的佇列行為](workflows-configure-runs.md)。 對應的 UI：視覺化編輯器/工作流程屬性/進階/**執行模式** ### Compute (選用) 用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在相同的執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。 如需運算的詳細資訊，請參閱 [設定運算和執行時間映像](workflows-working-compute.md)。 對應的 UI：*無* ``` Name: MyWorkflow SchemaVersion: 1.0 ... Compute: Type: EC2 | Lambda Fleet: fleet-name SharedInstance: true | false ``` #### Type (Compute/**Type**) （如果`Compute`已設定 則為必要） 運算引擎的類型。您可以使用下列其中一個值： + **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器） 針對動作執行期間的彈性進行最佳化。 + **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器） 最佳化的動作啟動速度。 如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。 對應的 UI：視覺化編輯器/工作流程屬性/進階/**運算類型** #### Fleet (Compute/**Fleet**) (選用) 指定將執行工作流程或工作流程動作的機器或機群。使用隨需機群時，當動作開始時，工作流程會佈建所需的資源，並在動作完成時銷毀機器。隨需機群的範例：`Linux.x86-64.Large`、`Linux.x86-64.XLarge`。如需隨需機群的詳細資訊，請參閱[隨需機群屬性](workflows-working-compute.md#compute.on-demand)。 使用佈建機群，您可以設定一組專用機器來執行工作流程動作。這些機器保持閒置狀態，準備好立即處理動作。如需佈建機群的詳細資訊，請參閱 [佈建的機群屬性](workflows-working-compute.md#compute.provisioned-fleets)。 如果省略 `Fleet` ，則預設值為 `Linux.x86-64.Large`。 如需運算機群的詳細資訊，請參閱 [運算機群](workflows-working-compute.md#compute.fleets)。 對應的 UI：視覺化編輯器/工作流程屬性/進階/**運算機群** #### SharedInstance (Compute/**SharedInstance**) (選用) 為您的動作指定運算共用功能。使用運算共用時，工作流程中的動作會在相同的執行個體上執行 （執行期環境映像）。您可以使用下列其中一個值： + `TRUE` 表示在工作流程動作之間共用執行期環境映像。 + `FALSE` 表示工作流程中的每個動作都會啟動並使用個別的執行期環境映像，因此您無法在沒有額外組態的情況下共用成品和變數等資源。 如需運算共用的詳細資訊，請參閱 [跨動作共用運算](compute-sharing.md)。 對應的 UI：*無* ### Triggers (選用) 此工作流程的一或多個觸發程序序列。如果未指定觸發條件，則必須手動啟動工作流程。 關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。 對應的 UI：視覺化編輯器/工作流程圖表/**觸發器** ``` Name: MyWorkflow SchemaVersion: 1.0 ... Triggers: - Type: PUSH Branches: - branch-name FilesChanged: - folder1/file - folder2/ - Type: PULLREQUEST Events: - OPEN - CLOSED - REVISION Branches: - branch-name FilesChanged: - file1.txt - Type: SCHEDULE # Run the workflow at 10:15 am (UTC+0) every Saturday Expression: "15 10 ? * 7 *" Branches: - branch-name ``` #### Type (Triggers/**Type**) （如果`Triggers`已設定 則為必要） 指定觸發的類型。您可以使用下列其中一個值： + **推送** （視覺化編輯器） 或 `PUSH`(YAML 編輯器） 當變更推送到您的來源儲存庫時，推送觸發會啟動工作流程執行。工作流程執行將使用您推送*到*的分支中的檔案 （即目的地分支）。 + **提取請求** （視覺化編輯器） 或 `PULLREQUEST`(YAML 編輯器） 提取請求觸發會在來源儲存庫中開啟、更新或關閉提取請求時啟動工作流程執行。工作流程執行將使用您*從*中提取的分支中的檔案 （即來源分支）。 + **排程** （視覺化編輯器） 或 `SCHEDULE`(YAML 編輯器） 排程觸發程序會根據您指定的 Cron 表達式所定義的排程啟動工作流程。將針對來源儲存庫中的每個分支，使用分支的 檔案啟動個別的工作流程執行。（若要限制觸發啟動的分支，請使用**分支**欄位 （視覺化編輯器） 或 `Branches` 屬性 (YAML 編輯器）。) 設定排程觸發時，請遵循下列準則： + 每個工作流程僅使用一個排程觸發。 + 如果您已在 CodeCatalyst 空間中定義多個工作流程，建議您排定不超過 10 個工作流程同時啟動。 + 請務必在執行之間設定具有足夠時間的觸發條件 cron 表達式。如需詳細資訊，請參閱[Expression](#workflow.triggers.expression)。 如需範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 對應的 UI：視覺化編輯器/工作流程圖表/觸發器/**觸發器類型** #### Events (Triggers/**Events**) （如果觸發`Type`設定為 ，則為必要`PULLREQUEST`) 指定將啟動工作流程執行的提取請求事件類型。以下是有效值： + **提取請求已建立** （視覺化編輯器） 或 `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)。 對應的 UI：視覺化編輯器/工作流程圖表/觸發器/**提取請求的事件** #### Branches (Triggers/**Branches**) (選用) 在您的來源儲存庫中指定觸發器監控的分支，以了解何時啟動工作流程執行。您可以使用 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)。 對應的 UI：視覺化編輯器/工作流程圖表/觸發器/**分支** #### FilesChanged (Triggers/**FilesChanged**) （如果觸發`Type`設定為 `PUSH`、 或 ，則為選用`PULLREQUEST`。 如果觸發`Type`設定為 ，則不支援 `SCHEDULE`。) 指定觸發器監控的來源儲存庫中的檔案或資料夾，以了解何時啟動工作流程執行。您可以使用規則表達式來比對檔案名稱或路徑。 如需範例，請參閱 [範例：工作流程中的觸發條件](workflows-add-trigger-examples.md)。 對應的 UI：視覺化編輯器/工作流程圖表/觸發條件/**檔案已變更** #### Expression (Triggers/**Expression**) （如果觸發`Type`設定為 ，則為必要`SCHEDULE`) 指定 cron 表達式，描述您希望排程工作流程執行的時間。 CodeCatalyst 中的 Cron 表達式使用以下六欄位語法，其中每個欄位以空格分隔： *分鐘* *小時* *days-of-month* *日 年* ** *days-of-week* **Cron 表達式的範例** | 分鐘 | 小時 | 每月的天數 | 月 | 星期幾 | 年 | 意義 | | --- | --- | --- | --- | --- | --- | --- | | 0 | 0 | ? | \$1 | MON-FRI | \$1 | 每週一到週五午夜 (UTC\$10) 執行工作流程。 | | 0 | 2 | \$1 | \$1 | ? | \$1 | 在每天上午 2：00 (UTC\$10) 執行工作流程。 | | 15 | 22 | \$1 | \$1 | ? | \$1 | 每天在下午 10：15 (UTC\$10) 執行工作流程。 | | 0/30 | 22-2 | ? | \$1 | SAT-SUN | \$1 | 每 30 分鐘執行工作流程，星期六至星期日的開始時間為下午 10：00，第二天為上午 2：00 (UTC\$10)。 | | 45 | 13 | L | \$1 | ? | 2023-2027 | 於 2023 年至 2027 年之間該月最後一天下午 1：45 (UTC\$10) 執行工作流程。 | 在 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)。 對應的 UI：視覺化編輯器/工作流程圖表/觸發器/**排程** ### 動作 此工作流程的一或多個動作序列。CodeCatalyst 支援數種動作類型，例如建置和測試動作，可提供不同類型的功能。每個動作類型都有： + 表示動作唯一、硬式編碼 ID 的 `Identifier` 屬性。例如， `aws/build@v1` 識別建置動作。 + `Configuration` 區段，其中包含 動作特有的屬性。 如需每個動作類型的詳細資訊，請參閱 [動作類型](workflows-actions.md#workflows-actions-types)。[動作類型](workflows-actions.md#workflows-actions-types) 主題包含每個動作的文件連結。 以下是工作流程定義檔案中動作和動作群組的 YAML 參考。 ``` Name: MyWorkflow SchemaVersion: 1.0 ... Actions: action-or-gate-name: Identifier: identifier Configuration: ... #Action groups action-group-name: Actions: ... ``` #### action-or-gate-name (Actions/*action-or-gate-name*) (必要) 將 *action-name* 取代為您要提供動作的名稱。動作名稱在工作流程中必須是唯一的，而且只能包含英數字元、連字號和底線。如需語法規則的詳細資訊，請參閱 [YAML 語法準則](#workflow.syntax.conv)。 如需 動作命名實務的詳細資訊，包括限制，請參閱 [action-or-gate-name](#workflow.actions.name)。 對應的 UI：視覺化編輯器/*action-name*/Configuration 標籤/**動作名稱**或**動作顯示名稱** #### action-group-name (Actions/*action-group-name*) (選用) *動作群組*包含一或多個動作。將動作分組為動作群組可協助您整理工作流程，也可讓您設定不同群組之間的相依性。 將 *action-group-name* 取代為您要提供動作群組的名稱。動作群組名稱在工作流程中必須是唯一的，而且只能包含英數字元、連字號和底線。如需語法規則的詳細資訊，請參閱 [YAML 語法準則](#workflow.syntax.conv)。 如需動作群組的詳細資訊，請參閱 [將動作分組為動作群組](workflows-group-actions.md)。 對應的 UI：*無*