Amazon CodeCatalyst 不再向新客戶開放。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[如何從 CodeCatalyst 遷移](migration.md)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用工作流程建置、測試和部署
在 [CodeCatalyst 開發環境中](devenvironment.md)撰寫應用程式碼並將其推送至 [CodeCatalyst 來源儲存庫](source.md)後，您就可以進行部署。自動執行此操作的方式是透過工作流程。
*工作流程*是一種自動化程序，說明如何建置、測試和部署您的程式碼，做為持續整合和持續交付 (CI/CD) 系統的一部分。工作流程定義了工作流程執行期間要採取的一系列步驟或*動作*。工作流程也會定義導致工作流程啟動的事件或*觸發條件*。若要設定工作流程，您可以使用 CodeCatalyst 主控台的[視覺化或 YAML 編輯器](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors)建立*工作流程定義檔案*。
**提示**
若要快速了解如何在專案中使用工作流程，[請使用藍圖建立專案](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template)。每個藍圖都會部署可檢閱、執行和實驗的正常運作工作流程。
## 關於工作流程定義檔案
*工作流程定義檔案*是描述工作流程的 YAML 檔案。根據預設，檔案會存放在[來源儲存庫](source-repositories.md)根目錄的`~/.codecatalyst/workflows/`資料夾中。檔案可以有 .yml 或 .yaml 副檔名，且副檔名必須為小寫。
以下是簡單工作流程定義檔案的範例。我們會在下表中說明此範例的每一行。
```
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 .
```
| 折線圖 | Description |
| --- | --- |
| Name: MyWorkflow
| 指定工作流程的名稱。如需 `Name` 屬性的詳細資訊，請參閱 [最上層屬性](workflow-reference.md#workflow.top.level)。 |
| SchemaVersion: 1.0
| 指定工作流程結構描述版本。如需 `SchemaVersion` 屬性的詳細資訊，請參閱 [最上層屬性](workflow-reference.md#workflow.top.level)。 |
| RunMode: QUEUED
| 指出 CodeCatalyst 如何處理多個執行。如需執行模式的詳細資訊，請參閱 [設定執行的佇列行為](workflows-configure-runs.md)。 |
| Triggers:
| 指定會導致工作流程執行開始的邏輯。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。 |
| - Type: PUSH
Branches:
- main
| 指出每當您將程式碼推送至預設來源儲存庫的`main`分支時，工作流程都必須啟動。如需工作流程來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。 |
| Actions:
| 定義工作流程執行期間要執行的任務。在此範例中， `Actions`區段會定義名為 的單一動作`Build`。如需 動作的詳細資訊，請參閱 [設定工作流程動作](workflows-actions.md)。 |
| Build:
| 定義`Build`動作的屬性。如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。 |
| Identifier: aws/build@v1
| 指定建置動作的唯一、硬式編碼識別符。 |
| Inputs:
Sources:
- WorkflowSource
| 表示建置動作應該在`WorkflowSource`來源儲存庫中尋找完成其處理所需的檔案。如需詳細資訊，請參閱[將來源儲存庫連線至工作流程](workflows-sources.md)。 |
| Configuration:
| 包含建置動作特有的組態屬性。 |
| Steps:
- Run: docker build -t MyApp:latest .
| 告知建置動作來建置名為 的 Docker 映像，`MyApp`並使用 加以標記`latest`。 |
如需工作流程定義檔案中所有可用屬性的完整清單，請參閱 [工作流程 YAML 定義](workflow-reference.md)。
## 使用 CodeCatalyst 主控台的視覺效果和 YAML 編輯器
若要建立和編輯工作流程定義檔案，您可以使用您偏好的編輯器，但建議使用 CodeCatalyst 主控台的視覺化編輯器或 YAML 編輯器。這些編輯器提供有用的檔案驗證，以協助確保 YAML 屬性名稱、值、巢狀、間距、大小寫等正確無誤。
下圖顯示視覺化編輯器中的工作流程。視覺化編輯器提供您完整的使用者介面，可讓您透過此界面建立和設定工作流程定義檔案。視覺化編輯器包含顯示工作流程主要元件的工作流程圖表 (1)，以及組態區域 (2)。
![\[工作流程視覺化編輯器\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/workflow-visual-editor.png)
或者，您可以使用 YAML 編輯器，如下圖所示。使用 YAML 編輯器貼入大型程式碼區塊 （例如，從教學課程），或新增未透過視覺化編輯器提供的進階屬性。
![\[工作流程 YAML 編輯器\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/workflow-yaml-editor.png)
您可以從視覺化編輯器切換到 YAML 編輯器，以查看組態對基礎 YAML 程式碼的影響。
## 探索工作流程
您可以在工作流程摘要頁面上檢視您的**工作流程**，以及您在相同專案中設定的其他工作流程。
下圖顯示**工作流程**摘要頁面。它會填入兩個工作流程： **BuildToProd** 和 **UnitTests**。您可以看到兩者都已執行幾次。您可以選擇**最近執行**來快速查看執行歷史記錄，或選擇工作流程的名稱來查看工作流程的 YAML 程式碼和其他詳細資訊。
![\[工作流程日誌\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/workflow-list.png)
## 檢視工作流程執行詳細資訊
您可以在工作流程摘要頁面中選擇執行，以檢視**工作流程**執行的詳細資訊。
下圖顯示名為 **Run-cc11d** 的工作流程執行詳細資訊，該工作流程會在遞交來源時自動啟動。工作流程圖表指出動作失敗 (1)。您可以導覽至日誌 (2)，以檢視詳細的日誌訊息並疑難排解問題。如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
![\[工作流程日誌\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/workflow-visual-logs.png)
## 後續步驟
若要進一步了解工作流程概念，請參閱 [工作流程概念](workflows-concepts.md)。
若要建立您的第一個工作流程，請參閱 [工作流程入門](workflows-getting-started.md)。
# 工作流程概念
以下是在 CodeCatalyst 中使用工作流程建置、測試或部署程式碼時，應注意的一些概念和術語。
## 工作流程
*工作流程*是一種自動化程序，說明如何建置、測試和部署您的程式碼，做為持續整合和持續交付 (CI/CD) 系統的一部分。工作流程會定義工作流程執行期間要採取的一系列步驟或*動作*。工作流程也會定義導致工作流程啟動的事件或*觸發條件*。若要設定工作流程，您可以使用 CodeCatalyst 主控台的[視覺化或 YAML 編輯器](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors)建立*工作流程定義檔案*。
**提示**
若要快速了解如何在專案中使用工作流程，[請使用藍圖建立專案](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template)。每個藍圖都會部署可檢閱、執行和實驗的正常運作工作流程。
## 工作流程定義檔案
*工作流程定義檔案*是描述工作流程的 YAML 檔案。根據預設，檔案會存放在[來源儲存庫](source-repositories.md)根目錄的`~/.codecatalyst/workflows/`資料夾中。檔案可以有 .yml 或 .yaml 副檔名，且副檔名必須為小寫。
如需工作流程定義檔案的詳細資訊，請參閱 [工作流程 YAML 定義](workflow-reference.md)。
## 動作
*動作*是工作流程的主要建置區塊，並定義要在工作流程執行期間執行的邏輯工作單位或任務。一般而言，工作流程包含多個動作，這些動作會根據您的設定方式依序或平行執行。
如需 動作的詳細資訊，請參閱 [設定工作流程動作](workflows-actions.md)。
## 動作群組
*動作群組*包含一或多個動作。將動作分組為動作群組可協助您整理工作流程，也可讓您設定不同群組之間的相依性。
如需動作群組的詳細資訊，請參閱 [將動作分組為動作群組](workflows-group-actions.md)。
## 成品
*成品*是工作流程動作的輸出，通常由資料夾或檔案封存組成。成品很重要，因為它們允許您在動作之間共用檔案和資訊。
如需成品的詳細資訊，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
## 運算
*運算*是指由 CodeCatalyst 管理和維護以執行工作流程動作的運算引擎 (CPU、記憶體和作業系統）。
如需運算的詳細資訊，請參閱 [設定運算和執行時間映像](workflows-working-compute.md)。
## 環境
CodeCatalyst *環境*不會與[開發環境](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html)混淆，會定義 CodeCatalyst [工作流程](workflow.md)連線的目標 AWS 帳戶 和選用 Amazon VPC。環境也會定義工作流程存取目標帳戶中 AWS 的服務和資源所需的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
您可以設定多個環境並為其命名，例如開發、測試、預備和生產等名稱。當您部署到這些環境中時，有關部署的資訊會顯示於環境中的 CodeCatalyst **部署活動**和**部署目標**標籤上。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
## 閘道
除非符合特定條件，否則*閘道*是可用於防止工作流程執行的工作流程元件。閘道的範例是**核准**閘道，使用者必須在 CodeCatalyst 主控台中提交核准，工作流程執行才能繼續。
您可以在工作流程中的動作序列之間或在第一個動作之前新增閘道 （在**來源**下載之後立即執行）。如果您需要，也可以在最後一個動作之後新增閘道。
如需閘道的詳細資訊，請參閱 [閘道工作流程執行](workflows-gates.md)。
## 報告
*報告*包含工作流程執行期間所發生測試的詳細資訊。您可以建立測試報告、程式碼涵蓋範圍報告、軟體合成分析報告和靜態分析報告等報告。您可以使用報告來協助對工作流程期間的問題進行疑難排解。如果您有許多來自多個工作流程的報告，您可以使用您的報告來檢視趨勢和失敗率，以協助您最佳化應用程式和部署組態。
如需報告的詳細資訊，請參閱 [品質報告類型](test-workflow-actions.md#test-reporting)。
## 執行
*執行*是工作流程的單一迭代。在執行期間，CodeCatalyst 會執行工作流程組態檔中定義的動作，並輸出相關的日誌、成品和變數。
如需執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
## 來源
*來源*也稱為*輸入來源*，是[工作流程動作](workflows-actions.md)所連接的來源儲存庫，以取得執行其操作所需的檔案。例如，工作流程動作可能會連線到來源儲存庫，以取得應用程式來源檔案，以建置應用程式。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
## Variables
*變數*是金鑰值對，其中包含您可以在 Amazon CodeCatalyst 工作流程中參考的資訊。工作流程執行時，變數的值部分會取代為實際值。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
## 工作流程觸發條件
*工作流程觸發*或只是*觸發*，可讓您在特定事件發生時自動啟動工作流程執行，例如程式碼推送。您可能想要設定觸發條件，讓您的軟體開發人員無需透過 CodeCatalyst 主控台手動啟動工作流程執行。
您可以使用三種類型的觸發：
+ **推送** – 程式碼推送觸發會在推送遞交時啟動工作流程執行。
+ **提取請求** – 提取請求觸發會在建立、修訂或關閉提取請求時啟動工作流程執行。
+ **排程** – 排程觸發程序會導致工作流程執行從您定義的排程開始。考慮使用排程觸發條件來執行軟體的夜間建置，以便軟體開發人員可以在隔天早上使用最新的建置。
您可以單獨使用推送、提取請求和排程觸發，或在相同的工作流程中結合使用。
觸發是選用的，如果您未設定任何 ，您只能手動啟動工作流程。
關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
# 工作流程入門
在本教學課程中，您將了解如何建立和設定您的第一個工作流程。
**提示**
偏好從預先設定的工作流程開始？ 請參閱 [使用藍圖建立專案](projects-create.md#projects-create-console-template)，其中包含使用正常運作的工作流程、範例應用程式和其他資源設定專案的指示。
**Topics**
+ [先決條件](#get-started-create-workflow-prerequisites)
+ [步驟 1：建立和設定您的工作流程](#get-started-create-workflow-create)
+ [步驟 2：使用遞交儲存工作流程](#get-started-create-workflow-commit)
+ [步驟 3：檢視執行結果](#get-started-create-workflow-results)
+ [(選用) 步驟 4：清理](#get-started-create-workflow-cleanup)
## 先決條件
開始之前：
+ 您需要 CodeCatalyst **空間**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在 CodeCatalyst 空間中，您需要一個名為 的空專案：
```
codecatalyst-project
```
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
+ 在專案中，您需要名為 的 CodeCatalyst **儲存庫**：
```
codecatalyst-source-repository
```
如需詳細資訊，請參閱[建立來源儲存庫](source-repositories-create.md)。
**注意**
如果您有現有的專案和來源儲存庫，您可以使用它們；不過，在本教學課程結束時，建立新的專案和來源儲存庫可讓您更輕鬆地進行清除。
## 步驟 1：建立和設定您的工作流程
在此步驟中，您會建立和設定工作流程，在進行變更時自動建置和測試您的原始程式碼。
**建立工作流程**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
工作流程定義檔案會出現在 CodeCatalyst 主控台的 YAML 編輯器中。
**設定您的工作流程**
您可以在**視覺化**編輯器或 **YAML** 編輯器中設定工作流程。讓我們從 YAML 編輯器開始，然後切換到視覺化編輯器。
1. 選擇 **\$1 動作**以查看您可以新增至工作流程的工作流程動作清單。
1. 在**建置**動作中，選擇 **\$1** 將動作的 YAML 新增至工作流程定義檔案。您的工作流程現在如下所示。
```
Name: Workflow_fe47
SchemaVersion: "1.0"
# Optional - Set automatic triggers.
Triggers:
- Type: Push
Branches:
- main
# Required - Define action configurations.
Actions:
Build_f0:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource # This specifies that the action requires this workflow as a source
Outputs:
AutoDiscoverReports:
Enabled: true
# Use as prefix for the report files
ReportNamePrefix: rpt
Configuration:
Steps:
- Run: echo "Hello, World!"
- Run: echo "" >> report.xml
- Run: echo "" >> report.xml
- Run: echo "" >> report.xml
```
工作流程會將`WorkflowSource`來源儲存庫中的檔案複製到執行 `Build_f0`動作的運算機器、列印`Hello, World!`至日誌、探索運算機器上的測試報告，並將它們輸出至 CodeCatalyst 主控台**的報告**頁面。
1. 選擇**視覺化**，在視覺化編輯器中檢視工作流程定義檔案。視覺化編輯器中的欄位可讓您設定 YAML 編輯器中顯示的 YAML 屬性。
## 步驟 2：使用遞交儲存工作流程
在此步驟中，您會儲存變更。由於工作流程會儲存為儲存庫中的`.yaml`檔案，因此您可以使用遞交儲存變更。
**遞交工作流程變更**
1. （選用） 選擇**驗證**，以確保工作流程的 YAML 程式碼有效。
1. 選擇 **Commit** (遞交)。
1. 在**工作流程檔案名稱**中，輸入工作流程組態檔案的名稱，例如 **my-first-workflow**。
1. 在**遞交訊息**中，輸入訊息以識別您的遞交，例如 **create my-first-workflow.yaml**。
1. 在**儲存庫**中，選擇您要在 () 中儲存工作流程的儲存庫`codecatalyst-repository`。
1. 在**分支名稱**中，選擇您要在 () 中儲存工作流程的分支`main`。
1. 選擇 **Commit** (遞交)。
您的新工作流程會出現在工作流程清單中。可能需要幾分鐘的時間才會顯示。
由於工作流程會與遞交一起儲存，而且工作流程已設定程式碼推送觸發，因此儲存工作流程會自動啟動工作流程執行。
## 步驟 3：檢視執行結果
在此步驟中，您會導覽至從遞交開始的執行，並檢視結果。
**檢視執行結果**
1. 選擇工作流程的名稱，例如 `Workflow_fe47`。
顯示來源儲存庫 (**WorkflowSource**) 標籤和建置動作 （例如 **Build\$1f0**) 的工作流程圖表。
1. 在工作流程執行圖表中，選擇建置動作 （例如 **Build\$1f0**)。
1. 檢閱**日誌**、**報告**、**組態**和**變數**索引標籤的內容。這些索引標籤會顯示建置動作的結果。
如需詳細資訊，請參閱[檢視建置動作的結果](build-view-results.md)。
## (選用) 步驟 4：清理
在此步驟中，您會清除在本教學課程中建立的資源。
**刪除資源**
+ 如果您已為此教學課程建立新的專案，請將其刪除。如需說明，請參閱[刪除專案](projects-delete.md)。刪除專案也會刪除來源儲存庫和工作流程。
# 使用工作流程建置
您可以使用 [CodeCatalyst 工作流程](workflow.md)來建置應用程式和其他資源。
**Topics**
+ [如何建置應用程式？](#build-how-to)
+ [建置動作的優點](#build-benefits)
+ [組建動作的替代方案](#build-alternatives)
+ [新增建置動作](build-add-action.md)
+ [檢視建置動作的結果](build-view-results.md)
+ [教學課程：將成品上傳至 Amazon S3](build-deploy.md)
+ [建置和測試動作 YAML](build-action-ref.md)
## 如何建置應用程式？
若要在 CodeCatalyst 中建置應用程式或資源，您必須先建立工作流程，然後在其中指定建置動作。
*建置動作*是工作流程建置區塊，可編譯您的原始程式碼、執行單元測試，並產生準備好部署的成品。
您可以使用 CodeCatalyst 主控台的視覺化編輯器或 YAML 編輯器，將建置動作新增至工作流程。
建置應用程式或資源的高階步驟如下所示。
**建置應用程式 （高階任務）**
1. 在 CodeCatalyst 中，您可以為要建置的應用程式**新增原始程式碼**。如需詳細資訊，請參閱[將原始程式碼存放在 CodeCatalyst 中專案的儲存庫中](source-repositories.md)。
1. 在 CodeCatalyst 中，您可以**建立工作流程**。工作流程是您定義如何建置、測試和部署應用程式的地方。如需詳細資訊，請參閱[工作流程入門](workflows-getting-started.md)。
1. （選用） 在工作流程中，您可以**新增觸發**，指出會導致工作流程自動啟動的事件。如需詳細資訊，請參閱[使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)
1. 在工作流程中，您可以新增**建置動作**，以編譯和封裝您的應用程式或資源原始碼。或者，如果您不想將測試或部署動作用於這些目的，您也可以進行建置動作執行單位測試、產生報告和部署應用程式。如需測試和部署動作的詳細資訊，請參閱[新增建置動作](build-add-action.md)。
1. （選用） 在工作流程中，您可以**新增測試動作**和**部署動作**，以測試和部署您的應用程式或資源。您可以從數個預先設定的動作中選擇，將您的應用程式部署到不同的目標，例如 Amazon ECS。如需詳細資訊，請參閱 [使用工作流程進行測試使用工作流程進行測試](test-workflow-actions.md) 和 [使用工作流程部署使用工作流程部署](deploy.md)。
1. 您可以透過觸發手動或自動**啟動工作流程**。工作流程會依序執行建置、測試和部署動作，以建置、測試和部署您的應用程式和資源至目標。如需詳細資訊，請參閱[手動啟動工作流程執行](workflows-manually-start.md)。
## 建置動作的優點
在工作流程中使用建置動作具有下列優點：
+ **完全受管** – 建置動作不需要設定、修補、更新和管理您自己的建置伺服器。
+ **隨需** – 建置動作會隨需擴展以符合您的建置需求。您只需針對實際使用的組建分鐘數付費。如需詳細資訊，請參閱[設定運算和執行時間映像](workflows-working-compute.md)。
+ **立即可用** – CodeCatalyst 包含預先封裝的執行時間環境 Docker 映像，用於執行所有工作流程動作，包括建置動作。這些映像具有預先設定的實用工具，可用於建置 AWS CLI 和 Node.js 等應用程式。您可以將 CodeCatalyst 設定為使用您從公有或私有登錄檔提供的建置映像。如需詳細資訊，請參閱[指定執行時間環境映像](build-images.md)。
## 組建動作的替代方案
如果您使用建置動作來部署應用程式，請考慮改用 CodeCatalyst *部署動作*。部署動作會執行behind-the-scenes組態，如果您使用建置動作，則必須手動寫入這些組態。如需可用部署動作的詳細資訊，請參閱 [部署動作的清單](deploy.md#deploy-concepts-action-supported)。
您也可以使用 AWS CodeBuild 來建置應用程式。如需詳細資訊，請參閱[什麼是 CodeBuild？](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html)。
# 新增建置動作
使用下列程序將建置動作新增至 CodeCatalyst 工作流程。
------
#### [ Visual ]
**使用視覺化編輯器新增建置動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**動作**。
1. 在**動作**中，選擇**建置**。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [建置和測試動作 YAML](build-action-ref.md)。此參考提供每個欄位 （和對應的 YAML 屬性值） 的詳細資訊，如 YAML 和視覺化編輯器所示。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增建置動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 選擇**動作**。
1. 在**動作**中，選擇**建置**。
1. 根據您的需求修改 YAML 程式碼中的屬性。中會提供每個可用屬性的說明[建置和測試動作 YAML](build-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 組建動作定義
建置動作定義為工作流程定義檔案內的一組 YAML 屬性。如需這些屬性的詳細資訊，請參閱 [建置和測試動作 YAML](build-action-ref.md) 中的 [工作流程 YAML 定義](workflow-reference.md)。
# 檢視建置動作的結果
使用下列指示來檢視建置動作的結果，包括產生的日誌、報告和變數。
**檢視建置動作的結果**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程圖表中，選擇建置動作的名稱，例如**建置**。
1. 若要檢視建置執行的日誌，請選擇**日誌**。隨即顯示各種建置階段的日誌。您可以視需要展開或摺疊日誌。
1. 若要檢視建置動作產生的測試報告，請選擇**報告**，或在導覽窗格中，選擇**報告**。如需詳細資訊，請參閱[品質報告類型](test-workflow-actions.md#test-reporting)。
1. 若要檢視用於建置動作的組態，請選擇**組態**。如需詳細資訊，請參閱[新增建置動作](build-add-action.md)。
1. 若要檢視建置動作所使用的變數，請選擇**變數**。如需詳細資訊，請參閱[在工作流程中使用變數](workflows-working-with-variables.md)。
# 教學課程：將成品上傳至 Amazon S3
在本教學課程中，您將了解如何使用包含幾個[建置動作](workflows-concepts.md#workflows-concepts-actions)的 Amazon CodeCatalyst 工作流程，將成品上傳至 Amazon S3 儲存貯體。 CodeCatalyst [工作流程](workflows-concepts.md#workflows-concepts-workflows) 這些動作會在工作流程開始時串聯執行。第一個建置動作會產生兩個檔案 `Hello.txt`和 `Goodbye.txt`，並將其封裝成建置成品。第二個建置動作會將成品上傳至 Amazon S3。您將設定工作流程，在每次將遞交推送至來源儲存庫時執行。
**Topics**
+ [先決條件](#build-deploy-tut-prereqs)
+ [步驟 1：建立 AWS 角色](#build-deploy-tut-role)
+ [步驟 2：建立 Amazon S3 儲存貯體](#build-deploy-tut-artifact)
+ [步驟 3：建立來源儲存庫](#deploy-tut-lambda-cfn-source)
+ [步驟 4：建立工作流程](#build-deploy-tut-workflow.title)
+ [步驟 5：驗證結果](#build-deploy.s3.verify)
+ [清除](#deploy-tut-lambda-cfn-clean-up)
## 先決條件
開始之前，您必須準備好以下事項：
+ 您需要具有連線 AWS 帳戶的 CodeCatalyst **空間**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在您的空間中，您需要一個名為 的空專案：
```
codecatalyst-artifact-project
```
使用**從頭開始**選項來建立此專案。
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
+ 在專案中，您需要名為 的 CodeCatalyst **環境**：
```
codecatalyst-artifact-environment
```
設定此環境，如下所示：
+ 選擇任何類型的，例如**開發**。
+ 將您的帳戶連接到該 AWS 帳戶。
+ 針對**預設 IAM 角色**，選擇任何角色。稍後您將指定不同的角色。
如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
## 步驟 1：建立 AWS 角色
在此步驟中，您會建立 IAM AWS 角色，稍後會指派給工作流程中的建置動作。此角色會授予 CodeCatalyst 建置動作許可，以存取 AWS 您的帳戶並寫入存放成品的 Amazon S3。角色稱為**建置角色**。
**注意**
如果您已經有為另一個教學課程建立的建置角色，您也可以將其用於此教學課程。只要確定它具有下列程序中顯示的許可和信任政策即可。
如需 IAM 角色的詳細資訊，請參閱*AWS AWS Identity and Access Management 《 使用者指南*》中的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
**建立建置角色**
1. 建立角色的政策，如下所示：
1. 登入 AWS。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇**政策**。
1. 選擇 **Create policy** (建立政策)。
1. 請選擇 **JSON** 標籤。
1. 刪除現有的程式碼。
1. 貼上以下程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:ListBucket"
],
"Resource": "*"
}
]
}
```
------
**注意**
第一次使用角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用後縮小政策的範圍。
```
"Resource": "*"
```
1. 選擇下**一步：標籤**。
1. 選擇下**一步：檢閱**。
1. 在**名稱**中，輸入：
```
codecatalyst-s3-build-policy
```
1. 選擇**建立政策**。
您現在已建立許可政策。
1. 建立建置角色，如下所示：
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 選擇**自訂信任政策**。
1. 刪除現有的自訂信任政策。
1. 新增下列自訂信任政策：
1. 選擇**下一步**。
1. 在**許可政策**中，搜尋`codecatalyst-s3-build-policy`並選取其核取方塊。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-s3-build-role
```
1. 針對**角色描述**，輸入：
```
CodeCatalyst build role
```
1. 選擇建**立角色**。
您現在已建立具有信任政策和許可政策的建置角色。
## 步驟 2：建立 Amazon S3 儲存貯體
在此步驟中，您會建立 Amazon S3 儲存貯體，其中會上傳 `Hello.txt`和 `Goodbye.txt`成品。
**建立 Amazon S3 儲存貯體**
1. 開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 在主窗格中，選擇**建立儲存貯**體。
1. 針對**儲存貯體名稱**，輸入：
```
codecatalyst-artifact-bucket
```
1. 對於 **AWS 區域**，選擇一個區域。本教學假設您選擇了**美國西部 （奧勒岡） us-west-2**。如需 Amazon S3 支援之區域的相關資訊，請參閱《》中的 [Amazon Simple Storage Service 端點和配額](https://docs.aws.amazon.com/general/latest/gr/s3.html)*AWS 一般參考*。
1. 在頁面底部，選擇**建立儲存貯**體。
1. 複製您剛建立的儲存貯體名稱，例如：
```
codecatalyst-artifact-bucket
```
您現在在美國西部 （奧勒岡） us-west-2 區域中建立了名為 **codecatalyst-artifact-bucket**的儲存貯體。
## 步驟 3：建立來源儲存庫
在此步驟中，您會在 CodeCatalyst 中建立來源儲存庫。此儲存庫用於存放教學課程的工作流程定義檔案。
如需來源儲存庫的詳細資訊，請參閱 [建立來源儲存庫](source-repositories-create.md)。
**建立來源儲存庫**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 導覽至您的專案 `codecatalyst-artifact-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇**新增儲存庫**，然後選擇**建立儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
codecatalyst-artifact-source-repository
```
1. 選擇**建立**。
您現在已建立名為 的儲存庫`codecatalyst-artifact-source-repository`。
## 步驟 4：建立工作流程
在此步驟中，您會建立工作流程，其中包含下列循序執行的建置區塊：
+ 觸發條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。如需觸發程序的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ 名為 的建置動作 `GenerateFiles` – 在觸發時，`GenerateFiles`動作會建立兩個檔案 `Hello.txt`和 `Goodbye.txt`，並將它們封裝成名為 的輸出成品`codecatalystArtifact`。
+ 另一個名為 的建置動作 `Upload` – `GenerateFiles`動作完成時， `Upload`動作會執行 AWS CLI 命令，將 `codecatalystArtifact`和來源儲存庫中的檔案`aws s3 sync`上傳至 Amazon S3 儲存貯體。在 CodeCatalyst 運算平台上 AWS CLI 預先安裝並預先設定 ，因此您不需要安裝或設定它。
如需 CodeCatalyst 運算平台上預先封裝軟體的詳細資訊，請參閱 [指定執行時間環境映像](build-images.md)。如需 AWS CLI`aws s3 sync`命令的詳細資訊，請參閱《 *AWS CLI 命令參考*》中的[同步](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)。
如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
**建立工作流程**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML 程式碼：
**注意**
在接下來的 YAML 程式碼中，您可以視需要省略 `Connections:`區段。如果您省略本節，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含 中所述的許可和信任政策[步驟 1：建立 AWS 角色](#build-deploy-tut-role)。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
```
Name: codecatalyst-artifact-workflow
SchemaVersion: 1.0
Triggers:
- Type: Push
Branches:
- main
Actions:
GenerateFiles:
Identifier: aws/build@v1
Configuration:
Steps:
# Create the output files.
- Run: echo "Hello, World!" > "Hello.txt"
- Run: echo "Goodbye!" > "Goodbye.txt"
Outputs:
Artifacts:
- Name: codecatalystArtifact
Files:
- "**/*"
Upload:
Identifier: aws/build@v1
DependsOn:
- GenerateFiles
Environment:
Name: codecatalyst-artifact-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-s3-build-role
Inputs:
Artifacts:
- codecatalystArtifact
Configuration:
Steps:
# Upload the output artifact to the S3 bucket.
- Run: aws s3 sync . s3://codecatalyst-artifact-bucket
```
在上述程式碼中，取代：
+ *codecatalyst-artifact-environment*，其中包含您在 中建立的環境名稱[先決條件](#build-deploy-tut-prereqs)。
+ *codecatalyst-account-connection*，其中包含您在 中建立的帳戶連線名稱[先決條件](#build-deploy-tut-prereqs)。
+ *codecatalyst-s3-build-role*，其中包含您在 中建立的建置角色名稱[步驟 1：建立 AWS 角色](#build-deploy-tut-role)。
+ *codecatalyst-artifact-bucket*，內含您在 中建立的 Amazon S3 名稱[步驟 2：建立 Amazon S3 儲存貯體](#build-deploy-tut-artifact)。
如需此檔案中屬性的相關資訊，請參閱 [建置和測試動作 YAML](build-action-ref.md)。
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇 **Commit** (遞交)。
1. 在**遞交工作流程**對話方塊中，輸入下列內容：
1. 對於**工作流程檔案名稱**，請保留預設值 `codecatalyst-artifact-workflow`。
1. 針對**遞交訊息**，輸入：
```
add initial workflow file
```
1. 針對**儲存庫**，選擇 **codecatalyst-artifact-source-repository**。
1. 針對**分支名稱**，選擇**主要**。
1. 選擇 **Commit** (遞交)。
您現在已建立工作流程。由於工作流程頂端定義的觸發條件，工作流程執行會自動啟動。具體而言，當您將`codecatalyst-artifact-workflow.yaml`檔案遞交 （並推送） 到您的來源儲存庫時，觸發會啟動工作流程執行。
**檢視進行中工作流程執行**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇您剛建立的工作流程：`codecatalyst-artifact-workflow`。
1. 選擇 **GenerateFiles** 以查看第一個建置動作進度。
1. 選擇**上傳**以查看第二個建置動作進度。
1. 當**上傳**動作完成時，請執行下列動作：
+ 如果工作流程執行成功，請前往下一個程序。
+ 如果工作流程執行失敗，請選擇**日誌**來疑難排解問題。
## 步驟 5：驗證結果
工作流程執行後，請前往 Amazon S3 服務並查看您的 *codecatalyst-artifact-bucket* 儲存貯體。現在應該包含下列檔案和資料夾：
```
.
|— .aws/
|— .git/
|Goodbye.txt
|Hello.txt
|REAME.md
```
上傳 `Goodbye.txt`和 `Hello.txt` 檔案是因為它們是`codecatalystArtifact`成品的一部分。`.aws/`、 和 `README.md` 檔案已上傳`.git/`，因為它們位於您的來源儲存庫中。
## 清除
在 CodeCatalyst 和 中清除 AWS ，以避免支付這些服務的費用。
**在 CodeCatalyst 中清除**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 刪除`codecatalyst-artifact-source-repository`來源儲存庫。
1. 刪除`codecatalyst-artifact-workflow`工作流程。
**在 中清除 AWS**
1. 在 Amazon S3 中清除，如下所示：
1. 開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 刪除儲存`codecatalyst-artifact-bucket`貯體中的檔案。
1. 刪除儲存`codecatalyst-artifact-bucket`貯體。
1. 在 IAM 中清除，如下所示：
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 刪除`codecatalyst-s3-build-policy`。
1. 刪除`codecatalyst-s3-build-role`。
# 建置和測試動作 YAML
以下是建置和測試動作的 YAML 定義。有兩個動作有一個參考，因為其 YAML 屬性非常類似。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
在下列程式碼中選擇 YAML 屬性，以查看描述。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素會與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
action-name:
Identifier: aws/build@v1 | aws/managed-test@v1
DependsOn:
- dependent-action-name-1
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Caching:
FileCaching:
key-name-1:
Path: file1.txt
RestoreKeys:
- restore-key-1
Inputs:
Sources:
- source-name-1
- source-name-2
Artifacts:
- artifact-name
Variables:
- Name: variable-name-1
Value: variable-value-1
- Name: variable-name-2
Value: variable-value-2
Outputs:
Artifacts:
- Name: output-artifact-1
Files:
- build-output/artifact-1.jar
- "build-output/build*"
- Name: output-artifact-2
Files:
- build-output/artifact-2.1.jar
- build-output/artifact-2.2.jar
Variables:
- variable-name-1
- variable-name-2
AutoDiscoverReports:
Enabled: true | false
ReportNamePrefix: AutoDiscovered
IncludePaths:
- "**/*"
ExcludePaths:
- node_modules/cdk/junit.xml
SuccessCriteria:
PassRate: percent
LineCoverage: percent
BranchCoverage: percent
Vulnerabilities:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisBug:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisSecurity:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisQuality:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisFinding:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
Reports:
report-name-1:
Format: format
IncludePaths:
- "*.xml"
ExcludePaths:
- report2.xml
- report3.xml
SuccessCriteria:
PassRate: percent
LineCoverage: percent
BranchCoverage: percent
Vulnerabilities:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisBug:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisSecurity:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisQuality:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
StaticAnalysisFinding:
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
Number: whole-number
Configuration:
Container:
Registry: registry
Image: image
Steps:
- Run: "step 1"
- Run: "step 2"
Packages:
NpmConfiguration:
PackageRegistries:
- PackagesRepository: package-repository
Scopes:
- "@scope"
ExportAuthorizationToken: true | false
```
## action-name
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
對應的 UI：組態索引標籤/**動作名稱**
## Identifier
(*action-name*/**Identifier**)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
使用 `aws/build@v1`進行建置動作。
使用 `aws/managed-test@v1` 進行測試動作。
對應的 UI：工作流程圖表/Action-name/*aws/build@v1\$1aws/managed-test@v1* 標籤
## DependsOn
(*action-name*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*action-name*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*action-name*/Compute/****Type)
（如果[Compute](#build.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/**運算類型**
## Fleet
(*action-name*/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`。
對應的 UI：組態索引標籤/**運算機群**
## Timeout
(*action-name*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Environment
(*action-name*/**Environment**)
(選用)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將 動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*action-name*/Environment/**Name**)
(選用)
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*action-name*/Environment/**Connections**)
(選用)
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態tab/Environment/What **中是什麼？/三個點功能表/**切換角色**
## Name
(*action-name*/Environment/Connections/**Name**)
（如果[Connections](#build.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：組態tab/Environment/What在*我的環境中*？/三個點功能表/**切換角色**
## Role
(*action-name*/Environment/Connections/**Role**)
（如果[Connections](#build.environment.connections)包含 則為必要）
指定此動作用於在 Amazon S3 和 Amazon ECR 等 AWS 服務中存取和操作的 IAM 角色名稱。請確定此角色已新增至您 AWS 帳戶 空間中的連線。若要將 IAM 角色新增至帳戶連線，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
**注意**
您可以搭配此動作使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
**警告**
將許可限制為建置和測試動作所需的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
對應的 UI：組態tab/Environment/What**是什麼？/三個點功能表/**切換角色**
## Caching
(*action-name*/**Caching**)
(選用)
您可以在此區段中指定快取，以儲存磁碟上檔案，並在後續工作流程執行中從該快取還原這些檔案。
如需檔案快取的詳細資訊，請參閱 [在工作流程執行之間快取檔案](workflows-caching.md)。
對應的 UI：組態索引標籤/**檔案快取 - 選用**
## FileCaching
(*action-name*/Caching/**FileCaching**)
(選用)
區段，指定一系列快取的組態。
對應的 UI：組態索引標籤/檔案快取 - 選用/**新增快取**
## key-name-1
(*action-name*/Caching/FileCaching/***key-name-1***)
(選用)
指定主要快取屬性名稱的名稱。快取屬性名稱在工作流程中必須是唯一的。每個動作在 中最多可以有五個項目`FileCaching`。
對應的 UI：組態索引標籤/檔案快取 - 選用/新增快取/**金鑰**
## Path
(*action-name*/Caching/FileCaching/*key-name-1*/**Path**)
(選用)
指定快取的關聯路徑。
對應的 UI：組態索引標籤/檔案快取 - 選用/新增快取/**路徑**
## RestoreKeys
(*action-name*/Caching/FileCaching/*key-name-1*/**RestoreKeys**)
(選用)
找不到主要快取屬性時，指定要用作備用的還原金鑰。還原金鑰名稱在工作流程中必須是唯一的。每個快取在 中最多可以有五個項目`RestoreKeys`。
對應的 UI：組態索引標籤/檔案快取 - 選用/新增快取/**還原金鑰 - 選用**
## Inputs
(*action-name*/**Inputs**)
(選用)
`Inputs` 本節定義 動作在工作流程執行期間所需的資料。
**注意**
每個建置動作或測試動作最多允許四個輸入 （一個來源和三個成品）。變數不會計入此總計。
如果您需要參考位於不同輸入中的檔案 （例如來源和成品），則來源輸入是主要輸入，而成品是次要輸入。對次要輸入中檔案的參考需要特殊的字首，才能將其從主要輸入中消除。如需詳細資訊，請參閱[範例：參考多個成品中的檔案](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file)。
對應的 UI：**輸入**索引標籤
## Sources
(*action-name*/Inputs/**Sources**)
(選用)
指定代表 動作所需來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`，代表儲存工作流程定義檔案的來源儲存庫。
如果您省略來源，則必須在 下指定至少一個輸入成品`action-name/Inputs/Artifacts`。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：*無*
## Artifacts - input
(*action-name*/Inputs/**Artifacts**)
(選用)
指定您要提供作為此動作輸入之先前動作的成品。這些成品必須已在先前的動作中定義為輸出成品。
如果您未指定任何輸入成品，則必須在 下指定至少一個來源儲存庫`action-name/Inputs/Sources`。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
如果**成品 - 選用**下拉式清單無法使用 （視覺化編輯器），或者您在驗證 YAML (YAML 編輯器） 時在 中發生錯誤，可能是因為動作僅支援一個輸入。在此情況下，請嘗試移除來源輸入。
對應的 UI：輸入索引標籤/**成品 - 選用**
## Variables - input
(*action-name*/Inputs/**Variables**)
(選用)
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸入索引標籤/**變數 - 選用**
## Outputs
(*action-name*/**Outputs**)
(選用)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts - output
(*action-name*/Outputs/**Artifacts**)
(選用)
指定 動作產生的成品名稱。成品名稱在工作流程中必須是唯一的，且僅限於英數字元 (a-z、A-Z、0-9) 和底線 (\$1)。不允許使用空格、連字號 (-) 和其他特殊字元。您無法使用引號在輸出成品名稱中啟用空格、連字號和其他特殊字元。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/**成品**
## Name
(*action-name*/Outputs/Artifacts/**Name**)
（如果[Artifacts - output](#build.outputs.artifacts)包含 則為必要）
指定 動作產生的成品名稱。成品名稱在工作流程中必須是唯一的，且僅限於英數字元 (a-z、A-Z、0-9) 和底線 (\$1)。不允許使用空格、連字號 (-) 和其他特殊字元。您無法使用引號在輸出成品名稱中啟用空格、連字號和其他特殊字元。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出tab/Artifacts/New輸出/**建置成品名稱**
## Files
(*action-name*/Outputs/Artifacts/**Files**)
（如果[Artifacts - output](#build.outputs.artifacts)包含 則為必要）
指定 CodeCatalyst 在由 動作輸出的成品中包含的檔案。這些檔案在執行時由工作流程動作產生，也可在您的來源儲存庫中使用。檔案路徑可以位於來源儲存庫或先前動作的成品中，並與來源儲存庫或成品根相關。您可以使用 glob 模式來指定路徑。範例：
+ 若要指定位於建置位置根目錄或來源儲存庫位置的單一檔案，請使用 `my-file.jar`。
+ 若要在子目錄中指定單一檔案，請使用 `directory/my-file.jar`或 `directory/subdirectory/my-file.jar`。
+ 若要指定所有檔案，請使用 `"**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要在名為 的目錄中指定所有檔案和目錄`directory`，請使用 `"directory/**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要指定名為 目錄中的所有檔案`directory`，但不是其任何子目錄，請使用 `"directory/*"`。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
您可能需要將字首新增至檔案路徑，以指出要尋找該路徑的成品或來源。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)及[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：輸出tab/Artifacts/New輸出/**建置產生的檔案**
## Variables - output
(*action-name*/Outputs/**Variables**)
(選用)
指定您希望動作匯出的變數，以便可供後續動作使用。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸出索引標籤/變數/**新增變數**
## variable-name-1
(*action-name*/Outputs/Variables/*variable-name-1*)
(選用)
指定您要動作匯出的變數名稱。此變數必須已在相同動作的 `Inputs`或 `Steps`區段中定義。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸出tab/Variables/Add變數/**名稱**
## AutoDiscoverReports
(*action-name*/Outputs/**AutoDiscoverReports**)
(選用)
定義自動探索功能的組態。
當您啟用自動探索時，CodeCatalyst 會搜尋所有`Inputs`傳遞至動作本身所產生的所有檔案，尋找測試、程式碼涵蓋範圍和軟體合成分析 (SCA) 報告。對於找到的每個報告，CodeCatalyst 會將其轉換為 CodeCatalyst 報告。*CodeCatalyst 報告*是完全整合到 CodeCatalyst 服務的報告，可以透過 CodeCatalyst 主控台檢視和操作。
**注意**
根據預設，自動探索功能會檢查所有檔案。您可以使用 [IncludePaths](#build.reports.includepaths)或 [ExcludePaths](#build.reports.excludepaths) 屬性來限制要檢查哪些檔案。
對應的 UI：輸出索引標籤/報告/**自動探索報告**
## Enabled
(*action-name*/Outputs/AutoDiscoverReports/**Enabled**)
(選用)
啟用或停用自動探索功能。
有效值為 `true` 或 `false`。
如果省略 `Enabled` ，則預設值為 `true`。
對應的 UI：輸出索引標籤/報告/**自動探索報告**
## ReportNamePrefix
(*action-name*/Outputs/AutoDiscoverReports/**ReportNamePrefix**)
（如果 [AutoDiscoverReports](#build.outputs.autodiscover) 已包含並啟用，則為必要項目）
指定 CodeCatalyst 在找到的所有報告前面加上的字首，以命名其關聯的 CodeCatalyst 報告。例如，如果您指定字首 `AutoDiscovered`，而 CodeCatalyst 會自動探索兩個測試報告 `TestSuiteOne.xml`和 `TestSuiteTwo.xml`，則相關聯的 CodeCatalyst 報告將命名為 `AutoDiscoveredTestSuiteOne`和 `AutoDiscoveredTestSuiteTwo`。
對應的 UI：輸出索引標籤/報告/**字首名稱**
## IncludePaths
(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)
（如果 [AutoDiscoverReports](#build.outputs.autodiscover)包含並啟用，或如果 [Reports](#test.configuration.reports) 包含，則為必要）
指定 CodeCatalyst 在搜尋原始報告時包含的檔案和檔案路徑。例如，如果您指定 `"/test/report/*"`，CodeCatalyst 會搜尋尋找`/test/report/*`目錄的動作所使用的整個[建置映像](build-images.md)。找到該目錄時，CodeCatalyst 接著會尋找該目錄中的報告。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
如果省略此屬性，則預設值為 `"**/*"`，表示搜尋包含所有路徑中的所有檔案。
**注意**
對於手動設定的報告， `IncludePaths` 必須是符合單一檔案的 glob 模式。
對應的 UI：
+ 輸出tab/Reports/Auto探索reports/Include/exclude路徑/**包含路徑**
+ 輸出tab/Reports/Manually設定報告/*報告名稱-1*/包含/排除路徑/**包含路徑**
## ExcludePaths
(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**ExcludePaths**)
(選用)
指定 CodeCatalyst 在搜尋原始報告時排除的檔案和檔案路徑。例如，如果您指定 `"/test/my-reports/**/*"`，CodeCatalyst 不會搜尋 `/test/my-reports/`目錄中的檔案。若要忽略目錄中的所有檔案，請使用 `**/*` glob 模式。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
對應的 UI：
+ 輸出tab/Reports/Auto探索reports/Include/exclude路徑/**排除路徑**
+ 輸出tab/Reports/Manually設定報告/*報告名稱-1*/包含/排除路徑/**排除路徑**
## SuccessCriteria
(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**SuccessCriteria**)
(選用)
指定測試、程式碼涵蓋範圍、軟體合成分析 (SCA) 和靜態分析 (SA) 報告的成功條件。
如需詳細資訊，請參閱[設定報告的成功條件](test-config-action.md#test.success-criteria)。
對應的 UI：輸出索引標籤/報告/**成功條件**
## PassRate
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**PassRate**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)
(選用)
指定測試報告中必須傳遞的測試百分比，相關 CodeCatalyst 報告才能標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。通過率條件僅適用於測試報告。如需測試報告的詳細資訊，請參閱 [測試報告](test-workflow-actions.md#test-reports)。
對應的 UI：輸出tab/Reports/Success條件/**通過率**
## LineCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**LineCoverage**)
(選用)
指定程式碼涵蓋範圍報告中必須涵蓋的行數百分比，以便將相關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。明細涵蓋範圍條件只會套用至程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
對應的 UI：輸出tab/Reports/Success條件/**行涵蓋**範圍
## BranchCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**BranchCoverage**)
(選用)
指定程式碼涵蓋範圍報告中必須涵蓋的分支百分比，以便將關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。分支涵蓋範圍條件僅適用於程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
對應的 UI：輸出tab/Reports/Success條件/**分支涵蓋範圍**
## Vulnerabilities
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)
(選用)
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SCA 報告中允許的漏洞數量和嚴重性上限。若要指定漏洞，您必須指定：
+ 您要包含在計數中的漏洞最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 漏洞將會很高。
+ 您想要允許之指定嚴重性的漏洞數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
漏洞條件只會套用至 SCA 報告。如需 SCA 報告的詳細資訊，請參閱 [軟體合成分析報告](test-workflow-actions.md#test-sca-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
對應的 UI：輸出tab/Reports/Success條件/**漏洞**
## StaticAnalysisBug
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisBug**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisBug**)
(選用)
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的錯誤數量和嚴重性上限。若要指定錯誤，您必須指定：
+ 您要包含在計數中錯誤的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 錯誤將會很高。
+ 您想要允許之指定嚴重性的錯誤數目上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
錯誤條件僅適用於 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
對應的 UI：輸出tab/Reports/Success條件/**錯誤**
## StaticAnalysisSecurity
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisSecurity**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisSecurity**)
(選用)
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的安全漏洞數量和嚴重性上限。若要指定安全漏洞，您必須指定：
+ 您要包含在計數中的安全漏洞的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 安全漏洞將會很高。
+ 您想要允許之指定嚴重性的安全漏洞數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
安全漏洞條件僅適用於 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
對應的 UI：輸出tab/Reports/Success條件/**安全漏洞**
## StaticAnalysisQuality
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisQuality**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisQuality**)
(選用)
針對要標示為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的品質問題數量和嚴重性上限。若要指定品質問題，您必須指定：
+ 您要包含在計數中品質問題的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和`CRITICAL`品質問題將會很高。
+ 您想要允許之指定嚴重性的品質問題數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
品質問題條件僅適用於 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
對應的 UI：輸出tab/Reports/Success條件/**品質問題**
## StaticAnalysisFinding
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisFinding**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisFinding**)
(選用)
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的問題清單數量和嚴重性上限。若要指定問題清單，您必須指定：
+ 您要包含在計數中之問題清單的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL`問題清單將會加長。
+ 您想要允許之指定嚴重性的問題清單數目上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
調查結果只會套用至 SARIF SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
對應的 UI：輸出tab/Reports/Success條件/**調查結果**
## Reports
(*action-name*/Outputs/**Reports**)
(選用)
指定測試報告組態的區段。
對應的 UI：輸出索引標籤/**報告**
## report-name-1
(*action-name*/Outputs/Reports/**report-name-1**)
（如果[Reports](#test.configuration.reports)包含 則為必要）
您要提供給 CodeCatalyst 報告的名稱，該報告將從原始報告產生。
對應的 UI：輸出tab/Reports/Manually設定報告/**報告名稱**
## Format
(*action-name*/Outputs/Reports/*report-name-1*/**Format**)
（如果[Reports](#test.configuration.reports)包含 則為必要）
指定您用於報告的檔案格式。可能的值如下。
+ 對於測試報告：
+ 針對 Cucumber JSON，指定 **Cucumber** （視覺化編輯器） 或 `CUCUMBERJSON`(YAML 編輯器）。
+ 對於 JUnit XML，指定 **JUnit** （視覺編輯器） 或 `JUNITXML`(YAML 編輯器）。
+ 對於 NUnit XML，指定 **NUnit** （視覺化編輯器） 或 `NUNITXML`(YAML 編輯器）。
+ 對於 NUnit 3 XML，指定 **NUnit3** （視覺化編輯器） 或 `NUNIT3XML`(YAML 編輯器）。
+ 針對 Visual Studio TRX，指定 **Visual Studio TRX** （視覺化編輯器） 或 `VISUALSTUDIOTRX`(YAML 編輯器）。
+ 針對 TestNG XML，指定 **TestNG** （視覺化編輯器） 或 `TESTNGXML`(YAML 編輯器）。
+ 對於程式碼涵蓋範圍報告：
+ 針對 Clover XML，指定 **Clover** （視覺化編輯器） 或 `CLOVERXML`(YAML 編輯器）。
+ 對於 Cobertura XML，指定 **Cobertura** （視覺編輯器） 或 `COBERTURAXML`(YAML 編輯器）。
+ 對於 JaCoCo XML，指定 **JaCoCo** （視覺編輯器） 或 `JACOCOXML`(YAML 編輯器）。
+ 對於 Simplecov 產生的 SimpleCov JSON，而非 [simplecov-json](https://github.com/vicentllongo/simplecov-json)，請指定 **Simplecov** （視覺化編輯器） 或 `SIMPLECOV`(YAML 編輯器）。 [https://github.com/simplecov-ruby/simplecov](https://github.com/simplecov-ruby/simplecov)
+ 對於軟體合成分析 (SCA) 報告：
+ 對於 SARIF，指定 **SARIF** （視覺編輯器） 或 `SARIFSCA`(YAML 編輯器）。
對應的 UI：輸出tab/Reports/Manually設定reports/Add/configure報告/*report-name-1*/**報告類型**和**報告格式**
## Configuration
(*action-name*/**Configuration**)
（必要） 您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## Container
(*action-name*/Configuration/**Container**)
(選用)
指定 動作用來完成其處理的 Docker 映像或*容器*。您可以指定 CodeCatalyst 隨附的其中一個[作用中映像](build-images.md#build-curated-images)，也可以使用自己的映像。如果您選擇使用自己的映像，它可以位於 Amazon ECR、Docker Hub 或其他登錄檔中。如果您未指定 Docker 映像，動作會使用其中一個作用中映像進行處理。如需預設使用哪些作用中映像的詳細資訊，請參閱 [作用中映像](build-images.md#build-curated-images)。
如需指定您自己的 Docker 映像的詳細資訊，請參閱 [將自訂執行期環境 Docker 映像指派給 動作](build-images.md#build-images-specify)。
對應的 UI：**執行期環境 Docker 映像 - 選用**
## Registry
(*action-name*/Configuration/Container/**Registry**)
（如果`Container`包含 則為必要）
指定儲存映像的登錄檔。有效值包含：
+ `CODECATALYST` (YAML 編輯器）
映像會存放在 CodeCatalyst 登錄檔中。
+ **Docker Hub** （視覺化編輯器） 或 `DockerHub`(YAML 編輯器）
映像會存放在 Docker Hub 映像登錄檔中。
+ **其他登錄**檔 （視覺化編輯器） 或 `Other`(YAML 編輯器）
映像會存放在自訂映像登錄檔中。您可以使用任何公開可用的登錄檔。
+ **Amazon Elastic Container Registry** （視覺化編輯器） 或 `ECR`(YAML 編輯器）
映像會存放在 Amazon Elastic Container Registry 映像儲存庫中。若要在 Amazon ECR 儲存庫中使用映像，此動作需要存取 Amazon ECR。若要啟用此存取權，您必須建立包含下列許可和自訂信任政策的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。（如果需要，您可以修改現有角色以包含許可和政策。)
IAM 角色必須在其角色政策中包含下列許可：
+ `ecr:BatchCheckLayerAvailability`
+ `ecr:BatchGetImage`
+ `ecr:GetAuthorizationToken`
+ `ecr:GetDownloadUrlForLayer`
IAM 角色必須包含下列自訂信任政策：
如需建立 IAM 角色的詳細資訊，請參閱《*IAM 使用者指南*》中的[使用自訂信任政策 （主控台） 建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)。
建立角色之後，您必須透過 環境將其指派給 動作。如需詳細資訊，請參閱[將環境與 動作建立關聯](deploy-environments-add-app-to-environment.md)。
對應的 UI：**Amazon Elastic Container Registry**、**Docker Hub** **和其他登錄**選項
## Image
(*action-name*/Configuration/Container/**Image**)
（如果`Container`包含 則為必要）
請指定下列其中一項：
+ 如果您使用`CODECATALYST`登錄檔，請將映像設定為下列其中一個[作用中映像](build-images.md#build-curated-images)：
+ `CodeCatalystLinux_x86_64:2024_03`
+ `CodeCatalystLinux_x86_64:2022_11`
+ `CodeCatalystLinux_Arm64:2024_03`
+ `CodeCatalystLinux_Arm64:2022_11`
+ `CodeCatalystLinuxLambda_x86_64:2024_03`
+ `CodeCatalystLinuxLambda_x86_64:2022_11`
+ `CodeCatalystLinuxLambda_Arm64:2024_03`
+ `CodeCatalystLinuxLambda_Arm64:2022_11`
+ `CodeCatalystWindows_x86_64:2022_11`
+ 如果您使用的是 Docker Hub 登錄檔，請將映像設定為 Docker Hub 映像名稱和選用標籤。
範例：`postgres:latest`
+ 如果您使用的是 Amazon ECR 登錄檔，請將映像設定為 Amazon ECR 登錄檔 URI。
範例：`111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`
+ 如果您使用自訂登錄檔，請將映像設定為自訂登錄檔預期的值。
對應的 UI：**執行期環境 docker 映像** （如果登錄檔是 `CODECATALYST`)、**Docker Hub 映像** （如果登錄檔是 **Docker Hub**)、**ECR 映像 URL** （如果登錄檔是 **Amazon Elastic Container Registry**) 和**映像 URL** （如果登錄檔是**其他登錄**檔）。
## Steps
(*action-name*/Configuration/**Steps**)
(必要)
指定要在 動作期間執行的 shell 命令，以安裝、設定和執行建置工具。
以下是如何建置 npm 專案的範例：
```
Steps:
- Run: npm install
- Run: npm run build
```
以下是如何指定檔案路徑的範例：
```
Steps:
- Run: cd $ACTION_BUILD_SOURCE_PATH_WorkflowSource/app && cat file2.txt
- Run: cd $ACTION_BUILD_SOURCE_PATH_MyBuildArtifact/build-output/ && cat file.txt
```
如需指定檔案路徑的詳細資訊，請參閱 [參考來源儲存庫檔案](workflows-sources-reference-files.md)和 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：組態索引標籤/**Shell 命令**
## Packages
(*action-name*/Configuration/**Packages**)
(選用)
您可以在此區段中指定 動作用來解析相依性的套件儲存庫。套件可讓您安全地存放和共用用於應用程式開發的軟體套件。
如需套件的詳細資訊，請參閱 [在 CodeCatalyst 中發佈和共用軟體套件](packages.md)。
對應的 UI：組態索引標籤/**套件**
## NpmConfiguration
(*action-name*/Configuration/Packages/**NpmConfiguration**)
（如果[Packages](#build.configuration.packages)包含 則為必要）
定義 npm 套件格式組態的區段。在工作流程執行期間， 動作會使用此組態。
如需 npm 套件組態的詳細資訊，請參閱 [使用 NPM](packages-npm.md)。
對應的 UI：組態tab/Packages/Add組態/**npm**
## PackageRegistries
(*action-name*/Configuration/Packages/NpmConfiguration/**PackageRegistries**)
（如果[Packages](#build.configuration.packages)包含 則為必要）
您可以在此區段定義一系列套件儲存庫的組態屬性。
對應的 UI：組態tab/Packages/Add組態/npm/**新增套件儲存庫**
## PackagesRepository
(*action-name*/Configuration/Packages/NpmConfiguration/PackageRegistries/**PackagesRepository**)
（如果[Packages](#build.configuration.packages)包含 則為必要）
指定您要動作使用的 CodeCatalyst *套件儲存庫*名稱。
如果您指定多個預設儲存庫，最後一個儲存庫將優先處理。
如需套件儲存庫的詳細資訊，請參閱 [套件儲存庫](packages-concepts.md#packages-concepts-repository)。
對應的 UI：組態tab/Packages/Addconfiguration/npm/Add套件儲存庫/**套件儲存庫**
## Scopes
(*action-name*/Configuration/Packages/NpmConfiguration/PackageRegistries/**Scopes**)
(選用)
指定您要在套件登錄檔中定義的一系列*範圍*。定義範圍時，指定的套件儲存庫會設定為所有列出範圍的登錄檔。如果透過 npm 用戶端請求具有 範圍的套件，則會使用該儲存庫，而不是預設值。每個範圍名稱都必須加上 "@" 字首。
如果您包含覆寫範圍，最後一個儲存庫將優先處理。
如果省略 `Scopes` ，則指定的套件儲存庫會設定為動作使用之所有套件的預設登錄檔。
如需範圍的詳細資訊，請參閱 [套件命名空間](packages-concepts.md#packages-concepts-package-namespaces)和[範圍套件](https://docs.npmjs.com/cli/v10/using-npm/scope)。
對應的 UI：組態tab/Packages/Addconfiguration/npm/Add套件儲存庫/**範圍 - 選用**
## ExportAuthorizationToken
(*action-name*/Configuration/Packages/**ExportAuthorizationToken**)
(選用)
啟用或停用匯出授權字符功能。如果啟用，匯出的授權字符可用於手動設定套件管理員，以使用 CodeCatalyst 套件儲存庫進行驗證。您可以使用字符做為可在 動作中參考的環境變數。
有效值為 `true` 或 `false`。
如果省略 `ExportAuthorizationToken` ，則預設值為 `false`。
如需匯出授權字符的詳細資訊，請參閱 [在工作流程動作中使用授權字符](workflows-package-export-token.md)。
對應的 UI：組態索引標籤/套件/**匯出授權字符**
# 使用工作流程進行測試
在 CodeCatalyst 中，您可以執行測試做為不同工作流程動作的一部分，例如建置和測試。這些工作流程動作都可以產生品質報告。*測試動作*是一種工作流程動作，可產生測試、程式碼涵蓋範圍、軟體合成分析和靜態分析報告。這些報告會顯示在 CodeCatalyst 主控台中。
**Topics**
+ [品質報告類型](#test-reporting)
+ [新增測試動作](test-add-action.md)
+ [檢視測試動作的結果](test-view-results.md)
+ [在 動作中略過失敗的測試](test.error-handling.md)
+ [與 universal-test-runner 整合](test.universal-test-runner.md)
+ [在 動作中設定品質報告](test-config-action.md)
+ [測試的最佳實務](test-best-practices.md)
+ [支援的 SARIF 屬性](test.sarif.md)
## 品質報告類型
Amazon CodeCatalyst 測試動作支援下列類型的品質報告。如需如何在 YAML 中格式化這些報告的範例，請參閱 [品質報告 YAML 範例](test-config-action.md#test.success-criteria-example)。
**Topics**
+ [測試報告](#test-reports)
+ [程式碼涵蓋範圍報告](#test-code-coverage-reports)
+ [軟體合成分析報告](#test-sca-reports)
+ [靜態分析報告](#test-static-analysis-reports)
### 測試報告
在 CodeCatalyst 中，您可以設定建置期間執行的單元測試、整合測試和系統測試。然後CodeCatalyst 可以建立包含測試結果的報告。
您可以使用測試報告來協助疑難排解測試的問題。如果您有來自多個組建的許多測試報告，您可以使用測試報告來檢視失敗率，以協助您最佳化組建。
您可以使用下列測試報告檔案格式：
+ 小黃瓜 JSON (.json)
+ JUnit XML (.xml)
+ NUnit XML (.xml)
+ NUnit3 XML (.xml)
+ TestNG XML (.xml)
+ Visual Studio TRX (.trx、.xml)
### 程式碼涵蓋範圍報告
在 CodeCatalyst 中，您可以為測試產生程式碼涵蓋範圍報告。CodeCatalyst 提供下列程式碼涵蓋範圍指標：
線路涵蓋範圍
測量您的測試涵蓋多少陳述式。陳述式是單一指示，不包含註解。
`line coverage = (total lines covered)/(total number of lines)`
分支涵蓋範圍
測量您的測試在控制結構的每個可能分支中涵蓋多少分支，例如 `if`或 `case`陳述式。
`branch coverage = (total branches covered)/(total number of branches)`
支援下列程式碼涵蓋範圍報告檔案格式：
+ JaCoCo XML (.xml)
+ SimpleCov JSON （由 [simplecov](https://github.com/simplecov-ruby/simplecov) 產生，而非 [simplecov-json](https://github.com/vicentllongo/simplecov-json)， .json)
+ Clover XML （第 3 版，.xml)
+ Cobertura XML (.xml)
+ LCOV (.info)
### 軟體合成分析報告
在 CodeCatalyst 中，您可以使用軟體合成分析 (SCA) 工具來分析應用程式的元件，並檢查已知的安全漏洞。您可以探索並剖析 SARIF 報告，其中詳細說明具有不同嚴重性的漏洞，以及修正這些漏洞的方法。從最嚴重到最不嚴重的有效嚴重性值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
支援下列 SCA 報告檔案格式：
+ SARIF (.sarif、.json)
### 靜態分析報告
您可以使用靜態分析 (SA) 報告來識別來源層級程式碼瑕疵。在 CodeCatalyst 中，您可以產生 SA 報告，以協助在部署程式碼之前解決問題。這些問題包括錯誤、安全漏洞、品質問題和其他漏洞。從最嚴重到最不嚴重的有效嚴重性值為：`CRITICAL`、`HIGH`、`LOW`、 `MEDIUM`和 `INFORMATIONAL`。
CodeCatalyst 提供下列 SA 指標：
錯誤
識別在原始程式碼中找到的許多可能錯誤。這些錯誤可能包括與記憶體安全相關的問題。以下是錯誤的範例。
```
// The while loop will inadvertently index into array x out-of-bounds
int x[64];
while (int n = 0; n <= 64; n++) {
x[n] = 0;
}
```
安全漏洞
識別在原始程式碼中找到的幾個可能的安全漏洞。這些安全漏洞可能包括以純文字儲存秘密字符等問題。
品質問題
識別來源碼中發現的許多可能品質問題。這些品質問題可能包括有關樣式慣例的問題。以下是品質問題的範例。
```
// The function name doesn't adhere to the style convention of camelCase
int SUBTRACT(int x, int y) {
return x-y
}
```
其他漏洞
識別在原始程式碼中找到的許多可能的其他漏洞。
CodeCatalyst 支援下列 SA 報告檔案格式：
+ PyLint (.py)
+ ESLint (.js、.jsx、.ts、.tsx)
+ SARIF (.sarif、.json)
# 新增測試動作
使用下列程序將測試動作新增至 CodeCatalyst 工作流程。
------
#### [ Visual ]
**使用視覺化編輯器新增測試動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**動作**。
1. 在**動作**中，選擇**測試**。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [建置和測試動作 YAML](build-action-ref.md)。此參考提供每個欄位 （和對應的 YAML 屬性值） 的詳細資訊，如 YAML 和視覺化編輯器所示。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增建置動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 選擇**動作**。
1. 在**動作**中，選擇**測試**。
1. 根據您的需求修改 YAML 程式碼中的屬性。中會提供每個可用屬性的說明[建置和測試動作 YAML](build-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 測試動作定義
測試動作定義為工作流程定義檔案內的一組 YAML 屬性。如需這些屬性的詳細資訊，請參閱 [建置和測試動作 YAML](build-action-ref.md) 中的 [工作流程 YAML 定義](workflow-reference.md)。
# 檢視測試動作的結果
使用下列指示來檢視測試動作的結果，包括產生的日誌、報告和變數。
**檢視測試動作的結果**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程圖表中，選擇測試動作的名稱，例如 **Test**。
1. 若要檢視動作產生的日誌，請選擇**日誌**。隨即顯示各種動作階段的日誌。您可以視需要展開或摺疊日誌。
1. 若要檢視測試動作產生的測試報告，請選擇**報告**，或在導覽窗格中，選擇**報告**。如需詳細資訊，請參閱[品質報告類型](test-workflow-actions.md#test-reporting)。
1. 若要檢視用於測試動作的組態，請選擇**組態**。如需詳細資訊，請參閱[新增測試動作](test-add-action.md)。
1. 若要檢視測試動作所使用的變數，請選擇**變數**。如需詳細資訊，請參閱[在工作流程中使用變數](workflows-working-with-variables.md)。
# 在 動作中略過失敗的測試
如果您的動作有多個測試命令，您可能想要允許動作中的後續測試命令執行，即使先前的命令失敗。例如，在下列命令中，您可能`test2`想要一律執行，即使 `test1` 故障也一樣。
```
Steps:
- Run: npm install
- Run: npm run test1
- Run: npm run test2
```
一般而言，當步驟傳回錯誤時，Amazon CodeCatalyst 會停止工作流程動作並將其標記為失敗。您可以將錯誤輸出重新導向至 ，以允許動作步驟繼續執行`null`。您可以將 `2>/dev/null`新增至 命令來執行此操作。在此修改中，上述範例會如下所示。
```
Steps:
- Run: npm install
- Run: npm run test1 2>/dev/null
- Run: npm run test2
```
在第二個程式碼片段中，將會接受`npm install`命令的狀態，但`npm run test1`命令傳回的任何錯誤都會遭到忽略。因此會執行 `npm run test2`命令。透過這樣做，無論是否發生錯誤，您都可以一次檢視這兩個報告。
# 與 universal-test-runner 整合
測試動作與開放原始碼命令列工具 整合`universal-test-runner`。 `universal-test-runner`使用[測試執行通訊協定](https://github.com/aws/universal-test-runner/blob/main/protocol/README.md)，針對指定架構中的任何語言執行測試。 `universal-test-runner`支援下列架構：
+ [Gradle](https://gradle.org/)
+ [Jest](https://jestjs.io/)
+ [Maven](https://maven.apache.org/)
+ [pytest](https://pytest.org)
+ [.NET](https://learn.microsoft.com/en-us/dotnet/core/tools/)
`universal-test-runner` 只會安裝在針對測試動作策劃的映像上。如果您要設定一個會使用自訂 Docker Hub 或 Amazon ECR 的測試動作，則您必須手動安裝 `universal-test-runner`，才能啟用進階的測試功能。若要這樣做，請在映像上安裝 Node.js (14 或更高版本)，接著透過 `npm` 使用 shell 命令 `- Run: npm install -g @aws/universal-test-runner` 安裝 `universal-test-runner`。如需透過 shell 命令在容器中安裝 Node.js 的詳細資訊，請參閱[安裝和更新 Node Version Manager](https://github.com/nvm-sh/nvm#install--update-script)。
如需 的詳細資訊`universal-test-runner`，請參閱[什麼是 universal-test-runner？](https://github.com/aws/universal-test-runner#-what-is-universal-test-runner)
------
#### [ Visual ]
**在視覺化編輯器中使用 universal-test-runner**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**動作**。
1. 在**動作**中，選擇**測試**。
1. 在**組態**索引標籤上，使用您選擇的支援架構更新範例程式碼，以完成 **Shell 命令**欄位。例如，若要使用支援的架構，您可以使用類似以下的`Run`命令。
```
- Run: run-tests
```
如果不支援您想要的架構，請考慮提供自訂的轉接器或執行器。如需 **Shell 命令**欄位的說明，請參閱 [Steps](build-action-ref.md#build.configuration.steps)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**在 YAML 編輯器中使用 universal-test-runner**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 選擇**動作**。
1. 在**動作**中，選擇**測試**。
1. 根據您的需求修改 YAML 程式碼。例如，若要使用支援的架構，您可以使用類似以下的`Run`命令。
```
Configuration:
Steps:
- Run: run-tests
```
如果不支援您想要的架構，請考慮提供自訂的轉接器或執行器。如需 **Steps** 屬性的說明，請參閱 [Steps](build-action-ref.md#build.configuration.steps)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 在 動作中設定品質報告
本節說明如何在 動作中設定品質報告。
**Topics**
+ [自動探索和手動報告](#test.auto-discovery)
+ [設定報告的成功條件](#test.success-criteria)
+ [品質報告 YAML 範例](#test.success-criteria-example)
## 自動探索和手動報告
啟用自動探索時，CodeCatalyst 會搜尋傳遞至動作的所有輸入，以及動作本身產生的所有檔案，尋找測試、程式碼涵蓋範圍、軟體合成分析 (SCA) 和靜態分析 (SA) 報告。您可以在 CodeCatalyst 中檢視和操作這些報告。
您也可以手動設定要產生哪些報告。您可以指定要產生的報告類型以及檔案格式。如需詳細資訊，請參閱[品質報告類型](test-workflow-actions.md#test-reporting)。
## 設定報告的成功條件
您可以設定值來決定測試、程式碼涵蓋範圍、軟體合成分析 (SCA) 或靜態分析 (SA) 報告的成功條件。
成功條件是決定報告是否通過或失敗的閾值。CodeCatalyst 會先產生您的報告，可以是測試、程式碼涵蓋範圍、SCA 或 SA 報告，然後將成功條件套用至產生的報告。然後，它會顯示是否符合成功條件，以及達到多少程度。如果任何報告不符合指定的成功條件，則指定成功條件的 CodeCatalyst 動作會失敗。
例如，當您設定 SCA 報告的成功條件時，從最嚴重到最不嚴重的有效漏洞值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、、`INFORMATIONAL`。如果您設定條件以`HIGH`嚴重性掃描一個漏洞，如果至少有一個`HIGH`嚴重性漏洞或沒有`HIGH`嚴重性漏洞，但至少一個嚴重性層級較高的漏洞，例如一個`CRITICAL`嚴重性漏洞，則報告將會失敗。
如果您未指定成功條件，則：
+ 根據您的原始報告產生的 CodeCatalyst 報告不會顯示成功條件。
+ 成功條件不會用來判斷相關聯的工作流程動作是否通過或失敗。
------
#### [ Visual ]
**設定成功條件**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇包含產生報告之動作的工作流程。這是您要套用成功條件的報告。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您已設定產生 CodeCatalyst 報告的動作。
1. 選擇 **Output (輸出)** 索引標籤。
1. 在**自動探索報告**或**手動設定報告**下，選擇**成功條件**。
成功條件隨即出現。根據您先前的選擇，您可能會看到下列任何或所有選項：
**通過率**
指定測試報告中必須傳遞的測試百分比，相關 CodeCatalyst 報告才能標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。通過率條件僅適用於測試報告。如需測試報告的詳細資訊，請參閱 [測試報告](test-workflow-actions.md#test-reports)。
**線路涵蓋範圍**
指定程式碼涵蓋範圍報告中必須涵蓋的行百分比，以便將關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。明細涵蓋範圍條件只會套用至程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
**分支涵蓋範圍**
指定程式碼涵蓋範圍報告中必須涵蓋的分支百分比，以便將關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。分支涵蓋範圍條件僅適用於程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
**漏洞 (SCA)**
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SCA 報告中允許的漏洞數量和嚴重性上限。若要指定漏洞，您必須指定：
+ 您要包含在計數中的漏洞最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 漏洞將會很高。
+ 您想要允許之指定嚴重性的漏洞數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
漏洞條件只會套用至 SCA 報告。如需 SCA 報告的詳細資訊，請參閱 [軟體合成分析報告](test-workflow-actions.md#test-sca-reports)。
**錯誤**
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的錯誤數量和嚴重性上限。若要指定錯誤，您必須指定：
+ 您要包含在計數中錯誤的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 錯誤將會很高。
+ 您想要允許之指定嚴重性的錯誤數目上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
錯誤條件只會套用至 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
**安全漏洞**
針對要標記為已傳遞的相關聯 CodeCatalyst 報告，指定 SA 報告中允許的安全漏洞數量和嚴重性上限。若要指定安全漏洞，您必須指定：
+ 您要包含在計數中的安全漏洞的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 安全漏洞將會很高。
+ 您想要允許之指定嚴重性的安全漏洞數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
安全漏洞條件僅適用於 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
**品質問題**
指定 SA 報告中允許將相關聯 CodeCatalyst 報告標示為已傳遞的品質問題數量和嚴重性上限。若要指定品質問題，您必須指定：
+ 您要包含在計數中品質問題的最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和`CRITICAL`品質問題將會很高。
+ 您想要允許之指定嚴重性的品質問題數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
品質問題條件僅適用於 PyLint 和 ESLint SA 報告。如需 SA 報告的詳細資訊，請參閱 [靜態分析報告](test-workflow-actions.md#test-static-analysis-reports)。
1. 選擇 **Commit** (遞交)。
1. 執行工作流程，讓 CodeCatalyst 將成功條件套用至原始報告，並重新產生包含成功條件資訊的相關聯 CodeCatalyst 報告。如需詳細資訊，請參閱[手動啟動工作流程執行](workflows-manually-start.md)。
------
#### [ YAML ]
**設定成功條件**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇包含產生報告之動作的工作流程。這是您要套用成功條件的報告。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在工作流程圖表中，選擇您已設定產生 CodeCatalyst 報告的動作。
1. 在詳細資訊窗格中，選擇**輸出**索引標籤。
1. 在 動作、 `AutoDiscoverReports`區段或 `Reports`區段中，新增 **SuccessCriteria** 屬性，以及 `PassRate`、`LineCoverage`、`BranchCoverage`、`Vulnerabilities``StaticAnalysisBug`、 `StaticAnalysisSecurity`和 `StaticAnalysisQuality` 屬性。
如需每個屬性的說明，請參閱 [建置和測試動作 YAML](build-action-ref.md)。
1. 選擇 **Commit** (遞交)。
1. 執行工作流程，讓 CodeCatalyst 將成功條件套用至原始報告，並使用包含的成功條件資訊重新產生相關聯的 CodeCatalyst 報告。如需啟動工作流程的詳細資訊，請參閱 [手動啟動工作流程執行](workflows-manually-start.md)。
------
## 品質報告 YAML 範例
下列範例示範如何手動設定四個報告：測試報告、程式碼涵蓋範圍報告、軟體合成分析報告，以及靜態分析報告。
```
Reports:
MyTestReport:
Format: JUNITXML
IncludePaths:
- "*.xml"
ExcludePaths:
- report1.xml
SuccessCriteria:
PassRate: 90
MyCoverageReport:
Format: CLOVERXML
IncludePaths:
- output/coverage/jest/clover.xml
SuccessCriteria:
LineCoverage: 75
BranchCoverage: 75
MySCAReport:
Format: SARIFSCA
IncludePaths:
- output/sca/reports.xml
SuccessCriteria:
Vulnerabilities:
Number: 5
Severity: HIGH
MySAReport:
Format: ESLINTJSON
IncludePaths:
- output/static/eslint.xml
SuccessCriteria:
StaticAnalysisBug:
Number: 10
Severity: MEDIUM
StaticAnalysisSecurity:
Number: 5
Severity: CRITICAL
StaticAnalysisQuality:
Number: 0
Severity: INFORMATIONAL
```
# 測試的最佳實務
使用 CodeCatalyst 提供的測試功能時，建議您遵循這些最佳實務。
**Topics**
+ [自動探索](#test.best-auto-discovery)
+ [成功條件](#test.best-success-criteria)
+ [包含/排除路徑](#test.best-include-exclude)
## 自動探索
在 CodeCatalyst 中設定動作時，自動探索可讓您自動探索各種工具的輸出，例如 JUnit 測試報告，並從中產生相關的 CodeCatalyst 報告。即使探索輸出的名稱或路徑變更，自動探索也有助於確保報告持續產生。新增新檔案時，CodeCatalyst 會自動探索它們並產生相關報告。不過，如果您使用自動探索，請務必考慮此功能的下列部分層面：
+ 當您在動作中啟用自動探索時，所有自動探索到的相同類型報告都會共用相同的成功條件。例如，共用條件，例如最低通過率，會套用至所有自動探索的測試報告。如果您需要相同類型的報告不同條件，則必須明確設定這些報告。
+ 自動探索也可以找到您的相依性產生的報告，如果設定成功條件，則這些報告上的 動作可能會失敗。您可以透過更新排除路徑組態來解決此問題。
+ 自動探索不保證每次都會產生相同的報告清單，因為它會在執行時間掃描動作。如果您希望一律產生特定報告，您應該明確設定報告。例如，如果測試在您的建置中停止執行，則測試架構不會產生任何輸出，因此不會產生任何測試報告，而且動作可能會成功。如果您希望動作的成功取決於該特定測試，則必須明確設定該報告。
**提示**
開始使用新的或現有的專案時，請對整個專案目錄 （包括 `**/*`) 使用自動探索。這會調用專案中所有檔案的報告產生，包括子目錄中的檔案。
如需詳細資訊，請參閱[在 動作中設定品質報告](test-config-action.md)。
## 成功條件
您可以設定成功條件，在報告上強制執行品質閾值。例如，如果自動探索兩個程式碼涵蓋範圍報告，一個包含 80% 的涵蓋範圍，另一個包含 60% 的涵蓋範圍，您有下列選項：
+ 將線路涵蓋範圍的自動探索成功條件設定為 80%。這會導致第一個報告通過，而第二個報告失敗，這會導致整體動作失敗。若要解除封鎖工作流程，請將新測試新增至您的專案，直到第二個報告的涵蓋範圍超過 80%。
+ 將行涵蓋範圍的自動探索成功條件設定為 60%。這會導致兩個報告都通過，這會導致動作成功。然後，您可以努力增加第二個報告中的程式碼涵蓋範圍。不過，使用此方法，您無法保證第一個報告中的涵蓋範圍不會低於 80%。
+ 使用視覺化編輯器或為每個報告新增明確的 YAML 區段和路徑，明確設定一個或兩個報告。這可讓您為每個報告設定個別的成功條件和自訂名稱。不過，使用此方法時，如果報告路徑變更，動作可能會失敗。
如需詳細資訊，請參閱[設定報告的成功條件](test-config-action.md#test.success-criteria)。
## 包含/排除路徑
檢閱動作結果時，您可以透過設定 `IncludePaths`和 來調整 CodeCatalyst 產生的報告清單`ExcludePaths`。
+ 使用 `IncludePaths`指定您希望 CodeCatalyst 在搜尋報告時包含的檔案和檔案路徑。例如，如果您指定 `"/test/report/*"`，CodeCatalyst 會搜尋尋找`/test/report/`目錄的動作所使用的整個建置映像。找到該目錄時，CodeCatalyst 接著會尋找該目錄中的報告。
**注意**
對於手動設定的報告， `IncludePaths` 必須是符合單一檔案的 glob 模式。
+ 使用 `ExcludePaths`指定您希望 CodeCatalyst 在搜尋報告時排除的檔案和檔案路徑。例如，如果您指定 `"/test/reports/**/*"`，CodeCatalyst 不會搜尋 `/test/reports/`目錄中的檔案。若要忽略目錄中的所有檔案，請使用 `**/*` glob 模式。
以下是可能的 glob 模式範例。
| 模式 | Description |
| --- | --- |
| `*.*` | 符合目前目錄中包含點的所有物件名稱 |
| `*.xml` | 符合目前目錄中以 結尾的所有物件名稱 `.xml` |
| `*.{xml,txt}` | 符合目前目錄中以 `.xml`或 結尾的所有物件名稱 `.txt` |
| `**/*.xml` | 比對以 結尾的所有目錄的物件名稱 `.xml` |
| `testFolder` | 比對名為 的物件`testFolder`，將其視為檔案 |
| `testFolder/*` | 比對 子資料夾中某個層級的物件`testFolder`，例如 `testFolder/file.xml` |
| `testFolder/*/*` | 從 比對兩個層級的子資料夾中的物件`testFolder`，例如 `testFolder/reportsFolder/file.xml` |
| `testFolder/**` | 符合資料夾 `testFolder` 以及 `testFolder` 下的檔案，例如 `testFolder/file.xml` 和 `testFolder/otherFolder/file.xml` |
CodeCatalyst 會解譯 glob 模式，如下所示：
+ 斜線 (`/`) 字元會分隔檔案路徑中的目錄。
+ 星號 (`*`) 字元符合不超過資料夾邊界之名稱元件的零個或多個字元。
+ 雙星號 (`**`) 會比對所有目錄中名稱元件的零個或多個字元。
**注意**
`ExcludePaths` 優先於 `IncludePaths`。如果 `IncludePaths`和 都`ExcludePaths`包含相同的資料夾，則不會掃描該資料夾是否有報告。
# 支援的 SARIF 屬性
靜態分析結果交換格式 (SARIF) 是一種輸出檔案格式，可用於 Amazon CodeCatalyst 中的軟體合成分析 (SCA) 和靜態分析報告。下列範例示範如何在靜態分析報告中手動設定 SARIF：
```
Reports:
MySAReport:
Format: SARIFSA
IncludePaths:
- output/sa_report.json
SuccessCriteria:
StaticAnalysisFinding:
Number: 25
Severity: HIGH
```
CodeCatalyst 支援下列 SARIF 屬性，可用於最佳化分析結果在報告中的顯示方式。
**Topics**
+ [`sarifLog` 物件](#test.sarif.sarifLog)
+ [`run` 物件](#test.sarif.run)
+ [`toolComponent` 物件](#test.sarif.toolComponent)
+ [`reportingDescriptor` 物件](#test.sarif.reportingDescriptor)
+ [`result` 物件](#test.sarif.result)
+ [`location` 物件](#test.sarif.location)
+ [`physicalLocation` 物件](#test.sarif.physicalLocation)
+ [`logicalLocation` 物件](#test.sarif.logicalLocation)
+ [`fix` 物件](#test.sarif.fix)
## `sarifLog` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `$schema` | 是 | [2.1.0](https://json.schemastore.org/sarif-2.1.0.json) 版 SARIF JSON 結構描述的 URI。 |
| `version` | 是 | CodeCatalyst 僅支援 SARIF 2.1.0 版。 |
| `runs[]` | 是 | SARIF 檔案包含一或多個執行的陣列，每個都代表分析工具的單一執行。 |
## `run` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `tool.driver` | 是 | 描述分析工具的`toolComponent`物件。 |
| `tool.name` | 否 | 屬性，指出用於執行分析的工具名稱。 |
| `results[]` | 是 | CodeCatalyst 上顯示的分析工具結果。 |
## `toolComponent` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `name` | 是 | 分析工具的名稱。 |
| `properties.artifactScanned` | 否 | 工具分析的成品總數。 |
| `rules[]` | 是 | 代表規則的`reportingDescriptor`物件陣列。根據這些規則，分析工具會在分析的程式碼中找到問題。 |
## `reportingDescriptor` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `id` | 是 | 用於參考問題清單之規則的唯一識別符。 長度上限：1，024 個字元 |
| `name` | 否 | 規則的顯示名稱。 長度上限：1，024 個字元 |
| `shortDescription.text` | 否 | 規則的簡短描述。 長度上限：3，000 個字元 |
| `fullDescription.text` | 否 | 規則的完整描述。 長度上限：3，000 個字元 |
| `helpUri` | 否 | 可以當地語系化的字串，包含規則之主要文件的絕對 URI。 長度上限：3，000 個字元 |
| `properties.unscore` | 否 | 指出掃描問題清單是否已評分的旗標。 |
| `properties.score.severity` | 否 | 指定調查結果嚴重性層級的一組固定字串。 長度上限：1，024 個字元 |
| `properties.cvssv3_baseSeverity` | 否 | Common [Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document) 的定性嚴重性評分。 |
| `properties.cvssv3_baseScore` | 否 | CVSS v3 基本分數範圍為 [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss)。 |
| `properties.cvssv2_severity` | 否 | 如果 CVSS v3 值不可用，CodeCatalyst 會搜尋 CVSS v2 值。 |
| `properties.cvssv2_score` | 否 | CVSS v2 基本分數範圍為 [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss)。 |
| `properties.severity` | 否 | 指定調查結果嚴重性層級的一組固定字串。 長度上限：1，024 個字元 |
| `defaultConfiguration.level` | 否 | 規則的預設嚴重性。 |
## `result` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `ruleId` | 是 | 用於參考問題清單之規則的唯一識別符。 長度上限：1，024 個字元 |
| `ruleIndex` | 是 | 工具元件 中相關聯規則的索引`rules[]`。 |
| `message.text` | 是 | 說明結果並顯示每個問題清單訊息的訊息。 長度上限：3，000 個字元 |
| `rank` | 否 | 包含 0.0 到 100.0 之間的值，代表結果的優先順序或重要性。此縮放值 0.0 為最低優先順序，100.0 為最高優先順序。 |
| `level` | 否 | 結果的嚴重性。 長度上限：1，024 個字元 |
| `properties.unscore` | 否 | 指出掃描問題清單是否已評分的旗標。 |
| `properties.score.severity` | 否 | 指定調查結果嚴重性層級的一組固定字串。 長度上限：1，024 個字元 |
| `properties.cvssv3_baseSeverity` | 否 | Common [Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document) 的定性嚴重性評分。 |
| `properties.cvssv3_baseScore` | 否 | CVSS v3 基本分數範圍為 [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss)。 |
| `properties.cvssv2_severity` | 否 | 如果 CVSS v3 值不可用，CodeCatalyst 會搜尋 CVSS v2 值。 |
| `properties.cvssv2_score` | 否 | CVSS v2 基本分數範圍為 [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss)。 |
| `properties.severity` | 否 | 指定調查結果嚴重性層級的一組固定字串。 長度上限：1，024 個字元 |
| `locations[]` | 是 | 偵測到結果的一組位置。除非問題只能透過在每個指定位置進行變更來修正，否則只能包含一個位置。CodeCatalyst 會使用位置陣列中的第一個值來註釋結果。 `location` 物件數量上限：10 |
| `relatedLocations[]` | 否 | 調查結果中其他位置參考的清單。 `location` 物件數量上限：50 |
| `fixes[]` | 否 | 代表掃描工具所提供建議的`fix`物件陣列。CodeCatalyst 使用`fixes`陣列中的第一個建議。 |
## `location` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `physicalLocation` | 是 | 識別成品和區域。 |
| `logicalLocations[]` | 否 | 名稱描述的一組位置，不參考成品。 |
## `physicalLocation` 物件
| 名稱 | 必要 | 描述 |
| --- | --- | --- |
| `artifactLocation.uri` | 是 | 指出成品位置的 URI，通常是在儲存庫中或在建置期間產生的檔案。 |
| `fileLocation.uri` | 否 | 指示檔案位置的備用 URI。如果 `artifactLocation.uri`傳回空白，則會使用此項目。 |
| `region.startLine` | 是 | 區域中第一個字元的行號。 |
| `region.startColumn` | 是 | 區域中第一個字元的資料欄編號。 |
| `region.endLine` | 是 | 區域中最後一個字元的行號。 |
| `region.endColumn` | 是 | 區域中最後一個字元的資料欄編號。 |
## `logicalLocation` 物件
| 名稱 | 必要 | Description |
| --- | --- | --- |
| `fullyQualifiedName` | 否 | 描述結果位置的其他資訊。 長度上限：1，024 個字元 |
## `fix` 物件
| 名稱 | 必要 | Description |
| --- | --- | --- |
| `description.text` | 否 | 顯示每個問題清單建議的訊息。 長度上限：3，000 個字元 |
| `artifactChanges.[0].artifactLocation.uri` | 否 | URI 指出需要更新之成品的位置。 |
# 使用工作流程部署
使用 [CodeCatalyst 工作流程](workflow.md)，您可以將應用程式和其他資源部署到 Amazon ECS 等各種目標 AWS Lambda。
## 如何部署應用程式？
若要透過 CodeCatalyst 部署應用程式或資源，您必須先建立工作流程，然後在其中指定部署動作。*部署動作*是工作流程建置區塊，可定義您要部署*的內容*、您要部署*的位置*，以及您想要部署*的方式* （例如，使用藍/綠方案）。您可以使用 CodeCatalyst 主控台的視覺化編輯器或 YAML 編輯器，將部署動作新增至工作流程。
部署應用程式或資源的高階步驟如下所示。
**部署應用程式 （高階任務）**
1. 在 CodeCatalyst 專案中，您可以為要部署的應用程式**新增原始程式碼**。如需詳細資訊，請參閱[將原始程式碼存放在 CodeCatalyst 中專案的儲存庫中](source-repositories.md)。
1. 在 CodeCatalyst 專案中，您可以**新增環境**，定義您要部署的目標 AWS 帳戶 和選用 Amazon Virtual Private Cloud (VPC)。如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
1. 在 CodeCatalyst 專案中，您可以**建立工作流程**。工作流程是您定義如何建置、測試和部署應用程式的地方。如需詳細資訊，請參閱[工作流程入門](workflows-getting-started.md)。
1. 在工作流程中，您可以**新增觸發**條件、**建置動作**，以及選擇性**的測試動作**。如需詳細資訊，請參閱[使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)、[新增建置動作](build-add-action.md)及[新增測試動作](test-add-action.md)。
1. 在工作流程中，您可以**新增部署動作**。您可以從數個 CodeCatalyst 提供的部署動作中選擇到應用程式的不同目標，例如 Amazon ECS。（您也可以使用建置動作或 GitHub 動作來部署應用程式。 如需建置動作和 GitHub 動作的詳細資訊，請參閱 [部署動作的替代方案](#deploy-concepts-alternatives)。)
1. 您可以透過觸發手動或自動**啟動工作流程**。工作流程會依序執行建置、測試和部署動作，將您的應用程式和資源部署到目標。如需詳細資訊，請參閱[手動啟動工作流程執行](workflows-manually-start.md)。
## 部署動作的清單
下列部署動作可供使用：
+ 部署 CloudFormation 堆疊 – 此動作 AWS 會根據您提供的[CloudFormation 範本](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html)，在 中建立 CloudFormation [AWS Serverless Application Model](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html) 堆疊。如需詳細資訊，請參閱[部署 CloudFormation 堆疊](deploy-action-cfn.md)。
+ 部署到 Amazon ECS – 此動作會註冊您提供[的任務定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)檔案。如需詳細資訊，請參閱[使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)。
+ 部署至 Kubernetes 叢集 – 此動作會將應用程式部署至 Amazon Elastic Kubernetes Service 叢集。如需詳細資訊，請參閱[使用工作流程部署至 Amazon EKS](deploy-action-eks.md)。
+ AWS CDK 部署 – 此動作會將[AWS CDK 應用程式](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_concepts)部署到 AWS。如需詳細資訊，請參閱[使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)。
**注意**
還有其他 CodeCatalyst 動作可以部署資源；不過，這些動作不會被視為*部署*動作，因為其部署資訊不會出現在**環境**頁面上。若要進一步了解**環境**頁面和檢視部署，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [檢視部署資訊](deploy-view-deployment-info.md)。
## 部署動作的優點
在工作流程中使用部署動作具有下列優點：
+ **部署歷史記錄** – 檢視部署的歷史記錄，以協助管理和傳達部署軟體中的變更。
+ 可**追蹤性** – 透過 CodeCatalyst 主控台追蹤部署的狀態，並查看每個應用程式修訂版的部署時間和位置。
+ **回復** – 發生錯誤時自動回復部署。您也可以設定警示來啟用部署轉返。
+ **監控** – 在部署進行工作流程的各個階段時觀察部署。
+ **與其他 CodeCatalyst 功能的整合** – 儲存原始程式碼，然後建置、測試和部署它，全都從單一應用程式完成。
## 部署動作的替代方案
您不需要使用部署動作，但建議使用這些動作，因為它們提供上一節中概述的優點。反之，您可以使用下列 [CodeCatalyst 動作](workflows-actions.md#workflows-actions-types-cc)：
+ **建置**動作。
一般而言，如果您想要部署到不存在對應部署動作的目標，或者想要對部署程序進行更多控制，您可以使用建置動作。如需使用建置動作部署資源的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ **GitHub 動作**。
您可以在 CodeCatalyst 工作流程中使用 [GitHub 動作](workflows-actions.md#workflows-actions-types-github)來部署應用程式和資源 （而不是 CodeCatalyst 動作）。如需如何在 CodeCatalyst 工作流程中使用 GitHub 動作的詳細資訊，請參閱 [與 GitHub 動作整合](integrations-github-actions.md)
如果您不想使用 CodeCatalyst 工作流程，您也可以使用下列 AWS 服務來部署應用程式：
+ AWS CodeDeploy – 請參閱[什麼是 CodeDeploy？](https://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html)
+ AWS CodeBuild 和 AWS CodePipeline – 請參閱[什麼是 AWS CodeBuild？](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html) [什麼是 AWS CodePipeline？](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html)
+ CloudFormation – 請參閱[什麼是 CloudFormation？](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)
針對複雜的企業部署，使用 CodeDeploy、CodeBuild、CodePipeline 和 CloudFormation 服務。
**Topics**
+ [如何部署應用程式？](#deploy-concepts)
+ [部署動作的清單](#deploy-concepts-action-supported)
+ [部署動作的優點](#deploy-concepts-why-use)
+ [部署動作的替代方案](#deploy-concepts-alternatives)
+ [使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)
+ [使用工作流程部署至 Amazon EKS](deploy-action-eks.md)
+ [部署 CloudFormation 堆疊](deploy-action-cfn.md)
+ [使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)
+ [使用工作流程引導 AWS CDK 應用程式](cdk-boot-action.md)
+ [使用工作流程將檔案發佈至 Amazon S3](s3-pub-action.md)
+ [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)
+ [在工作流程圖表中顯示應用程式 URL](deploy-app-url.md)
+ [移除部署目標](deploy-remove-target.md)
+ [依遞交追蹤部署狀態](track-changes.md)
+ [檢視部署日誌](deploy-deployment-logs.md)
+ [檢視部署資訊](deploy-view-deployment-info.md)
# 使用工作流程部署至 Amazon ECS
本節說明如何使用 CodeCatalyst 工作流程將容器化應用程式部署至 Amazon Elastic Container Service 叢集。若要達成此目的，您必須將**部署至 Amazon ECS** 動作新增至工作流程。此動作會註冊您提供[的任務定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)檔案。註冊時，任務定義會由 [Amazon ECS 叢集中執行的 Amazon ECS 服務](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html)執行個體化。 [https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters)「建立任務定義」等同於將應用程式部署到 Amazon ECS。
若要使用此動作，您必須備妥 Amazon ECS 叢集、服務和任務定義檔案。
如需 Amazon ECS 的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》。
**提示**
如需說明如何使用**部署至 Amazon ECS **動作的教學課程，請參閱 [教學課程：將應用程式部署至 Amazon ECS](deploy-tut-ecs.md)。
**提示**
如需**部署至 Amazon ECS** 動作的工作範例，請使用 **Node.js API 搭配 AWS Fargate** 或 **Java API 搭配 AWS Fargate**藍圖來建立專案。如需詳細資訊，請參閱[使用藍圖建立專案](projects-create.md#projects-create-console-template)。
**Topics**
+ [「部署至 Amazon ECS」動作所使用的執行期映像](#deploy-action-ecs-runtime)
+ [教學課程：將應用程式部署至 Amazon ECS](deploy-tut-ecs.md)
+ [將 'Deploy 新增至 Amazon ECS' 動作](deploy-action-ecs-adding.md)
+ [「部署到 Amazon ECS」變數](deploy-action-ecs-variables.md)
+ [「部署到 Amazon ECS」動作 YAML](deploy-action-ref-ecs.md)
## 「部署至 Amazon ECS」動作所使用的執行期映像
**部署至 Amazon ECS** 動作會在 [2022 年 11 月映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 教學課程：將應用程式部署至 Amazon ECS
在本教學課程中，您將了解如何使用工作流程、Amazon ECS 和其他一些 AWS 服務，將無伺服器應用程式部署至 Amazon Elastic Container Service (Amazon ECS)。部署的應用程式是建置在 Apache Web 伺服器 Docker 映像上的簡單 Hello World 網站。本教學課程會逐步解說必要的準備工作，例如設定叢集，然後說明如何建立工作流程來建置和部署應用程式。
**提示**
您可以使用藍圖，為您完成 Amazon ECS 設定，而不是透過本教學課程進行。您需要使用 **Node.js API 搭配 AWS Fargate** 或 **Java API 搭配 AWS Fargate**藍圖。如需詳細資訊，請參閱[使用藍圖建立專案](projects-create.md#projects-create-console-template)。
**Topics**
+ [先決條件](#deploy-tut-ecs-prereqs)
+ [步驟 1：設定 AWS 使用者和 AWS CloudShell](#deploy-tut-ecs-user-cloudshell)
+ [步驟 2：將預留位置應用程式部署至 Amazon ECS](#deploy-tut-ecs-placeholder)
+ [步驟 3：建立 Amazon ECR 映像儲存庫](#deploy-tut-ecs-ecr)
+ [步驟 4：建立 AWS 角色](#deploy-tut-ecs-build-deploy-roles)
+ [步驟 5：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-ecs-import-roles)
+ [步驟 6：建立來源儲存庫](#deploy-tut-ecs-source-repo)
+ [步驟 7：新增來源檔案](#deploy-tut-ecs-source-files)
+ [步驟 8：建立和執行工作流程](#deploy-tut-ecs-workflow)
+ [步驟 9：變更來源檔案](#deploy-tut-ecs-change)
+ [清除](#deploy-tut-ecs-cleanup)
## 先決條件
開始之前：
+ 您需要具有連線 AWS 帳戶的 CodeCatalyst **空間**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在您的空間中，您需要一個名為 的空專案：
```
codecatalyst-ecs-project
```
使用**從頭開始**選項來建立此專案。
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
+ 在您的專案中，您需要名為 的 CodeCatalyst **環境**：
```
codecatalyst-ecs-environment
```
設定此環境，如下所示：
+ 選擇任何類型的，例如**非生產**。
+ 將您的帳戶連接到該 AWS 帳戶。
+ 針對**預設 IAM 角色**，選擇任何角色。稍後您將指定不同的角色。
如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
## 步驟 1：設定 AWS 使用者和 AWS CloudShell
本教學課程的第一步是在 中建立使用者 AWS IAM Identity Center，並以此使用者身分啟動 AWS CloudShell 執行個體。在本教學課程中，CloudShell 是您的開發電腦，也是您設定 AWS 資源和服務的地方。完成教學課程後刪除此使用者。
**注意**
請勿將您的根使用者用於本教學課程。稍後在 AWS Command Line Interface (CLI) 中執行動作時，您必須建立個別的使用者，否則可能會遇到問題。
如需 IAM Identity Center 使用者和 CloudShell 的詳細資訊，請參閱 *AWS IAM Identity Center 使用者指南*和 *AWS CloudShell 使用者指南*。
**建立 IAM Identity Center 使用者**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/) 開啟 AWS IAM Identity Center 主控台。
**注意**
請務必使用連線至 CodeCatalyst 空間 AWS 帳戶 的 登入。您可以透過導覽至您的空間並選擇 **AWS 帳戶索引標籤來驗證哪個帳戶**已連線。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
1. 在導覽窗格中，選擇 **使用者**，然後選擇 **新增使用者**。
1. 在**使用者名稱**中，輸入：
```
CodeCatalystECSUser
```
1. 在**密碼**下，選擇**產生您可以與此使用者共用的一次性密碼**。
1. 在**電子郵件地址**和**確認電子郵件地址**中，輸入 IAM Identity Center 中尚不存在的電子郵件地址。
1. 在**名字**和**姓氏**中，輸入：
```
CodeCatalystECSUser
```
1. 在**顯示名稱**中，保留自動產生的名稱：
```
CodeCatalystECSUser CodeCatalystECSUser
```
1. 選擇**下一步**。
1. 在**新增使用者至群組**頁面上，選擇**下一步**。
1. 在**檢閱和新增使用者**頁面上，檢閱資訊，然後選擇**新增使用者**。
**一次性密碼**對話方塊隨即出現。
1. 選擇**複製**，然後貼上登入資訊，包括 AWS 存取入口網站 URL 和一次性密碼。
1. 選擇**關閉**。
**建立許可集合**
您將將此許可集指派給`CodeCatalystECSUser`稍後的 。
1. 在導覽窗格中，選擇**許可集**，然後選擇**建立許可集**。
1. 選擇**預先定義的許可集**，然後選取 **AdministratorAccess**。此政策為所有 提供完整許可 AWS 服務。
1. 選擇**下一步**。
1. 在**許可集名稱**中，輸入：
```
CodeCatalystECSPermissionSet
```
1. 選擇**下一步**。
1. 在**檢閱和建立**頁面上，檢閱資訊，然後選擇**建立**。
**將許可集指派給 CodeCatalystECSUser**
1. 在導覽窗格中，選擇 **AWS 帳戶**，然後選取 AWS 帳戶 您目前登入之 旁的核取方塊。
1. 選擇**指派使用者或群組**。
1. 選擇**使用者**索引標籤。
1. 選取 旁的核取方塊`CodeCatalystECSUser`。
1. 選擇**下一步**。
1. 選取 旁的核取方塊`CodeCatalystECSPermissionSet`。
1. 選擇**下一步**。
1. 檢閱資訊，然後選擇**提交**。
您現在已將 `CodeCatalystECSUser`和 `CodeCatalystECSPermissionSet` 指派給 AWS 帳戶，並將其繫結在一起。
**以 CodeCatalystECSUser 身分登出並重新登入**
1. 登出之前，請確定您擁有 AWS 存取入口網站 URL 以及 的使用者名稱和一次性密碼`CodeCatalystECSUser`。您應該稍早已將此資訊複製到文字編輯器。
**注意**
如果您沒有此資訊，請前往 IAM Identity Center 的詳細資訊`CodeCatalystECSUser`頁面，選擇**重設密碼**、**產生一次性密碼 【...】** 和再次**重設密碼**，以在畫面上顯示資訊。
1. 登出 AWS。
1. 將 AWS 存取入口網站 URL 貼到瀏覽器的地址列。
1. 使用 的使用者名稱和一次性密碼登入`CodeCatalystECSUser`。
1. 在**新密碼**中，輸入密碼，然後選擇**設定新密碼**。
畫面上會出現一個**AWS 帳戶**方塊。
1. 選擇 **AWS 帳戶**，然後選擇您 AWS 帳戶 為其指派`CodeCatalystECSUser`使用者和許可集的 名稱。
1. 在 旁`CodeCatalystECSPermissionSet`，選擇 **管理主控台**。
AWS 管理主控台 隨即出現。您現在以`CodeCatalystECSUser`具有適當許可的 身分登入。
**啟動 AWS CloudShell 執行個體**
1. 作為 `CodeCatalystECSUser`，在頂端導覽列中，選擇 AWS 圖示 (![\[AWS icon\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/deploy/aws-logo.png))。
隨即 AWS 管理主控台 顯示 的主頁面。
1. 在頂端導覽列中，選擇 AWS CloudShell 圖示 (![\[CloudShell icon\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/deploy/CloudShell.png))。
CloudShell 隨即開啟。等待 CloudShell 環境建立。
**注意**
如果您沒有看到 CloudShell 圖示，請確定您位於 [ CloudShell 支援的區域中](https://docs.aws.amazon.com/cloudshell/latest/userguide/faq-list.html#regions-available)。本教學假設您位於美國西部 （奧勒岡） 區域。
**驗證 AWS CLI 是否已安裝**
1. 在 CloudShell 終端機中，輸入：
```
aws --version
```
1. 檢查版本是否出現。
AWS CLI 已為目前使用者 設定 `CodeCatalystECSUser`，因此不需要設定 AWS CLI 金鑰和登入資料，通常也是如此。
## 步驟 2：將預留位置應用程式部署至 Amazon ECS
在本節中，您將手動將預留位置應用程式部署至 Amazon ECS。此預留位置應用程式將由工作流程部署的 Hello World 應用程式取代。預留位置應用程式為 Apache Web Server。
如需 Amazon ECS 的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》。
完成下列一系列程序以部署預留位置應用程式。
**建立任務執行角色**
此角色會授予 Amazon ECS 和代表您進行 API 呼叫的 AWS Fargate 許可。
1. 建立信任政策：
1. 在 中 AWS CloudShell，輸入下列命令：
```
cat > codecatalyst-ecs-trust-policy.json
```
CloudShell 終端機中會出現閃爍提示。
1. 在提示中輸入下列程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ecs-tasks.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 將游標放在最後一個大括號 () 之後`}`。
1. 按 **Enter** ，然後按 **Ctrl\$1d** 儲存檔案並退出貓。
1. 建立任務執行角色：
```
aws iam create-role \
--role-name codecatalyst-ecs-task-execution-role \
--assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
```
1. 將 AWS 受管`AmazonECSTaskExecutionRolePolicy`政策連接至角色：
```
aws iam attach-role-policy \
--role-name codecatalyst-ecs-task-execution-role \
--policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
```
1. 顯示角色的詳細資訊：
```
aws iam get-role \
--role-name codecatalyst-ecs-task-execution-role
```
1. 請記下角色`"Arn":`的值，例如 `arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role`。稍後您將需要此 Amazon Resource Name (ARN)。
**建立 Amazon ECS 叢集**
此叢集將包含 Apache 預留位置應用程式，以及稍後的 Hello World 應用程式。
1. 作為 `CodeCatalystECSUser`，在 中 AWS CloudShell建立空叢集：
```
aws ecs create-cluster --cluster-name codecatalyst-ecs-cluster
```
1. （選用） 確認叢集已成功建立：
```
aws ecs list-clusters
```
`codecatalyst-ecs-cluster` 叢集的 ARN 應該會出現在清單中，表示成功建立。
**建立任務定義檔案**
任務定義檔案指出 要執行從 DockerHub 提取的 [Apache 2.4 Web 伺服器](https://hub.docker.com/_/httpd) Docker 映像 (`httpd:2.4`)。 DockerHub
1. 作為 `CodeCatalystECSUser`，在 中 AWS CloudShell建立任務定義檔案：
```
cat > taskdef.json
```
1. 在提示中貼上下列程式碼：
```
{
"executionRoleArn": "arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role",
"containerDefinitions": [
{
"name": "codecatalyst-ecs-container",
"image": "httpd:2.4",
"essential": true,
"portMappings": [
{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
}
]
}
],
"requiresCompatibilities": [
"FARGATE"
],
"cpu": "256",
"family": "codecatalyst-ecs-task-def",
"memory": "512",
"networkMode": "awsvpc"
}
```
在上述程式碼中，取代 *arn：aws：iam：：111122223333：role/codecatalyst-ecs-task-execution-role*
使用您在 中記下之任務執行角色的 ARN[建立任務執行角色](#deploy-tut-ecs-create-task-execution-role)。
1. 將游標放在最後一個大括號 () 之後`}`。
1. 按 **Enter** ，然後按 **Ctrl\$1d** 儲存檔案並退出貓。
**向 Amazon ECS 註冊任務定義檔案**
1. 作為 `CodeCatalystECSUser`，在 中 AWS CloudShell註冊任務定義：
```
aws ecs register-task-definition \
--cli-input-json file://taskdef.json
```
1. （選用） 確認任務定義已註冊：
```
aws ecs list-task-definitions
```
`codecatalyst-ecs-task-def` 任務定義應該會出現在清單中。
**建立 Amazon ECS 服務**
Amazon ECS 服務會執行 Apache 預留位置應用程式的任務 （和相關聯的 Docker 容器），以及稍後的 Hello World 應用程式。
1. 身為 `CodeCatalystECSUser`，如果您尚未這麼做，請切換到 Amazon Elastic Container Service 主控台。
1. 選擇您先前建立的叢集 `codecatalyst-ecs-cluster`。
1. 在**服務**索引標籤中，選擇**建立**。
1. 在**建立**頁面中，執行下列動作：
1. 保留所有預設設定，但接下來列出的設定除外。
1. 針對 **Launch type (啟動類型)**，選擇 **FARGATE**。
1. 在**任務定義**下，於**系列**下拉式清單中，選擇：
`codecatalyst-ecs-task-def`
1. 針對**服務名稱**，輸入：
```
codecatalyst-ecs-service
```
1. 針對**所需的任務**，輸入：
```
3
```
在本教學課程中，每個任務都會啟動單一 Docker 容器。
1. 展開**聯網**區段。
1. 對於 **VPC**，請選擇任何 VPC。
1. 針對**子網路**，選擇任何子網路。
**注意**
僅指定一個子網路。這就是本教學課程所需的一切。
**注意**
如果您沒有 VPC 和子網路，請建立它們。請參閱《Amazon [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC) 使用者指南》中的建立 VPC 和[在您的 VPC 中建立子網路](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet)。 **
1. 針對**安全群組**，選擇**建立新的安全群組**，然後執行下列動作：
1. 針對**安全群組名稱**，輸入：
```
codecatalyst-ecs-security-group
```
1. 針對**安全群組描述**，輸入：
```
CodeCatalyst ECS security group
```
1. 選擇**新增規則**。針對**類型**，選擇 **HTTP**，針對**來源**，選擇 **Anywhere**。
1. 在底部，選擇**建立**。
1. 等待服務建立。這可能需要幾分鐘的時間。
1. 選擇**任務**索引標籤，然後選擇重新整理按鈕。確認這三個任務的**上次狀態**欄都設定為**執行**中。
**（選用） 驗證您的 Apache 預留位置應用程式是否正在執行**
1. 在**任務**索引標籤中，選擇三個任務中的任一個。
1. 在**公有 IP** 欄位中，選擇**開啟的地址**。
`It Works!` 頁面隨即出現。這表示 Amazon ECS 服務已成功啟動使用 Apache 映像啟動 Docker 容器的任務。
在教學課程中的這個階段，您已手動部署 Amazon ECS 叢集、服務和任務定義，以及 Apache 預留位置應用程式。所有這些項目都就緒後，您現在可以建立工作流程，以教學課程的 Hello World 應用程式取代 Apache 預留位置應用程式。
## 步驟 3：建立 Amazon ECR 映像儲存庫
在本節中，您會在 Amazon Elastic Container Registry (Amazon ECR) 中建立私有映像儲存庫。此儲存庫會存放教學課程的 Docker 映像，以取代您先前部署的 Apache 預留位置映像。
如需 Amazon ECR 的詳細資訊，請參閱《*Amazon Elastic Container Registry 使用者指南*》。
**在 Amazon ECR 中建立映像儲存庫**
1. 作為 `CodeCatalystECSUser`，在 中 AWS CloudShell，在 Amazon ECR 中建立空儲存庫：
```
aws ecr create-repository --repository-name codecatalyst-ecs-image-repo
```
1. 顯示 Amazon ECR 儲存庫的詳細資訊：
```
aws ecr describe-repositories \
--repository-names codecatalyst-ecs-image-repo
```
1. 請記下 `“repositoryUri”:`值，例如 `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`。
稍後在將儲存庫新增至工作流程時需要它。
## 步驟 4：建立 AWS 角色
在本節中，您會建立 CodeCatalyst AWS 工作流程運作所需的 IAM 角色。這些角色包括：
+ **組建角色** – 授予 CodeCatalyst 組建動作 （在工作流程中） 存取 AWS 您的帳戶和寫入 Amazon ECR 和 Amazon EC2 的許可。
+ **部署角色** – 授予 CodeCatalyst **部署到 ECS** 動作 （在工作流程中） 存取 AWS 您的帳戶、Amazon ECS 和其他一些 AWS 服務的許可。
如需 IAM 角色的詳細資訊，請參閱*AWS Identity and Access Management 《 使用者指南*》中的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
**注意**
若要節省時間，您可以建立稱為角色的單一`CodeCatalystWorkflowDevelopmentRole-spaceName`角色，而不是先前列出的兩個角色。如需詳細資訊，請參閱[為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有非常廣泛的許可，這可能會構成安全風險。我們建議您只在安全性較少的教學課程和案例中使用此角色。本教學假設您正在建立先前列出的兩個角色。
若要建立建置和部署角色，您可以使用 AWS 管理主控台 或 AWS CLI。
------
#### [ AWS 管理主控台 ]
若要建立建置和部署角色，請完成下列一系列程序。
**建立建置角色**
1. 建立角色的政策，如下所示：
1. 登入 AWS。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇**政策**。
1. 選擇 **Create policy** (建立政策)。
1. 請選擇 **JSON** 標籤。
1. 刪除現有的程式碼。
1. 貼上以下程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:*",
"ec2:*"
],
"Resource": "*"
}
]
}
```
------
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用之後縮小政策的範圍。
```
"Resource": "*"
```
1. 選擇下**一步：標籤**。
1. 選擇下**一步：檢閱**。
1. 在**名稱**中，輸入：
```
codecatalyst-ecs-build-policy
```
1. 選擇**建立政策**。
您現在已建立許可政策。
1. 建立建置角色，如下所示：
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 選擇**自訂信任政策**。
1. 刪除現有的自訂信任政策。
1. 新增下列自訂信任政策：
1. 選擇**下一步**。
1. 在**許可政策**中，搜尋 `codecatalyst-ecs-build-policy`，選取其核取方塊。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-ecs-build-role
```
1. 針對**角色描述**，輸入：
```
CodeCatalyst ECS build role
```
1. 選擇建**立角色**。
您現在已建立具有許可政策和信任政策的建置角色。
1. 取得建置角色 ARN，如下所示：
1. 在導覽窗格中，選擇**角色**。
1. 在搜尋方塊中，輸入您剛建立的角色名稱 (`codecatalyst-ecs-build-role`)。
1. 從清單中選擇角色。
角色的**摘要**頁面隨即出現。
1. 在頂端複製 **ARN** 值。供稍後使用。
**建立部署角色**
1. 建立角色的政策，如下所示：
1. 登入 AWS。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇**政策**。
1. 選擇**建立政策**。
1. 請選擇 **JSON** 標籤。
1. 刪除現有的程式碼。
1. 貼上以下程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Action":[
"ecs:DescribeServices",
"ecs:CreateTaskSet",
"ecs:DeleteTaskSet",
"ecs:ListClusters",
"ecs:RegisterTaskDefinition",
"ecs:UpdateServicePrimaryTaskSet",
"ecs:UpdateService",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:ModifyListener",
"elasticloadbalancing:DescribeRules",
"elasticloadbalancing:ModifyRule",
"lambda:InvokeFunction",
"lambda:ListFunctions",
"cloudwatch:DescribeAlarms",
"sns:Publish",
"sns:ListTopics",
"s3:GetObject",
"s3:GetObjectVersion",
"codedeploy:CreateApplication",
"codedeploy:CreateDeployment",
"codedeploy:CreateDeploymentGroup",
"codedeploy:GetApplication",
"codedeploy:GetDeployment",
"codedeploy:GetDeploymentGroup",
"codedeploy:ListApplications",
"codedeploy:ListDeploymentGroups",
"codedeploy:ListDeployments",
"codedeploy:StopDeployment",
"codedeploy:GetDeploymentTarget",
"codedeploy:ListDeploymentTargets",
"codedeploy:GetDeploymentConfig",
"codedeploy:GetApplicationRevision",
"codedeploy:RegisterApplicationRevision",
"codedeploy:BatchGetApplicationRevisions",
"codedeploy:BatchGetDeploymentGroups",
"codedeploy:BatchGetDeployments",
"codedeploy:BatchGetApplications",
"codedeploy:ListApplicationRevisions",
"codedeploy:ListDeploymentConfigs",
"codedeploy:ContinueDeployment"
],
"Resource":"*",
"Effect":"Allow"
},{"Action":[
"iam:PassRole"
],
"Effect":"Allow",
"Resource":"*",
"Condition":{"StringLike":{"iam:PassedToService":[
"ecs-tasks.amazonaws.com",
"codedeploy.amazonaws.com"
]
}
}
}]
}
```
------
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元。之後，您可以使用資源名稱縮小政策的範圍。
```
"Resource": "*"
```
1. 選擇下**一步：標籤**。
1. 選擇下**一步：檢閱**。
1. 在**名稱**中，輸入：
```
codecatalyst-ecs-deploy-policy
```
1. 選擇**建立政策**。
您現在已建立許可政策。
1. 建立部署角色，如下所示：
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 選擇**自訂信任政策**。
1. 刪除現有的自訂信任政策。
1. 新增下列自訂信任政策：
1. 選擇**下一步**。
1. 在**許可政策**中，搜尋 `codecatalyst-ecs-deploy-policy`，選取其核取方塊。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-ecs-deploy-role
```
1. 針對**角色描述**，輸入：
```
CodeCatalyst ECS deploy role
```
1. 選擇建**立角色**。
您現在已建立具有信任政策的部署角色。
1. 取得部署角色 ARN，如下所示：
1. 在導覽窗格中，選擇**角色**。
1. 在搜尋方塊中，輸入您剛建立的角色名稱 (`codecatalyst-ecs-deploy-role`)。
1. 從清單中選擇角色。
角色的**摘要**頁面隨即出現。
1. 在頂端複製 **ARN** 值。供稍後使用。
------
#### [ AWS CLI ]
若要建立建置和部署角色，請完成下列一系列程序。
**為兩個角色建立信任政策**
作為 `CodeCatalystECSUser`，在 中 AWS CloudShell建立信任政策檔案：
1. 建立 檔案：
```
cat > codecatalyst-ecs-trust-policy.json
```
1. 在終端機提示中，貼上下列程式碼：
1. 將游標放在最後一個大括號 () 之後`}`。
1. 按 **Enter** ，然後按 **Ctrl\$1d** 儲存檔案並退出貓。
**建立建置政策和建置角色**
1. 建立建置政策：
1. 作為 `CodeCatalystECSUser`，在 中 AWS CloudShell建立建置政策檔案：
```
cat > codecatalyst-ecs-build-policy.json
```
1. 出現提示時，輸入下列程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:*",
"ec2:*"
],
"Resource": "*"
}
]
}
```
------
1. 將游標放在最後一個大括號 () 之後`}`。
1. 按 **Enter** ，然後按 **Ctrl\$1d** 儲存檔案並退出貓。
1. 將建置政策新增至 AWS：
```
aws iam create-policy \
--policy-name codecatalyst-ecs-build-policy \
--policy-document file://codecatalyst-ecs-build-policy.json
```
1. 在命令輸出中，記下 `"arn":`值，例如 `arn:aws:iam::111122223333:policy/codecatalyst-ecs-build-policy`。您稍後需要此 ARN。
1. 建立建置角色，並將信任政策連接至該角色：
```
aws iam create-role \
--role-name codecatalyst-ecs-build-role \
--assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
```
1. 將建置政策連接至建置角色：
```
aws iam attach-role-policy \
--role-name codecatalyst-ecs-build-role \
--policy-arn arn:aws:iam::111122223333:policy/codecatalyst-ecs-build-policy
```
其中 *arn：aws：iam：：111122223333：policy/codecatalyst-ecs-build-policy* 會取代為您先前記下的建置政策的 ARN。
1. 顯示建置角色的詳細資訊：
```
aws iam get-role \
--role-name codecatalyst-ecs-build-role
```
1. 請記下角色`"Arn":`的值，例如 `arn:aws:iam::111122223333:role/codecatalyst-ecs-build-role`。您稍後需要此 ARN。
**建立部署政策和部署角色**
1. 建立部署政策：
1. 在 中， AWS CloudShell建立部署政策檔案：
```
cat > codecatalyst-ecs-deploy-policy.json
```
1. 出現提示時，輸入下列程式碼：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Action":[
"ecs:DescribeServices",
"ecs:CreateTaskSet",
"ecs:DeleteTaskSet",
"ecs:ListClusters",
"ecs:RegisterTaskDefinition",
"ecs:UpdateServicePrimaryTaskSet",
"ecs:UpdateService",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:ModifyListener",
"elasticloadbalancing:DescribeRules",
"elasticloadbalancing:ModifyRule",
"lambda:InvokeFunction",
"lambda:ListFunctions",
"cloudwatch:DescribeAlarms",
"sns:Publish",
"sns:ListTopics",
"s3:GetObject",
"s3:GetObjectVersion",
"codedeploy:CreateApplication",
"codedeploy:CreateDeployment",
"codedeploy:CreateDeploymentGroup",
"codedeploy:GetApplication",
"codedeploy:GetDeployment",
"codedeploy:GetDeploymentGroup",
"codedeploy:ListApplications",
"codedeploy:ListDeploymentGroups",
"codedeploy:ListDeployments",
"codedeploy:StopDeployment",
"codedeploy:GetDeploymentTarget",
"codedeploy:ListDeploymentTargets",
"codedeploy:GetDeploymentConfig",
"codedeploy:GetApplicationRevision",
"codedeploy:RegisterApplicationRevision",
"codedeploy:BatchGetApplicationRevisions",
"codedeploy:BatchGetDeploymentGroups",
"codedeploy:BatchGetDeployments",
"codedeploy:BatchGetApplications",
"codedeploy:ListApplicationRevisions",
"codedeploy:ListDeploymentConfigs",
"codedeploy:ContinueDeployment"
],
"Resource":"*",
"Effect":"Allow"
},{"Action":[
"iam:PassRole"
],
"Effect":"Allow",
"Resource":"*",
"Condition":{"StringLike":{"iam:PassedToService":[
"ecs-tasks.amazonaws.com",
"codedeploy.amazonaws.com"
]
}
}
}]
}
```
------
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用後縮小政策範圍。
```
"Resource": "*"
```
1. 將游標放在最後一個大括號 () 之後`}`。
1. 按 **Enter** ，然後按 **Ctrl\$1d** 儲存檔案並退出貓。
1. 將部署政策新增至 AWS：
```
aws iam create-policy \
--policy-name codecatalyst-ecs-deploy-policy \
--policy-document file://codecatalyst-ecs-deploy-policy.json
```
1. 在命令輸出中，記下部署政策`"arn":`的值，例如 `arn:aws:iam::111122223333:policy/codecatalyst-ecs-deploy-policy`。您稍後需要此 ARN。
1. 建立部署角色，並將信任政策連接至該角色：
```
aws iam create-role \
--role-name codecatalyst-ecs-deploy-role \
--assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
```
1. 將部署政策連接至部署角色，其中 *arn：aws：iam：：111122223333：policy/codecatalyst-ecs-deploy-policy* 會取代為您先前記下的部署政策的 ARN。
```
aws iam attach-role-policy \
--role-name codecatalyst-ecs-deploy-role \
--policy-arn arn:aws:iam::111122223333:policy/codecatalyst-ecs-deploy-policy
```
1. 顯示部署角色的詳細資訊：
```
aws iam get-role \
--role-name codecatalyst-ecs-deploy-role
```
1. 請記下角色`"Arn":`的值，例如 `arn:aws:iam::111122223333:role/codecatalyst-ecs-deploy-role`。您稍後需要此 ARN。
------
## 步驟 5：將 AWS 角色新增至 CodeCatalyst
在此步驟中，您將建置角色 (`codecatalyst-ecs-build-role`) 和部署角色 (`codecatalyst-ecs-deploy-role`) 新增至您空間中的 CodeCatalyst 帳戶連線。
**將建置和部署角色新增至您的帳戶連線**
1. 在 CodeCatalyst 中，導覽至您的空間。
1. 選擇**AWS 帳戶**。帳戶連線清單隨即顯示。
1. 選擇代表您建立建置和部署角色 AWS 的帳戶的帳戶連線。
1. **從管理主控台選擇 AWS 管理角色**。
**將 IAM 角色新增至 Amazon CodeCatalyst 空間**頁面隨即出現。您可能需要登入才能存取頁面。
1. 選取**新增您在 IAM 中建立的現有角色**。
下拉式清單隨即出現。清單會顯示具有信任政策的所有 IAM 角色，其中包含 `codecatalyst-runner.amazonaws.com``codecatalyst.amazonaws.com`和服務主體。
1. 在下拉式清單中，選擇 `codecatalyst-ecs-build-role`，然後選擇**新增角色**。
**注意**
如果您看到 `The security token included in the request is invalid`，可能是因為您沒有適當的許可。若要修正此問題，請以您建立 CodeCatalyst 空間時使用 AWS 的帳戶重新登入 AWS 。
1. 選擇**新增 IAM 角色**，選擇**新增您在 IAM 中建立的現有角色**，然後在下拉式清單中選擇 `codecatalyst-ecs-deploy-role`。選擇 **Add role (新增角色)**。
您現在已將建置和部署角色新增至您的空間。
1. 複製 **Amazon CodeCatalyst 顯示名稱**的值。稍後建立工作流程時，您將需要此值。
## 步驟 6：建立來源儲存庫
在此步驟中，您會在 CodeCatalyst 中建立來源儲存庫。此儲存庫會存放教學課程的來源檔案，例如任務定義檔案。
如需來源儲存庫的詳細資訊，請參閱 [建立來源儲存庫](source-repositories-create.md)。
**建立來源儲存庫**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 導覽至您的專案 `codecatalyst-ecs-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇**新增儲存庫**，然後選擇**建立儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
codecatalyst-ecs-source-repository
```
1. 選擇**建立**。
## 步驟 7：新增來源檔案
在本節中，您將 Hello World 來源檔案新增至 CodeCatalyst 儲存庫 `codecatalyst-ecs-source-repository`。它們包含：
+ `index.html` 檔案 – 在瀏覽器中顯示 Hello World 訊息。
+ Dockerfile – 描述要用於 Docker 映像的基本映像，以及要套用的 Docker 命令。
+ `taskdef.json` 檔案 – 定義在叢集中啟動任務時要使用的 Docker 映像。
資料夾結構如下所示：
```
.
|— public-html
| |— index.html
|— Dockerfile
|— taskdef.json
```
**注意**
下列指示說明如何使用 CodeCatalyst 主控台新增檔案，但您可以視需要使用 Git。如需詳細資訊，請參閱[複製來源儲存庫](source-repositories-clone.md)。
**Topics**
+ [index.html](#deploy-tut-ecs-source-files-index)
+ [Dockerfile](#deploy-tut-ecs-source-files-dockerfile)
+ [taskdef.json](#deploy-tut-ecs-source-files-taskdef)
### index.html
`index.html` 檔案會在瀏覽器中顯示 Hello World 訊息。
**新增 index.html 檔案**
1. 在 CodeCatalyst 主控台中，前往您的來源儲存庫 `codecatalyst-ecs-source-repository`。
1. 在**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
public-html/index.html
```
**重要**
請務必包含 `public-html/`字首，以建立相同名稱的資料夾。`index.html` 預期會位於此資料夾中。
1. 在文字方塊中，輸入下列程式碼：
```
Hello World
Hello World
```
1. 選擇**遞交**，然後再次選擇**遞交**。
`index.html` 會新增至`public-html`資料夾中的儲存庫。
### Dockerfile
Dockerfile 說明要使用的基本 Docker 映像，以及要套用的 Docker 命令。如需 Dockerfile 的詳細資訊，請參閱 [Dockerfile 參考](https://docs.docker.com/engine/reference/builder/)。
此處指定的 Dockerfile 表示使用 Apache 2.4 基礎映像 (`httpd`)。它還包含將名為 的來源檔案複製到提供網頁之 Apache 伺服器上`index.html`資料夾的說明。Dockerfile 中的`EXPOSE`說明會告知 Docker 容器正在接聽連接埠 80。
**新增 Dockerfile**
1. 在來源儲存庫中，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
Dockerfile
```
請勿包含副檔名。
**重要**
Dockerfile 必須位於儲存庫的根資料夾中。工作流程的 `Docker build`命令預期會存在。
1. 在文字方塊中，輸入下列程式碼：
```
FROM httpd:2.4
COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
EXPOSE 80
```
1. 選擇**遞交**，然後再次選擇**遞交**。
Dockerfile 會新增至您的儲存庫。
### taskdef.json
您在此步驟中新增的檔案與您已在 中指定的`taskdef.json`檔案相同，差異[步驟 2：將預留位置應用程式部署至 Amazon ECS](#deploy-tut-ecs-placeholder)如下：
這裡的任務定義會使用幾個變數來表示影像： `$REPOSITORY_URI`和 ，而不是在 `image:` 欄位 (`httpd:2.4`) 中指定硬式編碼的 Docker 影像名稱`$IMAGE_TAG`。當您在後續步驟中執行工作流程時，工作流程建置動作所產生的實際值會取代這些變數。
如需任務定義參數的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[任務定義參數](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html)。
**新增 taskdef.json 檔案**
1. 在來源儲存庫中，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
taskdef.json
```
1. 在文字方塊中，輸入下列程式碼：
```
{
"executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
"containerDefinitions": [
{
"name": "codecatalyst-ecs-container",
# The $REPOSITORY_URI and $IMAGE_TAG variables will be replaced
# by the workflow at build time (see the build action in the
# workflow)
"image": $REPOSITORY_URI:$IMAGE_TAG,
"essential": true,
"portMappings": [
{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
}
]
}
],
"requiresCompatibilities": [
"FARGATE"
],
"networkMode": "awsvpc",
"cpu": "256",
"memory": "512",
"family": "codecatalyst-ecs-task-def"
}
```
在上述程式碼中，取代
*arn：aws：iam：：account\$1ID：role/codecatalyst-ecs-task-execution-role*
使用您在 中記下之任務執行角色的 ARN[建立任務執行角色](#deploy-tut-ecs-create-task-execution-role)。
1. 選擇**遞交**，然後再次選擇**遞交**。
`taskdef.json` 檔案會新增至您的儲存庫。
## 步驟 8：建立和執行工作流程
在此步驟中，您會建立工作流程來取得來源檔案、將其建置到 Docker 映像中，然後將映像部署到您的 Amazon ECS 叢集。此部署會取代現有的 Apache 預留位置應用程式。
工作流程包含下列依順序執行的建置區塊：
+ 觸發條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ 建置動作 (`BuildBackend`) – 觸發時，動作會使用 Dockerfile 建置 Docker 映像，並將映像推送至 Amazon ECR。建置動作也會`taskdef.json`使用正確的`image`欄位值更新 ，然後建立此檔案的輸出成品。此成品會用作部署動作的輸入，接下來是 。
如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ 部署動作 (`DeployToECS`) – 完成建置動作後，部署動作會尋找建置動作 (`TaskDefArtifact`) 產生的輸出成品、尋找`taskdef.json`其中的 ，並向您的 Amazon ECS 服務註冊。然後，服務會遵循 `taskdef.json` 檔案中的指示，在您的 Amazon ECS 叢集內執行三個 Amazon ECS 任務，以及相關聯的 Hello World Docker 容器。
**建立工作流程**
1. 在 CodeCatalyst 主控台的導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 針對**來源儲存庫**，選擇 `codecatalyst-ecs-source-repository`。
1. 針對**分支**，選擇 `main`。
1. 選擇**建立**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML 程式碼：
**注意**
在後續的 YAML 程式碼中，您可以視需要省略這些`Connections:`區段。如果您省略這些區段，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含 中所述兩個角色的許可和信任政策[步驟 5：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-ecs-import-roles)。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
```
Name: codecatalyst-ecs-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
BuildBackend:
Identifier: aws/build@v1
Environment:
Name: codecatalyst-ecs-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-ecs-build-role
Inputs:
Sources:
- WorkflowSource
Variables:
- Name: REPOSITORY_URI
Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo
- Name: IMAGE_TAG
Value: ${WorkflowSource.CommitId}
Configuration:
Steps:
#pre_build:
- Run: echo Logging in to Amazon ECR...
- Run: aws --version
- Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
#build:
- Run: echo Build started on `date`
- Run: echo Building the Docker image...
- Run: docker build -t $REPOSITORY_URI:latest .
- Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
#post_build:
- Run: echo Build completed on `date`
- Run: echo Pushing the Docker images...
- Run: docker push $REPOSITORY_URI:latest
- Run: docker push $REPOSITORY_URI:$IMAGE_TAG
# Replace the variables in taskdef.json
- Run: find taskdef.json -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
- Run: find taskdef.json -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
- Run: cat taskdef.json
# The output artifact will be a zip file that contains a task definition file.
Outputs:
Artifacts:
- Name: TaskDefArtifact
Files:
- taskdef.json
DeployToECS:
DependsOn:
- BuildBackend
Identifier: aws/ecs-deploy@v1
Environment:
Name: codecatalyst-ecs-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-ecs-deploy-role
Inputs:
Sources: []
Artifacts:
- TaskDefArtifact
Configuration:
region: us-west-2
cluster: codecatalyst-ecs-cluster
service: codecatalyst-ecs-service
task-definition: taskdef.json
```
在上述程式碼中，取代：
+ 兩個 *codecatalyst-ecs-environment* 執行個體，其名稱為您在 中建立的環境[先決條件](#deploy-tut-ecs-prereqs)。
+ 這兩個 *codecatalyst-account-connection* 執行個體都具有您帳戶連線的顯示名稱。顯示名稱可能是數字。如需詳細資訊，請參閱[步驟 5：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-ecs-import-roles)。
+ *codecatalyst-ecs-build-role*，內含您在 中建立的建置角色名稱[步驟 4：建立 AWS 角色](#deploy-tut-ecs-build-deploy-roles)。
+ *111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo* （在 `Value:` 屬性中），其中包含您在 中建立的 Amazon ECR 儲存庫的 URI[步驟 3：建立 Amazon ECR 映像儲存庫](#deploy-tut-ecs-ecr)。
+ *111122223333.dkr.ecr.us-west-2.amazonaws.com* （在 `Run: aws ecr`命令中），不含映像尾碼 () 的 Amazon ECR 儲存庫的 URI`/codecatalyst-ecs-image-repo`。
+ *codecatalyst-ecs-deploy-role*，內含您在 中建立的部署角色名稱[步驟 4：建立 AWS 角色](#deploy-tut-ecs-build-deploy-roles)。
+ 使用 AWS 區域碼的 *us-west-2* 這兩個執行個體。如需區域代碼清單，請參閱《》中的[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)*AWS 一般參考*。
**注意**
如果您決定不建立建置和部署角色，請將 *codecatalyst-ecs-build-role* 和 *codecatalyst-ecs-deploy-role* 取代為`CodeCatalystWorkflowDevelopmentRole-spaceName`角色的名稱。如需有關此角色的詳細資訊，請參閱 [步驟 4：建立 AWS 角色](#deploy-tut-ecs-build-deploy-roles)。
**提示**
您可以使用**轉譯 Amazon ECS 任務定義**動作來更新儲存庫和映像名稱，而不是使用先前工作流程程式碼中顯示的 和 `find``sed`命令。如需詳細資訊，請參閱[修改 Amazon ECS 任務定義](render-ecs-action.md)。
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇 **Commit** (遞交)。
1. 在**遞交工作流程**對話方塊中，輸入下列內容：
1. 針對**遞交訊息**，移除文字並輸入：
```
Add first workflow
```
1. 針對**儲存庫**，選擇 `codecatalyst-ecs-source-repository`。
1. 針對**分支名稱**，選擇主要。
1. 選擇 **Commit** (遞交)。
您現在已建立工作流程。由於工作流程頂端定義的觸發條件，工作流程執行會自動啟動。具體而言，當您將`workflow.yaml`檔案遞交 （並推送） 到您的來源儲存庫時，觸發會啟動工作流程執行。
**檢視工作流程執行進度**
1. 在 CodeCatalyst 主控台的導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇您剛建立的工作流程 `codecatalyst-ecs-workflow`。
1. 選擇 **BuildBackend** 以查看建置進度。
1. 選擇 **DeployToECS** 以查看部署進度。
如需檢視執行詳細資訊的詳細資訊，請參閱 [檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
**驗證部署**
1. 開啟 Amazon ECS 傳統主控台，網址為 [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/)。
1. 選擇您的叢集 `codecatalyst-ecs-cluster`。
1. 選擇 **Tasks** (任務) 索引標籤。
1. 選擇三個任務中的任一個。
1. 在**公有 IP** 欄位中，選擇**開啟的地址**。
瀏覽器中會出現「Hello World」頁面，指出 Amazon ECS 服務已成功部署您的應用程式。
## 步驟 9：變更來源檔案
在本節中，您會變更來源儲存庫中的 `index.html` 檔案。此變更會導致工作流程建立新的 Docker 映像、使用遞交 ID 標記它、將其推送至 Amazon ECR，並將其部署至 Amazon ECS。
**若要變更 index.html**
1. 在 CodeCatalyst 主控台的導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**，然後選擇您的儲存庫 `codecatalyst-ecs-source-repository`。
1. 選擇 `public-html` (下一步)，然後選擇 `index.html` (完成)。
內容`index.html`隨即出現。
1. 選擇**編輯**。
1. 在第 14 行，將`Hello World`文字變更為 `Tutorial complete!`。
1. 選擇**遞交**，然後再次選擇**遞交**。
遞交會導致新的工作流程執行開始。
1. （選用） 前往來源儲存庫的主頁面，選擇**檢視遞交**，然後記下`index.html`變更的遞交 ID。
1. 觀看部署進度：
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇 `codecatalyst-ecs-workflow`以檢視最新的執行。
1. 選擇 **BuildBackend** 和 **DeployToECS** 以查看工作流程執行進度。
1. 確認您的應用程式已更新，如下所示：
1. 開啟 Amazon ECS 傳統主控台，網址為 [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/)。
1. 選擇您的叢集 `codecatalyst-ecs-cluster`。
1. 選擇 **Tasks** (任務) 索引標籤。
1. 選擇三個任務中的任一個。
1. 在**公有 IP** 欄位中，選擇**開啟的地址**。
`Tutorial complete!` 頁面隨即出現。
1. （選用） 在 中 AWS，切換至 Amazon ECR 主控台，並確認新的 Docker 映像已使用步驟 6 的遞交 ID 標記。
## 清除
清除本教學課程中使用的檔案和服務，以避免收取這些檔案和服務的費用。
在 中 AWS 管理主控台，依此順序清除：
1. 在 Amazon ECS 中，執行下列動作：
1. 刪除 `codecatalyst-ecs-service`。
1. 刪除 `codecatalyst-ecs-cluster`。
1. 取消註冊 `codecatalyst-ecs-task-definition`。
1. 在 Amazon ECR 中，刪除 `codecatalyst-ecs-image-repo`。
1. 在 Amazon EC2 中，刪除 `codecatalyst-ecs-security-group`。
1. 在 IAM Identity Center 中，刪除：
1. `CodeCatalystECSUser`
1. `CodeCatalystECSPermissionSet`
在 CodeCatalyst 主控台中，如下所示進行清除：
1. 刪除 `codecatalyst-ecs-workflow`。
1. 刪除 `codecatalyst-ecs-environment`。
1. 刪除 `codecatalyst-ecs-source-repository`。
1. 刪除 `codecatalyst-ecs-project`。
在本教學課程中，您已了解如何使用 CodeCatalyst 工作流程和部署至 Amazon ECS 動作，將應用程式**部署至 Amazon ECS** 服務。
# 將 'Deploy 新增至 Amazon ECS' 動作
使用下列指示將**部署至 Amazon ECS** 動作新增至您的工作流程。
------
#### [ Visual ]
**使用視覺化編輯器將 'Deploy 新增至 Amazon ECS' 動作**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署至 Amazon ECS** 動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署到 Amazon ECS**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「部署到 Amazon ECS」動作 YAML](deploy-action-ref-ecs.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器將 'Deploy 新增至 Amazon ECS' 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署至 Amazon ECS** 動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署到 Amazon ECS**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「部署到 Amazon ECS」動作 YAML](deploy-action-ref-ecs.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 「部署到 Amazon ECS」變數
**部署至 Amazon ECS** 動作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| 叢集 | 在工作流程執行期間部署至 的 Amazon ECS 叢集名稱。 範例：`codecatalyst-ecs-cluster` |
| deployment-platform | 部署平台的名稱。 硬式編碼為 `AWS:ECS`。 |
| 服務 | 在工作流程執行期間部署至 的 Amazon ECS 服務名稱。 範例：`codecatalyst-ecs-service` |
| task-definition-arn | 在工作流程執行期間註冊之任務定義的 Amazon Resource Name (ARN)。 範例：`arn:aws:ecs:us-west-2:111122223333:task-definition/codecatalyst-task-def:8`上述範例中`:8`的 表示已註冊的修訂。 |
| deployment-url | Amazon ECS 主控台**事件**索引標籤的連結，您可以在其中檢視與工作流程執行相關聯的 Amazon ECS 部署詳細資訊。 範例：`https://console.aws.amazon.com/ecs/home?region=us-west-2#/clusters/codecatalyst-ecs-cluster/services/codecatalyst-ecs-service/events` |
| region | 在工作流程執行期間 AWS 區域 部署至 的 區域碼。 範例：`us-west-2` |
# 「部署到 Amazon ECS」動作 YAML
以下是**部署至 Amazon ECS **動作的 YAML 定義。若要了解如何使用此動作，請參閱 [使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)。
此動作定義以區段形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
ECSDeployAction\$1nn:
Identifier: aws/ecs-deploy@v1
DependsOn:
- build-action
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- task-definition-artifact
Configuration:
region: us-east-1
cluster: ecs-cluster
service: ecs-service
task-definition: task-definition-path
force-new-deployment: false|true
codedeploy-appspec: app-spec-file-path
codedeploy-application: application-name
codedeploy-deployment-group: deployment-group-name
codedeploy-deployment-description: deployment-description
```
## ECSDeployAction
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
預設：`ECSDeployAction_nn`。
對應的 UI：組態索引標籤/**動作顯示名稱**
## Identifier
(*ECSDeployAction*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/ecs-deploy@v1`。
對應的 UI：工作流程圖表/ECSDeployAction\$1nn/**aws/ecs-deploy@v1** 標籤
## DependsOn
(*ECSDeployAction*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*ECSDeployAction*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*ECSDeployAction*/Compute/**Type**)
（如果[Compute](#deploy.action.ecs.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化的動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/進階 - 選用/**運算類型**
## Fleet
(*ECSDeployAction*/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`。
對應的 UI：組態索引標籤/進階 - 選用/**運算機群**
## Timeout
(*ECSDeployAction*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Environment
(*ECSDeployAction*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*ECSDeployAction*/Environment/**Name**)
（如果[Environment](#deploy.action.ecs.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*ECSDeployAction*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*ECSDeployAction*/Environment/Connections/**Name**)
（如果[Connections](#deploy.action.ecs.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What*我的環境*是什麼？/三個點選單/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/ **AWS 帳戶連線**
## Role
(*ECSDeployAction*/Environment/Connections/**Role**)
（如果[Connections](#deploy.action.ecs.environment.connections)包含 則為必要）
指定**部署至 Amazon ECS **動作用來存取的 IAM 角色名稱 AWS。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Action":[
"ecs:DescribeServices",
"ecs:CreateTaskSet",
"ecs:DeleteTaskSet",
"ecs:ListClusters",
"ecs:RegisterTaskDefinition",
"ecs:UpdateServicePrimaryTaskSet",
"ecs:UpdateService",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:ModifyListener",
"elasticloadbalancing:DescribeRules",
"elasticloadbalancing:ModifyRule",
"lambda:InvokeFunction",
"lambda:ListFunctions",
"cloudwatch:DescribeAlarms",
"sns:Publish",
"sns:ListTopics",
"s3:GetObject",
"s3:GetObjectVersion",
"codedeploy:CreateApplication",
"codedeploy:CreateDeployment",
"codedeploy:CreateDeploymentGroup",
"codedeploy:GetApplication",
"codedeploy:GetDeployment",
"codedeploy:GetDeploymentGroup",
"codedeploy:ListApplications",
"codedeploy:ListDeploymentGroups",
"codedeploy:ListDeployments",
"codedeploy:StopDeployment",
"codedeploy:GetDeploymentTarget",
"codedeploy:ListDeploymentTargets",
"codedeploy:GetDeploymentConfig",
"codedeploy:GetApplicationRevision",
"codedeploy:RegisterApplicationRevision",
"codedeploy:BatchGetApplicationRevisions",
"codedeploy:BatchGetDeploymentGroups",
"codedeploy:BatchGetDeployments",
"codedeploy:BatchGetApplications",
"codedeploy:ListApplicationRevisions",
"codedeploy:ListDeploymentConfigs",
"codedeploy:ContinueDeployment"
],
"Resource":"*",
"Effect":"Allow"
},{"Action":[
"iam:PassRole"
],
"Effect":"Allow",
"Resource":"*",
"Condition":{"StringLike":{"iam:PassedToService":[
"ecs-tasks.amazonaws.com",
"codedeploy.amazonaws.com"
]
}
}
}]
}
```
------
**注意**
第一次使用角色時，請在資源政策陳述式中使用下列萬用字元，然後在可用的資源名稱縮小政策範圍。
```
"Resource": "*"
```
+ 下列自訂信任政策：
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Inputs
(*ECSDeployAction*/**Inputs**)
(選用)
`Inputs` 區段定義工作流程執行期間 `ECSDeployAction`所需的資料。
**注意**
每個**部署到 Amazon ECS **動作只允許一個輸入 （來源或成品）。
對應的 UI：**輸入**索引標籤
## Sources
(*ECSDeployAction*/Inputs/**Sources**)
（如果您的任務定義檔案存放在來源儲存庫中，則為必要項目）
如果您的任務定義檔案存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的任務定義檔案不包含在來源儲存庫中，它必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*ECSDeployAction*/Inputs/**Artifacts**)
（如果您的任務定義檔案存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要）
如果您要部署的任務定義檔案包含在先前動作產生的成品中，請在此處指定該成品。如果您的任務定義檔案不包含在成品中，它必須位於您的來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**成品 - 選用**
## Configuration
(*ECSDeployAction*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## region
(Configuration/**region**)
(必要)
指定 Amazon ECS 叢集和服務所在的 AWS 區域。如需區域代碼的清單，請參閱《》中的[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)*AWS 一般參考*。
對應的 UI：組態索引標籤/**區域**
## cluster
(*ECSDeployAction*/Configuration/**cluster**)
(必要)
指定現有 Amazon ECS 叢集的名稱。**部署至 Amazon ECS** 動作會將您的容器化應用程式做為任務部署至此叢集。如需 Amazon ECS 叢集的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[叢集](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters)。
對應的 UI：組態索引標籤/**叢集**
## service
(*ECSDeployAction*/Configuration/**service**)
(必要)
指定將執行個體化任務定義檔案的現有 Amazon ECS 服務名稱。此服務必須位於 `cluster` 欄位中指定的叢集下。如需 Amazon ECS 服務的詳細資訊，請參閱《[Amazon Elastic Container Service 開發人員指南》中的 Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) *服務*。
對應的 UI：組態索引標籤/**服務**
## task-definition
(*ECSDeployAction*/Configuration/**task-definition**)
(必要)
指定現有任務定義檔案的路徑。如果檔案位於您的來源儲存庫中，路徑會與來源儲存庫根資料夾相對。如果您的檔案位於先前工作流程動作的成品中，則路徑會與成品根資料夾相對。如需任務定義檔案的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[任務定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)。
對應的 UI：組態索引標籤/**任務定義**
## force-new-deployment
(*ECSDeployAction*/Configuration/**force-new-deployment**)
(必要)
如果啟用，Amazon ECS 服務可以在不變更服務定義的情況下啟動新的部署。強制部署會導致服務停止所有目前正在執行的任務，並啟動新任務。如需強制新部署的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[更新服務](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service.html)。
預設：`false`
對應的 UI：組態索引標籤/**強制新部署服務**
## codedeploy-appspec
(*ECSDeployAction*/Configuration/**codedeploy-appspec**)
（如果您已將 Amazon ECS 服務設定為使用藍/綠部署，則此為必要項目，否則請省略）
指定現有 CodeDeploy 應用程式規格 (AppSpec) 檔案的名稱和路徑。此檔案必須位於 CodeCatalyst 來源儲存庫的根目錄。如需 AppSpec 檔案的詳細資訊，請參閱*AWS CodeDeploy 《 使用者指南*》中的 [CodeDeploy 應用程式規格 (AppSpec) 檔案](https://docs.aws.amazon.com/codedeploy/latest/userguide/application-specification-files.html)。
**注意**
只有在您已將 Amazon ECS 服務設定為執行藍/綠部署時，才提供 CodeDeploy 資訊。對於滾動更新部署 （預設），省略 CodeDeploy 資訊。如需 Amazon ECS 部署的詳細資訊，請參閱《[Amazon Elastic Container Service 開發人員指南》中的 Amazon ECS 部署類型](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-types.html)。 **
**注意**
**CodeDeploy** 欄位可能會隱藏在視覺化編輯器中。若要讓它們出現，請參閱 [為什麼視覺化編輯器中缺少 CodeDeploy 欄位？](troubleshooting-workflows.md#troubleshooting-workflows-codedeploy)。
對應的 UI：組態索引標籤/**CodeDeploy AppSpec**
## codedeploy-application
(*ECSDeployAction*/Configuration/**codedeploy-application**)
（如果`codedeploy-appspec`包含 則為必要）
指定現有 CodeDeploy 應用程式的名稱。如需 CodeDeploy 應用程式的詳細資訊，請參閱*AWS CodeDeploy 《 使用者指南*》[中的在 CodeDeploy 中使用應用程式](https://docs.aws.amazon.com/codedeploy/latest/userguide/applications.html)。
對應的 UI：組態索引標籤/**CodeDeploy 應用程式**
## codedeploy-deployment-group
(*ECSDeployAction*/Configuration/**codedeploy-deployment-group**)
（如果`codedeploy-appspec`包含 則為必要）
指定現有 CodeDeploy 部署群組的名稱。如需 CodeDeploy 部署群組的詳細資訊，請參閱*AWS CodeDeploy 《 使用者指南*[》中的在 CodeDeploy 中使用部署群組](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-groups.html)。
對應的 UI：組態索引標籤/**CodeDeploy 部署群組**
## codedeploy-deployment-description
(*ECSDeployAction*/Configuration/**codedeploy-deployment-description**)
(選用)
指定此動作將建立之部署的描述。如需詳細資訊，請參閱*AWS CodeDeploy 《 使用者指南*》中的[在 CodeDeploy 中使用部署](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployments.html)。
對應的 UI：組態索引標籤/**CodeDeploy 部署描述**
# 使用工作流程部署至 Amazon EKS
**提示**
如需說明如何使用**部署至 Kubernetes 叢集**動作的教學課程，請參閱 [教學課程：將應用程式部署至 Amazon EKS](deploy-tut-eks.md)。
本節說明如何使用 CodeCatalyst 工作流程將容器化應用程式部署至 Kubernetes 叢集。若要達成此目的，您必須將**部署至 Kubernetes 叢集**動作新增至工作流程。此動作會將您的應用程式部署到您在 Amazon Elastic Kubernetes Service (EKS) 中使用一或多個 Kubernetes 資訊清單檔案設定的 Kubernetes 叢集。如需範例資訊清單，請參閱 [deployment.yaml](deploy-tut-eks.md#deploy-tut-eks-source-files-deployment-yml)中的 [教學課程：將應用程式部署至 Amazon EKS](deploy-tut-eks.md)。
如需 Kubernetes 的詳細資訊，請參閱 [Kubernetes 文件](https://kubernetes.io/docs/home/)。
如需 Amazon EKS 的詳細資訊，請參閱[什麼是 Amazon EKS？](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) *Amazon EKS 使用者指南*中的 。
**Topics**
+ [「部署到 Kubernetes 叢集」動作的運作方式](#deploy-action-eks-howitworks)
+ [「部署至 Amazon EKS」動作所使用的執行期映像](#deploy-action-eks-runtime)
+ [教學課程：將應用程式部署至 Amazon EKS](deploy-tut-eks.md)
+ [將 'Deploy 新增至 Kubernetes 叢集' 動作](deploy-action-eks-adding.md)
+ [「部署到 Kubernetes 叢集」變數](deploy-action-eks-variables.md)
+ [「部署到 Kubernetes 叢集」動作 YAML](deploy-action-ref-eks.md)
## 「部署到 Kubernetes 叢集」動作的運作方式
**部署至 Kubernetes 叢集**的運作方式如下：
1. 在執行時間，動作會將 Kubernetes `kubectl`公用程式安裝到執行動作的 CodeCatalyst 運算機器。動作會將 設定為`kubectl`指向您在設定動作時提供的 Amazon EKS 叢集。接下來，需要 `kubectl`公用程式才能執行 `kubectl apply`命令。
1. 動作會執行 `kubectl apply -f my-manifest.yaml`命令，執行 *my-manifest.yaml* 中的指示，將您的應用程式部署為一組容器和 Pod 到設定的叢集。如需此命令的詳細資訊，請參閱 *Kubernetes 參考文件中*的 [kubectl 套用](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply)主題。
## 「部署至 Amazon EKS」動作所使用的執行期映像
**部署至 Amazon EKS** 動作會在 [2022 年 11 月的映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 教學課程：將應用程式部署至 Amazon EKS
在本教學課程中，您將了解如何使用 Amazon CodeCatalyst 工作流程、Amazon EKS 和其他一些 AWS 服務，將容器化應用程式部署至 Amazon Elastic Kubernetes Service。部署的應用程式是簡單的「Hello， World！」 在 Apache Web 伺服器 Docker 映像上建置的網站。本教學課程會逐步解說必要的準備工作，例如設定開發機器和 Amazon EKS 叢集，然後說明如何建立工作流程來建置應用程式並將其部署到叢集。
初始部署完成後，教學會指示您變更應用程式來源。此變更會導致建立新的 Docker 映像，並使用新的修訂資訊推送到您的 Docker 映像儲存庫。然後，Docker 映像的新修訂會部署到 Amazon EKS。
**提示**
您可以使用藍圖，為您完成 Amazon EKS 設定，而不是完成本教學課程。您需要使用 **EKS 應用程式部署**藍圖。如需詳細資訊，請參閱[使用藍圖建立專案](projects-create.md#projects-create-console-template)。
**Topics**
+ [先決條件](#deploy-tut-eks-prereqs)
+ [步驟 1：設定您的開發機器](#deploy-tut-eks-dev-env-create)
+ [步驟 2：建立 Amazon EKS 叢集](#deploy-tut-eks-cluster)
+ [步驟 3：建立 Amazon ECR 映像儲存庫](#deploy-tut-eks-ecr)
+ [步驟 4：新增來源檔案](#deploy-tut-eks-source-files)
+ [步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)
+ [步驟 6：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-eks-import-roles)
+ [步驟 7：更新 ConfigMap](#deploy-tut-eks-configmap)
+ [步驟 8：建立和執行工作流程](#deploy-tut-eks-workflow)
+ [步驟 9：變更來源檔案](#deploy-tut-eks-change)
+ [清除](#deploy-tut-eks-cleanup)
## 先決條件
開始本教學課程之前：
+ 您需要具有連線 AWS 帳戶的 Amazon CodeCatalyst **空間**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在您的空間中，您需要一個名為 的空專案：
```
codecatalyst-eks-project
```
使用**從頭開始**選項來建立此專案。
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
+ 在您的專案中，您需要名為 的空 CodeCatalyst **來源儲存庫**：
```
codecatalyst-eks-source-repository
```
如需詳細資訊，請參閱[將程式碼與 CodeCatalyst 中的來源儲存庫一起存放和協作儲存程式碼並與來源儲存庫協作](source.md)。
+ 在專案中，您需要名為 的 CodeCatalyst CI/CD **環境** （而非開發環境）：
```
codecatalyst-eks-environment
```
設定此環境，如下所示：
+ 選擇任何類型的，例如**非生產**。
+ 將您的帳戶連接到該 AWS 帳戶。
+ 針對**預設 IAM 角色**，選擇任何角色。稍後您將指定不同的角色。
如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
## 步驟 1：設定您的開發機器
本教學課程的第一步是使用您將在本教學課程中使用的幾個工具來設定開發機器。這些工具包括：
+ `eksctl` 公用程式 – 用於建立叢集
+ `kubectl` 公用程式 – 的先決條件 `eksctl`
+ AWS CLI - 也是 的先決條件 `eksctl`
如果您有這些工具，則可以在現有的開發機器上安裝這些工具，也可以使用以雲端為基礎的 CodeCatalyst 開發環境。CodeCatalyst 開發環境的優點是，可輕鬆啟動和關閉，並與其他 CodeCatalyst 服務整合，可讓您以較少的步驟完成本教學課程。
本教學假設您將使用 CodeCatalyst 開發環境。
下列指示說明啟動 CodeCatalyst 開發環境並使用必要工具進行設定的快速方法，但如果您需要詳細說明，請參閱：
+ 本指南中的 [建立開發環境](devenvironment-create.md)。
+ 《**Amazon EKS 使用者指南**》中的[安裝 kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)。
+ 《**Amazon EKS 使用者指南**》中的[安裝或升級 eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html)。
+ *AWS Command Line Interface 《 使用者指南*》中的[安裝或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。
**啟動開發環境**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 導覽至您的專案 `codecatalyst-eks-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇來源儲存庫的名稱 `codecatalyst-eks-source-repository`。
1. 在最上方選擇**建立開發環境**，然後選擇 **AWS Cloud9 （在瀏覽器中）**。
1. 確定已選取**現有分支和主要分支中的工作**，然後選擇**建立**。 ****
您的開發環境會在新的瀏覽器索引標籤中啟動，並將您的儲存庫 (`codecatalyst-eks-source-repository`) 複製到其中。
**安裝和設定 kubectl**
1. 在開發環境終端機中，輸入：
```
curl -o kubectl https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.9/2020-11-02/bin/linux/amd64/kubectl
```
1. 輸入：
```
chmod +x ./kubectl
```
1. 輸入：
```
mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$PATH:$HOME/bin
```
1. 輸入：
```
echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
```
1. 輸入：
```
kubectl version --short --client
```
1. 檢查版本是否出現。
您現在已安裝 `kubectl`。
**安裝和設定 eksctl**
**注意**
`eksctl` 並非嚴格要求，因為您可以`kubectl`改為使用 。不過， `eksctl` 具有將大部分叢集組態自動化的好處，因此是本教學課程建議的工具。
1. 在開發環境終端機中，輸入：
```
curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
```
1. 輸入：
```
sudo cp /tmp/eksctl /usr/bin
```
1. 輸入：
```
eksctl version
```
1. 檢查版本是否出現。
您現在已安裝 `eksctl`。
**驗證 AWS CLI 是否已安裝**
1. 在開發環境終端機中，輸入：
```
aws --version
```
1. 檢查版本是否出現，以確認 AWS CLI 已安裝 。
完成其餘程序， AWS CLI 以使用存取所需的許可來設定 AWS。
**若要設定 AWS CLI**
您必須 AWS CLI 使用存取金鑰和工作階段字符來設定 ，讓它存取 AWS 服務。下列指示提供設定金鑰和字符的快速方法，但如果您想要詳細說明，請參閱*AWS Command Line Interface 《 使用者指南*》中的[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) 。
1. 建立 IAM Identity Center 使用者，如下所示：
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/) 開啟 AWS IAM Identity Center 主控台。
（如果您從未登入 IAM Identity Center，您可能需要選擇**啟用**。)
**注意**
請務必使用連線至 CodeCatalyst 空間 AWS 帳戶 的 登入。您可以透過導覽至您的空間並選擇 **AWS 帳戶索引標籤來驗證哪個帳戶**已連線。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
1. 在導覽窗格中，選擇 **使用者**，然後選擇 **新增使用者**。
1. 在**使用者名稱**中，輸入：
```
codecatalyst-eks-user
```
1. 在**密碼**下，選擇**產生您可以與此使用者共用的一次性密碼**。
1. 在**電子郵件地址**和**確認電子郵件地址**中，輸入 IAM Identity Center 中尚不存在的電子郵件地址。
1. 在**名字**中，輸入：
```
codecatalyst-eks-user
```
1. 在**姓氏**中，輸入：
```
codecatalyst-eks-user
```
1. 在**顯示名稱**中，保留：
```
codecatalyst-eks-user codecatalyst-eks-user
```
1. 選擇**下一步**。
1. 在**新增使用者至群組**頁面上，選擇**下一步**。
1. 在**檢閱和新增使用者**頁面上，檢閱資訊，然後選擇**新增使用者**。
**一次性密碼**對話方塊隨即出現。
1. 選擇**複製**，然後將登入資訊貼到文字檔案。登入資訊包含 AWS 存取入口網站 URL、使用者名稱和一次性密碼。
1. 選擇**關閉**。
1. 建立許可集，如下所示：
1. 在導覽窗格中，選擇**許可集**，然後選擇**建立許可集**。
1. 選擇**預先定義的許可集**，然後選取 **AdministratorAccess**。此政策提供所有 的完整許可 AWS 服務。
1. 選擇**下一步**。
1. 在**許可集名稱**中，移除`AdministratorAccess`並輸入：
```
codecatalyst-eks-permission-set
```
1. 選擇**下一步**。
1. 在**檢閱和建立**頁面上，檢閱資訊，然後選擇**建立**。
1. 將許可集指派給 `codecatalyst-eks-user`，如下所示：
1. 在導覽窗格中，選擇 **AWS 帳戶**，然後選取 AWS 帳戶 您目前登入之 旁的核取方塊。
1. 選擇**指派使用者或群組**。
1. 選擇**使用者**索引標籤。
1. 選取 旁的核取方塊`codecatalyst-eks-user`。
1. 選擇**下一步**。
1. 選取 旁的核取方塊`codecatalyst-eks-permission-set`。
1. 選擇**下一步**。
1. 檢閱資訊，然後選擇**提交**。
您現在已將 `codecatalyst-eks-user`和 `codecatalyst-eks-permission-set` 指派給 AWS 帳戶，並將它們繫結在一起。
1. 取得 `codecatalyst-eks-user`的存取金鑰和工作階段字符，如下所示：
1. 請確定您擁有 AWS 存取入口網站 URL 以及 的使用者名稱和一次性密碼`codecatalyst-eks-user`。您應該稍早已將此資訊複製到文字編輯器。
**注意**
如果您沒有此資訊，請前往 IAM Identity Center 的詳細資訊`codecatalyst-eks-user`頁面，選擇**重設密碼**、**產生一次性密碼 【...】** 和再次**重設密碼**，以在畫面上顯示資訊。
1. 登出 AWS。
1. 將 AWS 存取入口網站 URL 貼到瀏覽器的地址列。
1. 使用 登入：
+ **使用者名稱**：
```
codecatalyst-eks-user
```
+ **密碼**：
*one-time-password*
1. 在**設定新密碼**中，輸入新密碼，然後選擇**設定新密碼**。
畫面上會出現一個**AWS 帳戶**方塊。
1. 選擇 **AWS 帳戶**，然後選擇 AWS 帳戶 您指派`codecatalyst-eks-user`使用者和許可集的 名稱。
1. 在 旁`codecatalyst-eks-permission-set`，選擇**命令列或程式設計存取**。
1. 在頁面中間複製命令。它們看起來類似以下內容：
```
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_SESSION_TOKEN="session-token"
```
...其中 *session-token* 是長隨機字串。
1. 將存取金鑰和工作階段字符新增至 AWS CLI，如下所示：
1. 返回 CodeCatalyst 開發環境。
1. 在終端機提示中，貼上您複製的命令。按 Enter。
您現在已 AWS CLI 使用存取金鑰和工作階段字符設定 。您現在可以使用 AWS CLI 完成本教學課程所需的任務。
**重要**
如果您在本教學課程中的任何時候看到類似如下的訊息：
`Unable to locate credentials. You can configure credentials by running "aws configure".`
或者：
`ExpiredToken: The security token included in the request is expired`
...這是因為您的 AWS CLI 工作階段已過期。在此情況下，*請勿*執行 `aws configure`命令。請改用此程序步驟 4 中以 開頭的指示`Obtain codecatalyst-eks-user's access key and session token`來重新整理工作階段。
## 步驟 2：建立 Amazon EKS 叢集
在本節中，您會在 Amazon EKS 中建立叢集。以下指示說明使用 建立叢集的快速方法`eksctl`，但如果您想要詳細說明，請參閱：
+ 《**Amazon EKS 使用者指南**》中的 [eksctl 入門](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html)
或
+ [主控台入門和《Amazon EKS 使用者指南 AWS CLI](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html)****》中的 （本主題提供建立叢集`kubectl`的說明）
**注意**
CodeCatalyst 與 Amazon EKS 整合不支援[私有叢集](https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html)。
**開始之前**
請確定您已在開發機器上完成下列任務：
+ 安裝 `eksctl`公用程式。
+ 已安裝 `kubectl`公用程式。
+ 安裝 並使用存取金鑰 AWS CLI 和工作階段字符進行設定。
如需如何完成這些任務的資訊，請參閱 [步驟 1：設定您的開發機器](#deploy-tut-eks-dev-env-create)。
**建立叢集**
**重要**
請勿使用 Amazon EKS 服務的使用者介面來建立叢集，因為叢集無法正確設定。使用 `eksctl`公用程式，如下列步驟所述。
1. 前往您的開發環境。
1. 建立叢集和節點：
```
eksctl create cluster --name codecatalyst-eks-cluster --region us-west-2
```
其中：
+ *codecatalyst-eks-cluster* 會取代為您要提供叢集的名稱。
+ *us-west-2* 已取代為您的 區域。
10-20 分鐘後，會出現類似以下內容的訊息：
`EKS cluster "codecatalyst-eks-cluster" in "us-west-2" region is ready`
**注意**
建立叢集時 AWS ，您會看到多個`waiting for CloudFormation stack`訊息。這是預期的行為。
1. 確認您的叢集已成功建立：
```
kubectl cluster-info
```
您將看到類似以下的訊息，指出成功的叢集建立：
```
Kubernetes master is running at https://long-string.gr7.us-west-2.eks.amazonaws.com
CoreDNS is running at https://long-string.gr7.us-west-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
```
## 步驟 3：建立 Amazon ECR 映像儲存庫
在本節中，您會在 Amazon Elastic Container Registry (Amazon ECR) 中建立私有映像儲存庫。此儲存庫會存放教學課程的 Docker 映像。
如需 Amazon ECR 的詳細資訊，請參閱《*Amazon Elastic Container Registry 使用者指南*》。
**在 Amazon ECR 中建立映像儲存庫**
1. 前往您的開發環境。
1. 在 Amazon ECR 中建立空儲存庫：
```
aws ecr create-repository --repository-name codecatalyst-eks-image-repo
```
將 *codecatalyst-eks-image-repo* 取代為您要提供 Amazon ECR 儲存庫的名稱。
本教學假設您已將儲存庫命名為 `codecatalyst-eks-image-repo`。
1. 顯示 Amazon ECR 儲存庫的詳細資訊：
```
aws ecr describe-repositories \
--repository-names codecatalyst-eks-image-repo
```
1. 請記下 `“repositoryUri”:`值，例如 `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo`。
稍後在將儲存庫新增至工作流程時需要它。
## 步驟 4：新增來源檔案
在本節中，您將應用程式來源檔案新增至來源儲存庫 (`codecatalyst-eks-source-repository`)。它們包含：
+ `index.html` 檔案 – 顯示「Hello， World！」 瀏覽器中的 訊息。
+ Dockerfile – 描述要用於 Docker 映像的基本映像，以及要套用的 Docker 命令。
+ `deployment.yaml` 檔案 – 定義 Kubernetes 服務和部署的 Kubernetes 資訊清單。
資料夾結構如下所示：
```
|— codecatalyst-eks-source-repository
|— Kubernetes
|— deployment.yaml
|— public-html
| |— index.html
|— Dockerfile
```
**Topics**
+ [index.html](#deploy-tut-eks-source-files-index)
+ [Dockerfile](#deploy-tut-eks-source-files-dockerfile)
+ [deployment.yaml](#deploy-tut-eks-source-files-deployment-yml)
### index.html
`index.html` 檔案會顯示「Hello， World！」 瀏覽器中的 訊息。
**新增 index.html 檔案**
1. 前往您的開發環境。
1. 在 中`codecatalyst-eks-source-repository`，建立名為 的資料夾`public-html`。
1. 在 中`/public-html`，建立名為 的檔案`index.html`，其中包含下列內容：
```
Hello World
Hello, World!
```
1. 在終端機提示中，輸入：
```
cd /projects/codecatalyst-eks-source-repository
```
1. 新增、遞交和推送：
```
git add .
git commit -m "add public-html/index.html"
git push
```
`index.html` 會新增至`public-html`資料夾中的儲存庫。
### Dockerfile
Dockerfile 說明要使用的基本 Docker 映像，以及要套用的 Docker 命令。如需 Dockerfile 的詳細資訊，請參閱 [Dockerfile 參考](https://docs.docker.com/engine/reference/builder/)。
此處指定的 Dockerfile 表示使用 Apache 2.4 基礎映像 (`httpd`)。它還包含將名為 的來源檔案複製到提供網頁之 Apache 伺服器上的`index.html`資料夾的說明。Dockerfile 中的`EXPOSE`說明會告知 Docker 容器正在接聽連接埠 80。
**新增 Dockerfile**
1. 在 中`codecatalyst-eks-source-repository`，建立名為 的檔案`Dockerfile`，其中包含下列內容：
```
FROM httpd:2.4
COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
EXPOSE 80
```
請勿包含副檔名。
**重要**
Dockerfile 必須位於儲存庫的根資料夾中。工作流程的 `Docker build`命令預期會存在。
1. 新增、遞交和推送：
```
git add .
git commit -m "add Dockerfile"
git push
```
Dockerfile 會新增至您的儲存庫。
### deployment.yaml
在本節中，您將`deployment.yaml`檔案新增至您的儲存庫。`deployment.yaml` 檔案是 Kubernetes 資訊清單，定義兩個**要執行的 Kubernetes 資源類型：「服務和「部署」。
+ 「服務」會將負載平衡器部署到 Amazon EC2。負載平衡器為您提供面向網際網路的公有 URL 和標準連接埠 （連接埠 80)，可用來瀏覽至 'Hello， World！' 應用程式。
+ 「部署」會部署三個 Pod，每個 Pod 都會包含 Docker 容器，其中包含「Hello， World！」 應用程式。這三個 Pod 會部署到您建立叢集時建立的節點上。
本教學課程中的資訊清單很簡短；不過，資訊清單可以包含任意數量的 Kubernetes 資源類型，例如 Pod、任務、輸入和網路政策。此外，如果您的部署很複雜，您可以使用多個資訊清單檔案。
**新增 deployment.yaml 檔案**
1. 在 中`codecatalyst-eks-source-repository`，建立名為 的資料夾`Kubernetes`。
1. 在 中`/Kubernetes`，建立名為 的檔案`deployment.yaml`，其中包含下列內容：
```
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
app: my-app
spec:
type: LoadBalancer
selector:
app: my-app
ports:
- protocol: TCP
port: 80
targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
labels:
app: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: codecatalyst-eks-container
# The $REPOSITORY_URI and $IMAGE_TAG placeholders will be replaced by actual values supplied by the build action in your workflow
image: $REPOSITORY_URI:$IMAGE_TAG
ports:
- containerPort: 80
```
1. 新增、遞交和推送：
```
git add .
git commit -m "add Kubernetes/deployment.yaml"
git push
```
`deployment.yaml` 檔案會新增至名為 的資料夾中的儲存庫`Kubernetes`。
您現在已新增所有來源檔案。
花一點時間仔細檢查您的工作，並確保將所有檔案放在正確的資料夾中。資料夾結構如下所示：
```
|— codecatalyst-eks-source-repository
|— Kubernetes
|— deployment.yaml
|— public-html
| |— index.html
|— Dockerfile
```
## 步驟 5：建立 AWS 角色
在本節中，您會建立 CodeCatalyst AWS 工作流程運作所需的 IAM 角色。這些角色包括：
+ **組建角色** – 授予 CodeCatalyst 組建動作 （在工作流程中） 存取 AWS 您的帳戶和寫入 Amazon ECR 和 Amazon EC2 的許可。
+ **部署角色** – 授予 CodeCatalyst **部署到 Kubernetes 叢集**動作 （在工作流程中） 存取 AWS 您的帳戶和 Amazon EKS 的許可。
如需 IAM 角色的詳細資訊，請參閱*AWS Identity and Access Management 《 使用者指南*》中的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
**注意**
若要節省時間，您可以建立稱為角色的單一`CodeCatalystWorkflowDevelopmentRole-spaceName`角色，而不是先前列出的兩個角色。如需詳細資訊，請參閱[為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有非常廣泛的許可，這可能會構成安全風險。我們建議您只在安全性較少的教學課程和案例中使用此角色。本教學假設您正在建立先前列出的兩個角色。
若要建立建置和部署角色，請完成下列一系列程序。
**1. 為兩個角色建立信任政策**
1. 前往您的開發環境。
1. 在 `Cloud9-long-string`目錄中，建立名為 的檔案`codecatalyst-eks-trust-policy.json`，其中包含下列內容：
**2. 建立建置角色的建置政策**
+ 在 `Cloud9-long-string`目錄中，建立名為 的檔案`codecatalyst-eks-build-policy.json`，其中包含下列內容：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:*",
"ec2:*"
],
"Resource": "*"
}
]
}
```
------
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用之後縮小政策的範圍。
```
"Resource": "*"
```
**3. 建立部署角色的部署政策**
+ 在 `Cloud9-long-string`目錄中，建立名為 的檔案`codecatalyst-eks-deploy-policy.json`，其中包含下列內容：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"eks:DescribeCluster",
"eks:ListClusters"
],
"Resource": "*"
}
]
}
```
------
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用之後縮小政策的範圍。
```
"Resource": "*"
```
您現在已將三個政策文件新增至開發環境。您的目錄結構現在如下所示：
```
|— Cloud9-long-string
|— .c9
|— codecatalyst-eks-source-repository
|— Kubernetes
|— public-html
|— Dockerfile
codecatalyst-eks-build-policy.json
codecatalyst-eks-deploy-policy.json
codecatalyst-eks-trust-policy.json
```
**4. 將建置政策新增至 AWS**
1. 在開發環境終端機中，輸入：
```
cd /projects
```
1. 輸入：
```
aws iam create-policy \
--policy-name codecatalyst-eks-build-policy \
--policy-document file://codecatalyst-eks-build-policy.json
```
1. 按 **Enter**。
1. 在命令輸出中，記下 `"arn":`值，例如 `arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy`。您稍後需要此 ARN。
**5. 將部署政策新增至 AWS**
1. 輸入：
```
aws iam create-policy \
--policy-name codecatalyst-eks-deploy-policy \
--policy-document file://codecatalyst-eks-deploy-policy.json
```
1. 按 **Enter**。
1. 在命令輸出中，記下部署政策`"arn":`的值，例如 `arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy`。您稍後需要此 ARN。
**6. 建立建置角色**
1. 輸入：
```
aws iam create-role \
--role-name codecatalyst-eks-build-role \
--assume-role-policy-document file://codecatalyst-eks-trust-policy.json
```
1. 按 **Enter**。
1. 輸入：
```
aws iam attach-role-policy \
--role-name codecatalyst-eks-build-role \
--policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy
```
其中 *arn：aws：iam：：111122223333：policy/codecatalyst-eks-build-policy* 會取代為您先前記下的建置政策的 ARN。
1. 按 **Enter**。
1. 在終端機提示中，輸入：
```
aws iam get-role \
--role-name codecatalyst-eks-build-role
```
1. 按 **Enter**。
1. 請記下角色`"Arn":`的值，例如 `arn:aws:iam::111122223333:role/codecatalyst-eks-build-role`。您稍後需要此 ARN。
**7. 建立部署角色**
1. 輸入：
```
aws iam create-role \
--role-name codecatalyst-eks-deploy-role \
--assume-role-policy-document file://codecatalyst-eks-trust-policy.json
```
1. 按 **Enter**。
1. 輸入：
```
aws iam attach-role-policy \
--role-name codecatalyst-eks-deploy-role \
--policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy
```
其中 *arn：aws：iam：：111122223333：policy/codecatalyst-eks-deploy-policy* 會取代為您先前記下的部署政策的 ARN。
1. 按 **Enter**。
1. 輸入：
```
aws iam get-role \
--role-name codecatalyst-eks-deploy-role
```
1. 按 **Enter**。
1. 請記下角色`"Arn":`的值，例如 `arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role`。您稍後需要此 ARN。
您現在已建立建置和部署角色，並記下其 ARNs。
## 步驟 6：將 AWS 角色新增至 CodeCatalyst
在此步驟中，您將建置角色 (`codecatalyst-eks-build-role`) 和部署角色 (`codecatalyst-eks-deploy-role`) 新增至您連線至空間 AWS 帳戶 的 。這可讓角色在您的工作流程中使用。
**將建置和部署角色新增至您的 AWS 帳戶**
1. 在 CodeCatalyst 主控台中，導覽至您的空間。
1. 在頂端，選擇**設定**。
1. 在導覽窗格中，選擇**AWS 帳戶**。帳戶清單隨即出現。
1. 在 **Amazon CodeCatalyst 顯示名稱**欄中，複製 AWS 帳戶 您建立建置和部署角色的 顯示名稱。（可能是數字。) 稍後建立工作流程時，您將需要此值。
1. 選擇顯示名稱。
1. **從管理主控台選擇 AWS 管理角色**。
**將 IAM 角色新增至 Amazon CodeCatalyst 空間**頁面隨即出現。您可能需要登入才能存取頁面。
1. 選取**新增您在 IAM 中建立的現有角色**。
下拉式清單隨即出現。清單會顯示建置和部署角色，以及具有包含 `codecatalyst-runner.amazonaws.com``codecatalyst.amazonaws.com`和服務主體之信任政策的任何其他 IAM 角色。
1. 從下拉式清單中，新增：
+ `codecatalyst-eks-build-role`
+ `codecatalyst-eks-deploy-role`
**注意**
如果您看到 `The security token included in the request is invalid`，可能是因為您沒有適當的許可。若要修正此問題，請以您建立 CodeCatalyst 空間時使用 AWS 的帳戶登入 AWS 身分登出 。
1. 返回 CodeCatalyst 主控台並重新整理頁面。
建置和部署角色現在應該會出現在 **IAM 角色**下。
這些角色現在可用於 CodeCatalyst 工作流程。
## 步驟 7：更新 ConfigMap
您必須將您在 中建立的部署角色新增至 [步驟 5：建立 AWS 角色](#deploy-tut-eks-roles) Kubernetes `ConfigMap` 檔案，讓**部署至 Kubernetes 叢集**動作 （在您的工作流程中） 能夠存取叢集並與叢集互動。您可以使用 `eksctl`或 `kubectl` 來執行此任務。
**使用 eksctl 設定 Kubernetes ConfigMap 檔案**
+ 在開發環境終端機中，輸入：
```
eksctl create iamidentitymapping --cluster codecatalyst-eks-cluster --arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role --group system:masters --username codecatalyst-eks-deploy-role --region us-west-2
```
其中：
+ *codecatalyst-eks-cluster* 會取代為 Amazon EKS 叢集的叢集名稱。
+ *arn：aws：iam：：111122223333：role/codecatalyst-eks-deploy-role* 會取代為您在 中建立之部署角色的 ARN[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
+ *codecatalyst-eks-deploy-role* ( 旁`--username`) 會取代為您在 中建立的部署角色名稱[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
**注意**
如果您決定不建立部署角色，請將 *codecatalyst-eks-deploy-role* 取代為`CodeCatalystWorkflowDevelopmentRole-spaceName`角色的名稱。如需有關此角色的詳細資訊，請參閱 [步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
+ *us-west-2* 已取代為您的 區域。
如需此命令的詳細資訊，請參閱[管理 IAM 使用者和角色](https://eksctl.io/usage/iam-identity-mappings/)。
出現類似下列的訊息：
```
2023-06-09 00:58:29 [ℹ] checking arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role against entries in the auth ConfigMap
2023-06-09 00:58:29 [ℹ] adding identity "arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role" to auth ConfigMap
```
**使用 kubectl 設定 Kubernetes ConfigMap 檔案**
1. 在開發環境終端機中，輸入：
```
kubectl edit configmap -n kube-system aws-auth
```
ConfigMap 檔案會顯示在畫面上。
1. 新增紅色斜體的文字：
```
# Please edit the object below. Lines beginning with a '#' will be ignored,
# and an empty file will abort the edit. If an error occurs while saving this file will be
# reopened with the relevant failures.
#
apiVersion: v1
data:
mapRoles: |
- groups:
- system:bootstrappers
- system:nodes
rolearn: arn:aws:iam::111122223333:role/eksctl-codecatalyst-eks-cluster-n-NodeInstanceRole-16BC456ME6YR5
username: system:node:{{EC2PrivateDNSName}}
- groups:
- system:masters
rolearn: arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role
username: codecatalyst-eks-deploy-role
mapUsers: |
[]
kind: ConfigMap
metadata:
creationTimestamp: "2023-06-08T19:04:39Z"
managedFields:
...
```
其中：
+ *arn：aws：iam：：111122223333：role/codecatalyst-eks-deploy-role* 會取代為您在 中建立之部署角色的 ARN[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
+ *codecatalyst-eks-deploy-role* ( 旁`username:`) 會取代為您在 中建立的部署角色名稱[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
**注意**
如果您決定不建立部署角色，請將 *codecatalyst-eks-deploy-role* 取代為`CodeCatalystWorkflowDevelopmentRole-spaceName`角色的名稱。如需有關此角色的詳細資訊，請參閱 [步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
如需詳細資訊，請參閱《**Amazon** [EKS 使用者指南》中的啟用叢集的 IAM 主體存取權](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html)。
您現在已提供部署角色，並透過擴充**部署至 Amazon EKS** 動作，將`system:masters`許可授予您的 Kubernetes 叢集。
## 步驟 8：建立和執行工作流程
在此步驟中，您會建立工作流程來取得來源檔案、將它們建置到 Docker 映像中，然後將映像部署到 Amazon EKS 叢集中的樹莢中。
工作流程包含下列依次執行的建置區塊：
+ 觸發條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ 建置動作 (`BuildBackend`) – 觸發時，動作會使用 Dockerfile 建置 Docker 映像，並將映像推送至 Amazon ECR。建置動作也會使用正確的值更新 `deployment.yaml` 檔案中的 `$REPOSITORY_URI`和 `$IMAGE_TAG`變數，然後建立此檔案和 `Kubernetes` 資料夾中任何其他檔案的輸出成品。在本教學課程中，`Kubernetes`資料夾中唯一的檔案是 ，`deployment.yaml`但您可以包含更多檔案。成品會用作部署動作的輸入，接下來是 。
如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ 部署動作 (`DeployToEKS`) – 完成建置動作時，部署動作會尋找建置動作 (`Manifests`) 產生的輸出成品，並在其中尋找`deployment.yaml`檔案。動作接著會依照 `deployment.yaml` 檔案中的指示執行三個 Pod，每個都包含單一 'Hello， World！' Docker 容器 - Amazon EKS 叢集內部。
**建立工作流程**
1. 前往 CodeCatalyst 主控台。
1. 導覽至您的專案 (`codecatalyst-eks-project`)。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 針對**來源儲存庫**，選擇 `codecatalyst-eks-source-repository`。
1. 針對**分支**，選擇 `main`。
1. 選擇**建立**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML 程式碼以建立新的工作流程定義檔案：
**注意**
如需工作流程定義檔案的詳細資訊，請參閱 [工作流程 YAML 定義](workflow-reference.md)。
**注意**
在下列 YAML 程式碼中，您可以視需要省略這些`Connections:`區段。如果您省略這些區段，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含 中所述兩個角色的許可和信任政策[步驟 6：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-eks-import-roles)。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
```
Name: codecatalyst-eks-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
BuildBackend:
Identifier: aws/build@v1
Environment:
Name: codecatalyst-eks-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-eks-build-role
Inputs:
Sources:
- WorkflowSource
Variables:
- Name: REPOSITORY_URI
Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo
- Name: IMAGE_TAG
Value: ${WorkflowSource.CommitId}
Configuration:
Steps:
#pre_build:
- Run: echo Logging in to Amazon ECR...
- Run: aws --version
- Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
#build:
- Run: echo Build started on `date`
- Run: echo Building the Docker image...
- Run: docker build -t $REPOSITORY_URI:latest .
- Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
#post_build:
- Run: echo Build completed on `date`
- Run: echo Pushing the Docker images...
- Run: docker push $REPOSITORY_URI:latest
- Run: docker push $REPOSITORY_URI:$IMAGE_TAG
# Replace the variables in deployment.yaml
- Run: find Kubernetes/ -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
- Run: find Kubernetes/ -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
- Run: cat Kubernetes/*
# The output artifact will be a zip file that contains Kubernetes manifest files.
Outputs:
Artifacts:
- Name: Manifests
Files:
- "Kubernetes/*"
DeployToEKS:
DependsOn:
- BuildBackend
Identifier: aws/kubernetes-deploy@v1
Environment:
Name: codecatalyst-eks-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-eks-deploy-role
Inputs:
Artifacts:
- Manifests
Configuration:
Namespace: default
Region: us-west-2
Cluster: codecatalyst-eks-cluster
Manifests: Kubernetes/
```
在上述程式碼中，取代：
+ 兩個 *codecatalyst-eks-environment* 執行個體，其名稱為您在 中建立的環境[先決條件](#deploy-tut-eks-prereqs)。
+ 這兩個 *codecatalyst-account-connection* 執行個體都具有您帳戶連線的顯示名稱。顯示名稱可能是數字。如需詳細資訊，請參閱[步驟 6：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-eks-import-roles)。
+ *codecatalyst-eks-build-role*，其中包含您在 中建立的建置角色名稱[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
+ *111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo* （在 `Value:` 屬性中），其中包含您在 中建立的 Amazon ECR 儲存庫的 URI[步驟 3：建立 Amazon ECR 映像儲存庫](#deploy-tut-eks-ecr)。
+ *111122223333.dkr.ecr.us-west-2.amazonaws.com* （在 `Run: aws ecr`命令中），不含映像尾碼 () 的 Amazon ECR 儲存庫的 URI`/codecatalyst-eks-image-repo`。
+ *codecatalyst-eks-deploy-role*，內含您在 中建立的部署角色名稱[步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
+ 使用 AWS 區域碼的 *us-west-2* 這兩個執行個體。如需區域代碼清單，請參閱《》中的[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)*AWS 一般參考*。
**注意**
如果您決定不建立建置和部署角色，請將 *codecatalyst-eks-build-role* 和 *codecatalyst-eks-deploy-role* 取代為`CodeCatalystWorkflowDevelopmentRole-spaceName`角色的名稱。如需有關此角色的詳細資訊，請參閱 [步驟 5：建立 AWS 角色](#deploy-tut-eks-roles)。
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇 **Commit** (遞交)。
1. 在**遞交工作流程**對話方塊中，輸入下列內容：
1. 針對**遞交訊息**，移除文字並輸入：
```
Add first workflow
```
1. 針對**儲存庫**，選擇 `codecatalyst-eks-source-repository`。
1. 針對**分支名稱**，選擇主要。
1. 選擇 **Commit** (遞交)。
您現在已建立工作流程。由於工作流程頂端定義的觸發條件，工作流程執行會自動啟動。具體而言，當您將`workflow.yaml`檔案遞交 （並推送） 至來源儲存庫時，觸發會啟動工作流程執行。
**檢視工作流程執行進度**
1. 在 CodeCatalyst 主控台的導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇您剛建立的工作流程 `codecatalyst-eks-workflow`。
1. 選擇 **BuildBackend** 以查看建置進度。
1. 選擇 **DeployToEKS** 以查看部署進度。
如需檢視執行詳細資訊的詳細資訊，請參閱 [檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
**驗證部署**
1. 前往 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) 開啟 Amazon EC2 主控台。
1. 在左側底部附近，選擇**負載平衡器**。
1. 選取在 Kubernetes 部署中建立的負載平衡器。如果您不確定要選擇哪個負載平衡器，請在標籤索引標籤下尋找下列**標籤**：
+ `kubernetes.io/service-name`
+ `kubernetes.io/cluster/ekstutorialcluster`
1. 選取正確的負載平衡器後，選擇**描述**索引標籤。
1. 將 **DNS 名稱**值複製並貼到瀏覽器的地址列。
'Hello， World！' 網頁會顯示在瀏覽器中，表示您已成功部署應用程式。
## 步驟 9：變更來源檔案
在本節中，您會變更來源儲存庫中的 `index.html` 檔案。此變更會導致工作流程建立新的 Docker 映像、使用遞交 ID 標記它、將其推送至 Amazon ECR，並將其部署至 Amazon ECS。
**若要變更 index.html**
1. 前往您的開發環境。
1. 在終端機提示中，變更至您的來源儲存庫：
```
cd /projects/codecatalyst-eks-source-repository
```
1. 提取最新的工作流程變更：
```
git pull
```
1. 打開 `codecatalyst-eks-source-repository/public-html/index.html`。
1. 在第 14 行，將`Hello, World!`文字變更為 `Tutorial complete!`。
1. 新增、遞交和推送：
```
git add .
git commit -m "update index.html title"
git push
```
工作流程執行會自動啟動。
1. （選用） 輸入：
```
git show HEAD
```
請注意`index.html`變更的遞交 ID。此遞交 ID 將標記到 Docker 映像，該映像將由您剛啟動的工作流程執行所部署。
1. 觀看部署進度：
1. 在 CodeCatalyst 主控台的導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇 `codecatalyst-eks-workflow`以檢視最新的執行。
1. 選擇 **BuildBackend** 和 **DeployToEKS** 以查看工作流程執行進度。
1. 確認您的應用程式已更新，如下所示：
1. 前往 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) 開啟 Amazon EC2 主控台。
1. 在左側底部附近，選擇**負載平衡器**。
1. 選取在 Kubernetes 部署中建立的負載平衡器。
1. 將 **DNS 名稱**值複製並貼到瀏覽器的地址列。
「教學完成！」 網頁會顯示在瀏覽器中，表示您已成功部署應用程式的新修訂版。
1. （選用） 在 中 AWS，切換到 Amazon ECR 主控台，並確認新的 Docker 映像已標記此程序步驟 7 的遞交 ID。
## 清除
您應該清除您的環境，以免不必要地向您收取本教學課程使用的儲存和運算資源的費用。
**清理方式**
1. 刪除您的叢集：
1. 在開發環境終端機中，輸入：
```
eksctl delete cluster --region=us-west-2 --name=codecatalyst-eks-cluster
```
其中：
+ *us-west-2* 已取代為您的 區域。
+ *codecatalyst-eks-cluster* 會取代為您建立的叢集名稱。
5-10 分鐘後，會刪除叢集和相關聯的資源，包括但不限於 CloudFormation 堆疊、節點群組 （在 Amazon EC2 中） 和負載平衡器。
**重要**
如果`eksctl delete cluster`命令無法運作，您可能需要重新整理登入 AWS 資料或登入`kubectl`資料。如果您不確定要重新整理哪些登入資料，請先重新整理 AWS 登入資料。若要重新整理您的 AWS 登入資料，請參閱 [如何修正「找不到登入資料」和「ExpiredToken」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-auth-errors-eks)。若要重新整理您的`kubectl`登入資料，請參閱 [如何修正「無法連線至伺服器」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-unable-connect-eks)。
1. 在 AWS 主控台中，如下所示進行清除：
1. 在 Amazon ECR 中，刪除 `codecatalyst-eks-image-repo`。
1. 在 IAM Identity Center 中，刪除：
1. `codecatalyst-eks-user`
1. `codecatalyst-eks-permission-set`
1. 在 IAM 中，刪除：
+ `codecatalyst-eks-build-role`
+ `codecatalyst-eks-deploy-role`
+ `codecatalyst-eks-build-policy`
+ `codecatalyst-eks-deploy-policy`
1. 在 CodeCatalyst 主控台中，如下所示進行清除：
1. 刪除 `codecatalyst-eks-workflow`。
1. 刪除 `codecatalyst-eks-environment`。
1. 刪除 `codecatalyst-eks-source-repository`。
1. 刪除您的開發環境。
1. 刪除 `codecatalyst-eks-project`。
在本教學課程中，您已了解如何使用 CodeCatalyst 工作流程和部署至 **Kubernetes 叢集動作，將應用程式部署至 Amazon EKS **服務。
# 將 'Deploy 新增至 Kubernetes 叢集' 動作
使用下列指示將**部署至 Kubernetes 叢集**動作新增至您的工作流程。
**開始之前**
將**部署至 Kubernetes 叢集**動作新增至工作流程之前，您必須備妥下列項目：
**提示**
若要快速設定這些先決條件，請遵循 中的指示[教學課程：將應用程式部署至 Amazon EKS](deploy-tut-eks.md)。
+ Amazon EKS 中的 Kubernetes 叢集。如需叢集的相關資訊，請參閱《[Amazon EKS 使用者指南》中的 Amazon EKS 叢集](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html)。 ****
+ 至少一個 Dockerfile，說明如何將應用程式組合成 Docker 映像。如需 Dockerfiles 的詳細資訊，請參閱 [Dockerfile 參考](https://docs.docker.com/engine/reference/builder/)。
+ 至少一個 Kubernetes 資訊清單檔案，在 Kubernetes 文件中稱為*組態檔案*或*組態*。如需詳細資訊，請參閱 Kubernetes 文件中的[管理資源](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/)。
+ IAM 角色，可讓**部署至 Kubernetes 叢集**動作存取您的 Amazon EKS 叢集並與之互動。如需詳細資訊，請參閱 [「部署到 Kubernetes 叢集」動作 YAML](deploy-action-ref-eks.md) 中的「[Role](deploy-action-ref-eks.md#deploy.action.eks.environment.connections.role)」主題。
建立此角色之後，您必須將其新增至：
+ 您的 Kubernetes ConfigMap 檔案。若要了解如何將角色新增至 ConfigMap 檔案，請參閱《**Amazon EKS 使用者指南*》中的*[啟用叢集的 IAM 主體存取權](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html)。
+ CodeCatalyst。若要了解如何將 IAM 角色新增至 CodeCatalyst，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
+ CodeCatalyst 空間、專案和環境。空間和環境都必須連線到您要部署應用程式的 AWS 帳戶。如需詳細資訊，請參閱[建立空間](spaces-create.md)、[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)及[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
+ CodeCatalyst 支援的來源儲存庫。儲存庫會存放您的應用程式來源檔案、Dockerfiles 和 Kubernetes 資訊清單。如需詳細資訊，請參閱[將程式碼與 CodeCatalyst 中的來源儲存庫一起存放和協作儲存程式碼並與來源儲存庫協作](source.md)。
------
#### [ Visual ]
**使用視覺化編輯器將 'Deploy 新增至 Kubernetes 叢集' 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署至 Kubernetes 叢集**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署到 Kubernetes 叢集**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「部署到 Kubernetes 叢集」動作 YAML](deploy-action-ref-eks.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器將 'Deploy 新增至 Kubernetes 叢集' 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署到 Kubernetes 叢集**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署到 Kubernetes 叢集**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「部署到 Kubernetes 叢集」動作 YAML](deploy-action-ref-eks.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 「部署到 Kubernetes 叢集」變數
**部署至 Kubernetes 叢集**動作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| 叢集 | 在工作流程執行期間部署至 之 Amazon EKS 叢集 的 Amazon.com Resource Name (ARN)。 範例：`arn:aws:eks:us-west-2:111122223333:cluster/codecatalyst-eks-cluster` |
| deployment-platform | 部署平台的名稱。 硬式編碼為 `AWS:EKS`。 |
| 中繼資料 | 預訂. 在工作流程執行期間所部署叢集的相關 JSON 格式中繼資料。 |
| 命名空間 | 部署叢集的 Kubernetes 命名空間。 範例：`default` |
| resources | 預訂. 與工作流程執行期間部署的資源相關的 JSON 格式中繼資料。 |
| 伺服器 | 您可以使用 等管理工具與叢集通訊的 API 伺服器端點名稱`kubectl`。 如需 API 服務端點的詳細資訊，請參閱《[Amazon EKS 使用者指南》中的 Amazon EKS 叢集端點存取控制](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html)。 **** 範例：`https://random-string.gr7.us-west-2.eks.amazonaws.com` |
# 「部署到 Kubernetes 叢集」動作 YAML
以下是**部署至 Kubernetes 叢集動作的 YAML **定義。若要了解如何使用此動作，請參閱 [使用工作流程部署至 Amazon EKS](deploy-action-eks.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素會與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
DeployToKubernetesCluster\$1nn:
Identifier: aws/kubernetes-deploy@v1
DependsOn:
- build-action
Compute:
- Type: EC2 | Lambda
- Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: DeployToEKS
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- manifest-artifact
Configuration:
Namespace: namespace
Region: us-east-1
Cluster: eks-cluster
Manifests: manifest-path
```
## DeployToKubernetesCluster
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在動作名稱中啟用特殊字元和空格。
預設：`DeployToKubernetesCluster_nn`。
對應的 UI：組態索引標籤/**動作顯示名稱**
## Identifier
(*DeployToKubernetesCluster*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/kubernetes-deploy@v1`。
對應的 UI：工作流程圖表/DeployToKubernetesCluster\$1nn/**aws/kubernetes-deploy@v1** 標籤
## DependsOn
(*DeployToKubernetesCluster*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*DeployToKubernetesCluster*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*DeployToKubernetesCluster*/Compute/**Type**)
（如果[Compute](#deploy.action.eks.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/進階 - 選用/**運算類型**
## Fleet
(*DeployToKubernetesCluster*/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`。
對應的 UI：組態索引標籤/進階 - 選用/**運算機群**
## Timeout
(*DeployToKubernetesCluster*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Environment
(*DeployToKubernetesCluster*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將 動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*DeployToKubernetesCluster*/Environment/**Name**)
（如果[Environment](#deploy.action.eks.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*DeployToKubernetesCluster*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*DeployToKubernetesCluster*/Environment/Connections/**Name**)
(選用)
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*DeployToKubernetesCluster*/Environment/Connections/**Role**)
（如果[Connections](#deploy.action.eks.environment.connections)包含 則為必要）
指定**部署至 Kubernetes 叢集動作用來存取的 IAM **角色名稱 AWS。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"eks:DescribeCluster",
"eks:ListClusters"
],
"Resource": "*"
}
]
}
```
------
**注意**
第一次使用角色時，請在資源政策陳述式中使用下列萬用字元，然後在可用的資源名稱縮小政策範圍。
```
"Resource": "*"
```
+ 下列自訂信任政策：
請確定此角色已新增至：
+ 您的帳戶連線。若要進一步了解如何將 IAM 角色新增至帳戶連線，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
+ 您的 Kubernetes ConfigMap。若要進一步了解如何將 IAM 角色新增至 ConfigMap，請參閱 `eksctl` 文件中的[管理 IAM 使用者和角色](https://eksctl.io/usage/iam-identity-mappings/)。
**提示**
另請參閱 [教學課程：將應用程式部署至 Amazon EKS](deploy-tut-eks.md) ，以取得將 am IAM 角色新增至帳戶連線和 ConfigMap 的指示。
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Inputs
(*DeployToKubernetesCluster*/**Inputs**)
（如果[Connections](#deploy.action.eks.environment.connections)包含 則為必要）
`Inputs` 區段定義工作流程執行期間 `DeployToKubernetesCluster`所需的資料。
**注意**
每個**部署到 Amazon EKS **動作只允許一個輸入 （來源或成品）。
對應的 UI：**輸入**索引標籤
## Sources
(*DeployToKubernetesCluster*/Inputs/**Sources**)
（如果您的資訊清單檔案存放在來源儲存庫中，則為必要項目）
如果您的 Kubernetes 資訊清單檔案存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的資訊清單檔案不包含在來源儲存庫中，它們必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*DeployToKubernetesCluster*/Inputs/**Artifacts**)
（如果您的資訊清單檔案存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要）
如果 Kubernetes 資訊清單檔案或檔案包含在先前動作產生的成品中，請在此處指定該成品。如果您的資訊清單檔案不包含在成品中，則必須位於來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**成品 - 選用**
## Configuration
(*DeployToKubernetesCluster*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## Namespace
(*DeployToKubernetesCluster*/Configuration/**Namespace**)
(選用)
指定要部署 Kubernetes 應用程式的 Kubernetes 命名空間。`default` 如果您未搭配叢集使用命名空間，請使用 。如需命名空間的詳細資訊，請參閱 [Kubernetes 文件中的使用 Kubernetes 命名空間細分叢集](https://kubernetes.io/docs/tasks/administer-cluster/namespaces/#subdividing-your-cluster-using-kubernetes-namespaces)。
如果您省略命名空間，`default`則會使用 的值。
對應的 UI：組態索引標籤/**命名空間**
## Region
(*DeployToKubernetesCluster*/Configuration/**Region**)
(必要)
指定 Amazon EKS 叢集和服務所在的 AWS 區域。如需區域代碼清單，請參閱《》中的[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)*AWS 一般參考*。
對應的 UI：組態索引標籤/**區域**
## Cluster
(*DeployToKubernetesCluster*/Configuration/**Cluster**)
(必要)
指定現有 Amazon EKS 叢集的名稱。**部署至 Kubernetes 叢集**動作會將您的容器化應用程式部署至此叢集。如需 Amazon EKS 叢集的詳細資訊，請參閱《**Amazon EKS 使用者指南**》中的[叢集](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html)。
對應的 UI：組態索引標籤/**叢集**
## Manifests
(*DeployToKubernetesCluster*/Configuration/**Manifests**)
(必要)
在 Kubernetes 文件中指定 YAML 格式 Kubernetes 資訊清單檔案的路徑 （稱為*組態檔案*、*組態檔案*或簡稱*組態*)。
如果您使用的是多個資訊清單檔案，請將它們放在單一資料夾中，並參考該資料夾。資訊清單檔案是由 Kubernetes 以英數方式處理，因此請務必在檔案名稱前面加上數字或字母，以控制處理順序。例如：
`00-namespace.yaml`
`01-deployment.yaml`
如果您的資訊清單檔案位於來源儲存庫中，則路徑會與來源儲存庫根資料夾相對。如果檔案位於先前工作流程動作的成品中，則路徑會與成品根資料夾相對。
範例：
`Manifests/`
`deployment.yaml`
`my-deployment.yml`
請勿使用萬用字元 (`*`)。
**注意**
不支援 [Helm Chart](https://helm.sh/docs/topics/charts/) 和 [kustomization 檔案](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/)。
如需資訊清單檔案的詳細資訊，請參閱 Kubernetes 文件中的[組織資源組態](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#organizing-resource-configurations)。
對應的 UI：組態索引標籤/**資訊清單**
# 部署 CloudFormation 堆疊
本節說明如何使用 CodeCatalyst 工作流程部署 AWS CloudFormation 堆疊。若要達成此目的，您必須將**部署 CloudFormation 堆疊**動作新增至工作流程。動作 AWS 會根據您提供的範本，將資源的 CloudFormation 堆疊部署至 。範本可以是：
+ CloudFormation 範本 – 如需詳細資訊，請參閱[使用 CloudFormation 範本](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)。
+ AWS SAM 範本 – 如需詳細資訊，請參閱 [AWS Serverless Application Model (AWS SAM) 規格](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html)。
**注意**
若要使用 AWS SAM 範本，您必須先使用 `[sam package](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html)`操作封裝 AWS SAM 應用程式。如需示範如何在 Amazon CodeCatalyst 工作流程中自動執行此封裝的教學課程，請參閱 [教學課程：部署無伺服器應用程式](deploy-tut-lambda.md)。
如果堆疊已存在，動作會執行 CloudFormation `[CreateChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateChangeSet.html)`操作，然後執行 `[ExecuteChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_ExecuteChangeSet.html)`操作。動作接著會等待變更部署，並根據結果將本身標記為失敗。
如果您已經有包含要部署之資源的 CloudFormation 或 AWS SAM 範本，或者您計劃使用 AWS SAM 和 等工具，在工作流程建置動作中自動產生資源，請使用**部署 CloudFormation 堆疊**動作[AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html)。 [新增建置動作](build-add-action.md)
您可以在 CloudFormation 中編寫的範本，或 AWS SAM 可與**部署 CloudFormation 堆疊**動作搭配使用的範本，都沒有任何限制。
**提示**
如需說明如何使用部署** CloudFormation 堆疊動作部署**無伺服器應用程式的教學課程，請參閱 [教學課程：部署無伺服器應用程式](deploy-tut-lambda.md)。
**Topics**
+ [「部署 CloudFormation 堆疊」動作所使用的執行期映像](#deploy-action-cfn-runtime)
+ [教學課程：部署無伺服器應用程式](deploy-tut-lambda.md)
+ [新增「部署 CloudFormation 堆疊」動作](deploy-action-cfn-adding.md)
+ [設定轉返](deploy-consumption-enable-alarms.md)
+ [「部署 CloudFormation 堆疊」變數](deploy-action-cfn-variables.md)
+ [「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)
## 「部署 CloudFormation 堆疊」動作所使用的執行期映像
**部署 CloudFormation 堆疊**動作會在 [2022 年 11 月的映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 教學課程：部署無伺服器應用程式
在本教學課程中，您將了解如何使用工作流程建置、測試和部署無伺服器應用程式做為 CloudFormation 堆疊。
本教學課程中的應用程式是一個簡單的 Web 應用程式，會輸出 'Hello World' 訊息。它包含 AWS Lambda 函數和 Amazon API Gateway，您可以使用 [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html) 建置它，這是 的延伸[CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。
**Topics**
+ [先決條件](#deploy-tut-lambda-cfn-prereqs)
+ [步驟 1：建立來源儲存庫](#deploy-tut-lambda-cfn-source)
+ [步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)
+ [步驟 3：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-lambda-cfn-roles-add)
+ [步驟 4：建立 Amazon S3 儲存貯體](#deploy-tut-lambda-cfn-s3)
+ [步驟 5：新增來源檔案](#deploy-tut-lambda-cfn-files)
+ [步驟 6：建立和執行工作流程](#deploy-tut-lambda-cfn-workflow)
+ [步驟 7：進行變更](#deploy-tut-lambda-cfn-change)
+ [清除](#deploy-tut-lambda-cfn-clean-up)
## 先決條件
開始之前：
+ 您需要具有連線 AWS 帳戶的 CodeCatalyst **空間**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在您的空間中，您需要一個名為 的空專案：
```
codecatalyst-cfn-project
```
使用**從頭開始**選項來建立此專案。
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
+ 在專案中，您需要名為 的 CodeCatalyst **環境**：
```
codecatalyst-cfn-environment
```
設定此環境，如下所示：
+ 選擇任何類型的，例如**非生產**。
+ 將您的帳戶連接到該 AWS 帳戶。
+ 針對**預設 IAM 角色**，選擇任何角色。稍後您將指定不同的角色。
如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
## 步驟 1：建立來源儲存庫
在此步驟中，您會在 CodeCatalyst 中建立來源儲存庫。此儲存庫用於存放教學課程的來源檔案，例如 Lambda 函數檔案。
如需來源儲存庫的詳細資訊，請參閱 [建立來源儲存庫](source-repositories-create.md)。
**建立來源儲存庫**
1. 在 CodeCatalyst 的導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇**新增儲存庫**，然後選擇**建立儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
codecatalyst-cfn-source-repository
```
1. 選擇**建立**。
您現在已建立名為 的儲存庫`codecatalyst-cfn-source-repository`。
## 步驟 2：建立 AWS 角色
在此步驟中，您會建立下列 AWS IAM 角色：
+ **部署角色** – 授予 CodeCatalyst **部署 CloudFormation 堆疊**動作許可，以存取您將部署無伺服器應用程式的 AWS 帳戶和 CloudFormation 服務。**部署 CloudFormation 堆疊**動作是工作流程的一部分。
+ **組建角色** – 授予 CodeCatalyst 組建動作許可，以存取 AWS 您的帳戶並寫入 Amazon S3，其中將存放無伺服器應用程式套件。建置動作是工作流程的一部分。
+ **堆疊角色** – 授予 CloudFormation 許可，以讀取和修改稍後將提供之 AWS SAM 範本中指定的資源。同時授予 CloudWatch 許可。
如需 IAM 角色的詳細資訊，請參閱*AWS Identity and Access Management 《 使用者指南*》中的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
**注意**
若要節省時間，您可以建立稱為角色的單一`CodeCatalystWorkflowDevelopmentRole-spaceName`角色，而不是先前列出的三個角色。如需詳細資訊，請參閱[為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有非常廣泛的許可，可能會帶來安全風險。我們建議您只在安全性較少的教學課程和案例中使用此角色。本教學假設您正在建立先前列出的三個角色。
**注意**
[Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)也是必要的，但您不需要立即建立，因為`sam-template.yml`檔案會在步驟 5 中執行工作流程時為您建立。
**建立部署角色**
1. 建立角色的政策，如下所示：
1. 登入 AWS。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇**政策**。
1. 選擇 **Create policy** (建立政策)。
1. 請選擇 **JSON** 標籤。
1. 刪除現有的程式碼。
1. 貼上以下程式碼：
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用後縮小政策的範圍。
```
"Resource": "*"
```
1. 選擇下**一步：標籤**。
1. 選擇下**一步：檢閱**。
1. 在**名稱**中，輸入：
```
codecatalyst-deploy-policy
```
1. 選擇**建立政策**。
您現在已建立許可政策。
1. 建立部署角色，如下所示：
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 選擇**自訂信任政策**。
1. 刪除現有的自訂信任政策。
1. 新增下列自訂信任政策：
1. 選擇**下一步**。
1. 在**許可政策**中，搜尋`codecatalyst-deploy-policy`並選取其核取方塊。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-deploy-role
```
1. 針對**角色描述**，輸入：
```
CodeCatalyst deploy role
```
1. 選擇建**立角色**。
您現在已建立具有信任政策和許可政策的部署角色。
1. 取得部署角色 ARN，如下所示：
1. 在導覽窗格中，選擇**角色**。
1. 在搜尋方塊中，輸入您剛建立的角色名稱 (`codecatalyst-deploy-role`)。
1. 從清單中選擇角色。
角色的**摘要**頁面隨即出現。
1. 在頂端複製 **ARN** 值。
您現在已建立具有適當許可的部署角色，並取得其 ARN。
**建立建置角色**
1. 建立角色的政策，如下所示：
1. 登入 AWS。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇**政策**。
1. 選擇 **Create policy** (建立政策)。
1. 請選擇 **JSON** 標籤。
1. 刪除現有的程式碼。
1. 貼上以下程式碼：
**注意**
第一次使用該角色執行工作流程動作時，請在資源政策陳述式中使用萬用字元，然後在資源名稱可用後縮小政策的範圍。
```
"Resource": "*"
```
1. 選擇下**一步：標籤**。
1. 選擇下**一步：檢閱**。
1. 在**名稱**中，輸入：
```
codecatalyst-build-policy
```
1. 選擇**建立政策**。
您現在已建立許可政策。
1. 建立建置角色，如下所示：
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 選擇**自訂信任政策**。
1. 刪除現有的自訂信任政策。
1. 新增下列自訂信任政策：
1. 選擇**下一步**。
1. 在**許可政策**中，搜尋`codecatalyst-build-policy`並選取其核取方塊。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-build-role
```
1. 針對**角色描述**，輸入：
```
CodeCatalyst build role
```
1. 選擇建**立角色**。
您現在已建立具有信任政策和許可政策的建置角色。
1. 取得建置角色 ARN，如下所示：
1. 在導覽窗格中，選擇**角色**。
1. 在搜尋方塊中，輸入您剛建立的角色名稱 (`codecatalyst-build-role`)。
1. 從清單中選擇角色。
角色的**摘要**頁面隨即出現。
1. 在頂端複製 **ARN** 值。
您現在已建立具有適當許可的建置角色，並取得其 ARN。
**建立堆疊角色**
1. AWS 使用您要部署堆疊的帳戶登入 。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 建立堆疊角色，如下所示：
1. 在導覽窗格中，選擇 **Roles** (角色)。
1. 選擇 **Create Role** (建立角色)。
1. 選擇 **AWS 服務**。
1. 在**使用案例**區段中，從下拉式清單中選擇 **CloudFormation**。
1. 選取 **CloudFormation** 選項按鈕。
1. 在底部，選擇**下一步**。
1. 使用搜尋方塊，尋找下列許可政策，然後選取其各自的核取方塊。
**注意**
如果您搜尋政策但未顯示，請務必選擇**清除篩選條件**，然後再試一次。
+ **CloudWatchFullAccess**
+ **AWS CloudFormationFullAccess**
+ **IAMFullAccess**
+ **AWS Lambda\$1FullAccess**
+ **AmazonAPIGatewayAdministrator**
+ **AmazonS3FullAccess**
+ **AmazonEC2ContainerRegistryFullAccess**
第一個政策允許存取 CloudWatch，以便在警示發生時啟用堆疊轉返。
其餘政策允許 AWS SAM 存取本教學課程中將部署的堆疊中的服務和資源。如需詳細資訊，請參閱《 *AWS Serverless Application Model 開發人員指南*》中的[許可](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-permissions.html)。
1. 選擇**下一步**。
1. 針對**角色名稱**，輸入：
```
codecatalyst-stack-role
```
1. 選擇建**立角色**。
1. 取得堆疊角色的 ARN，如下所示：
1. 在導覽窗格中，選擇**角色**。
1. 在搜尋方塊中，輸入您剛建立的角色名稱 (`codecatalyst-stack-role`)。
1. 從清單中選擇角色。
1. 在**摘要**區段中，複製 **ARN** 值。供稍後使用。
您現在已建立具有適當許可的堆疊角色，並且已取得其 ARN。
## 步驟 3：將 AWS 角色新增至 CodeCatalyst
在此步驟中，您將建置角色 (`codecatalyst-build-role`) 和部署角色 (`codecatalyst-deploy-role`) 新增至您空間中的 CodeCatalyst 帳戶連線。
**注意**
您不需要將堆疊角色 (`codecatalyst-stack-role`) 新增至連線。這是因為 *CloudFormation* （非 CodeCatalyst) 使用堆疊角色，在 CodeCatalyst 與 AWS 使用部署角色之間建立連線*之後*。由於 CodeCatalyst 不會使用堆疊角色來存取 AWS，因此不需要與帳戶連線建立關聯。
**將建置和部署角色新增至您的帳戶連線**
1. 在 CodeCatalyst 中，導覽至您的空間。
1. 選擇**AWS 帳戶**。帳戶連線清單隨即顯示。
1. 選擇代表您建立建置和部署角色 AWS 的帳戶的帳戶連線。
1. **從管理主控台選擇 AWS 管理角色**。
將 **IAM 角色新增至 Amazon CodeCatalyst 空間**頁面隨即出現。您可能需要登入才能存取頁面。
1. 選取**新增您在 IAM 中建立的現有角色**。
下拉式清單隨即出現。清單會顯示具有信任政策的所有 IAM 角色，其中包含 `codecatalyst-runner.amazonaws.com``codecatalyst.amazonaws.com`和服務主體。
1. 在下拉式清單中，選擇 `codecatalyst-build-role`，然後選擇**新增角色**。
1. 選擇**新增 IAM 角色**，選擇**新增您在 IAM 中建立的現有角色**，然後在下拉式清單中選擇 `codecatalyst-deploy-role`。選擇 **Add role (新增角色)**。
您現在已將建置和部署角色新增至您的空間。
1. 複製 **Amazon CodeCatalyst 顯示名稱**的值。稍後建立工作流程時，您將需要此值。
## 步驟 4：建立 Amazon S3 儲存貯體
在此步驟中，您會建立 Amazon S3 儲存貯體，存放無伺服器應用程式的部署套件 .zip 檔案。
**建立 Amazon S3 儲存貯體**
1. 開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 在主窗格中，選擇**建立儲存貯**體。
1. 針對**儲存貯體名稱**，輸入：
```
codecatalyst-cfn-s3-bucket
```
1. 對於 **AWS 區域**，選擇一個區域。本教學假設您選擇了**美國西部 （奧勒岡） us-west-2**。如需 Amazon S3 支援之區域的相關資訊，請參閱《》中的 [Amazon Simple Storage Service 端點和配額](https://docs.aws.amazon.com/general/latest/gr/s3.html)*AWS 一般參考*。
1. 在頁面底部，選擇**建立儲存貯**體。
您現在在美國西部 （奧勒岡） us-west-2 區域中建立名為 **codecatalyst-cfn-s3-bucket**的儲存貯體。
## 步驟 5：新增來源檔案
在此步驟中，您會將數個應用程式來源檔案新增至 CodeCatalyst 來源儲存庫。`hello-world` 資料夾包含您將部署的應用程式檔案。`tests` 資料夾包含單元測試。資料夾結構如下所示：
```
.
|— hello-world
| |— tests
| |— unit
| |— test-handler.js
| |— app.js
|— .npmignore
|— package.json
|— sam-template.yml
|— setup-sam.sh
```
### .npmignore 檔案
`.npmignore` 檔案指出哪些檔案和資料夾 npm 應該從應用程式套件中排除。在本教學課程中，npm 會排除 `tests` 資料夾，因為它不是應用程式的一部分。
**新增 .npmignore 檔案**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案， `codecatalyst-cfn-project`
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 從來源儲存庫清單中，選擇您的儲存庫 `codecatalyst-cfn-source-repository`。
1. 在**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
.npmignore
```
1. 在文字方塊中，輸入下列程式碼：
```
tests/*
```
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已在儲存庫的根`.npmignore`目錄中建立名為 的檔案。
### package.json 檔案
`package.json` 檔案包含有關節點專案的重要中繼資料，例如專案名稱、版本編號、描述、相依性，以及描述如何與應用程式互動和執行的其他詳細資訊。
本教學`package.json`課程中的 包含相依性和`test`指令碼的清單。測試指令碼會執行下列動作：
+ 使用 [mocha](https://mochajs.org/)，測試指令碼會執行 中指定的單元測試，`hello-world/tests/unit/`並使用 [xunit]() 報告程式將結果寫入`junit.xml`檔案。
+ 使用[伊斯坦堡 (nyc)](https://istanbul.js.org/)，測試指令碼會使用 [clover](https://openclover.org/doc/manual/4.2.0/general--about-openclover.html) 報告程式產生程式碼涵蓋範圍報告 (`clover.xml`)。如需詳細資訊，請參閱伊斯坦堡文件中[的使用替代報告程式](https://istanbul.js.org/docs/advanced/alternative-reporters/#clover)。
**新增 package.json 檔案**
1. 在儲存庫的**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
package.json
```
1. 在文字方塊中，輸入下列程式碼：
```
{
"name": "hello_world",
"version": "1.0.0",
"description": "hello world sample for NodeJS",
"main": "app.js",
"repository": "https://github.com/awslabs/aws-sam-cli/tree/develop/samcli/local/init/templates/cookiecutter-aws-sam-hello-nodejs",
"author": "SAM CLI",
"license": "MIT",
"dependencies": {
"axios": "^0.21.1",
"nyc": "^15.1.0"
},
"scripts": {
"test": "nyc --reporter=clover mocha hello-world/tests/unit/ --reporter xunit --reporter-option output=junit.xml"
},
"devDependencies": {
"aws-sdk": "^2.815.0",
"chai": "^4.2.0",
"mocha": "^8.2.1"
}
}
```
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已將名為 的檔案新增至儲存庫的`package.json`根目錄。
### sam-template.yml 檔案
`sam-template.yml` 檔案包含部署 Lambda 函數和 API Gateway 並將其一起設定的指示。它遵循[AWS Serverless Application Model 範本規格](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html)，擴展 CloudFormation 範本規格。
您在本教學課程中使用 AWS SAM 範本，而不是一般 CloudFormation 範本，因為 AWS SAM 提供實用的 [AWS：：Serverless：：Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) 資源類型。此類型會執行許多behind-the-scenes組態，您通常必須將其寫入才能使用基本 CloudFormation 語法。例如， `AWS::Serverless::Function`會建立 Lambda 函數、Lambda 執行角色，以及啟動函數的事件來源映射。如果您想要使用基本 CloudFormation 進行寫入，則必須將所有程式碼編寫。
雖然本教學課程使用預先編寫的範本，但您可以使用建置動作在工作流程中產生範本。如需詳細資訊，請參閱[部署 CloudFormation 堆疊](deploy-action-cfn.md)。
**新增 sam-template.yml 檔案**
1. 在儲存庫的**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
sam-template.yml
```
1. 在文字方塊中，輸入下列程式碼：
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
serverless-api
Sample SAM Template for serverless-api
# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Globals:
Function:
Timeout: 3
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function # For details on this resource type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
Properties:
CodeUri: hello-world/
Handler: app.lambdaHandler
Runtime: nodejs12.x
Events:
HelloWorld:
Type: Api # For details on this event source type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
Properties:
Path: /hello
Method: get
Outputs:
# ServerlessRestApi is an implicit API created out of the events key under Serverless::Function
# Find out about other implicit resources you can reference within AWS SAM at
# https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api
HelloWorldApi:
Description: "API Gateway endpoint URL for the Hello World function"
Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"
HelloWorldFunction:
Description: "Hello World Lambda function ARN"
Value: !GetAtt HelloWorldFunction.Arn
HelloWorldFunctionIamRole:
Description: "Implicit Lambda execution role created for the Hello World function"
Value: !GetAtt HelloWorldFunctionRole.Arn
```
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已在儲存庫的根資料夾`sam-template.yml`下新增名為 的檔案。
### setup-sam.sh 檔案
`setup-sam.sh` 檔案包含下載和安裝 CLI AWS SAM 公用程式的指示。工作流程會使用此公用程式來封裝`hello-world`來源。
**新增 setup-sam.sh 檔案**
1. 在儲存庫的**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
setup-sam.sh
```
1. 在文字方塊中，輸入下列程式碼：
```
#!/usr/bin/env bash
echo "Setting up sam"
yum install unzip -y
curl -LO https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
unzip -qq aws-sam-cli-linux-x86_64.zip -d sam-installation-directory
./sam-installation-directory/install; export AWS_DEFAULT_REGION=us-west-2
```
在上述程式碼中，將 AWS *us-west-2* 取代為您的 區域。
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已將名為 的檔案新增至儲存庫的`setup-sam.sh`根目錄。
### app.js 檔案
`app.js` 包含 Lambda 函數程式碼。在本教學課程中，程式碼會傳回文字 `hello world`。
**新增 app.js 檔案**
1. 在儲存庫的**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
hello-world/app.js
```
1. 在文字方塊中，輸入下列程式碼：
```
// const axios = require('axios')
// const url = 'http://checkip.amazonaws.com/';
let response;
/**
*
* Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
* @param {Object} event - API Gateway Lambda Proxy Input Format
*
* Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html
* @param {Object} context
*
* Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
* @returns {Object} object - API Gateway Lambda Proxy Output Format
*
*/
exports.lambdaHandler = async (event, context) => {
try {
// const ret = await axios(url);
response = {
'statusCode': 200,
'body': JSON.stringify({
message: 'hello world',
// location: ret.data.trim()
})
}
} catch (err) {
console.log(err);
return err;
}
return response
};
```
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已建立名為 的資料夾`hello-world`和名為 的檔案`app.js`。
### test-handler.js 檔案
`test-handler.js` 檔案包含 Lambda 函數的單位測試。
**新增 test-handler.js 檔案**
1. 在儲存庫的**檔案中**，選擇**建立檔案**。
1. 針對**檔案名稱**，輸入：
```
hello-world/tests/unit/test-handler.js
```
1. 在文字方塊中，輸入下列程式碼：
```
'use strict';
const app = require('../../app.js');
const chai = require('chai');
const expect = chai.expect;
var event, context;
describe('Tests index', function () {
it('verifies successful response', async () => {
const result = await app.lambdaHandler(event, context)
expect(result).to.be.an('object');
expect(result.statusCode).to.equal(200);
expect(result.body).to.be.an('string');
let response = JSON.parse(result.body);
expect(response).to.be.an('object');
expect(response.message).to.be.equal("hello world");
// expect(response.location).to.be.an("string");
});
});
```
1. 選擇**遞交**，然後再次選擇**遞交**。
您現在已在 `hello-world/tests/unit` 資料夾`test-handler.js`下新增名為 的檔案。
您現在已新增所有來源檔案。
花一點時間仔細檢查您的工作，並確保將所有檔案放在正確的資料夾中。資料夾結構如下所示：
```
.
|— hello-world
| |— tests
| |— unit
| |— test-handler.js
| |— app.js
|— .npmignore
|— README.md
|— package.json
|— sam-template.yml
|— setup-sam.sh
```
## 步驟 6：建立和執行工作流程
在此步驟中，您建立的工作流程會封裝您的 Lambda 原始程式碼並進行部署。工作流程包含下列依順序執行的建置區塊：
+ 觸發條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ 測試動作 (`Test`) – 在觸發時，此動作會安裝 [Node 套件管理員 (npm)](https://www.npmjs.com/)，然後執行 `npm run test`命令。此命令會告知 npm 執行 `package.json` 檔案中定義的`test`指令碼。`test` 指令碼接著會執行單元測試，並產生兩個報告：測試報告 (`junit.xml`) 和程式碼涵蓋報告 (`clover.xml`)。如需詳細資訊，請參閱[package.json 檔案](#deploy-tut-lambda-cfn-files-package-json)。
接下來，測試動作會將 XML 報告轉換為 CodeCatalyst 報告，並在測試動作**的報告**索引標籤下顯示在 CodeCatalyst 主控台中。
如需測試動作的詳細資訊，請參閱 [使用工作流程進行測試使用工作流程進行測試](test-workflow-actions.md)。
+ 建置動作 (`BuildBackend`) – 測試動作完成後，建置動作會下載並安裝 AWS SAM CLI、封裝`hello-world`來源，並將套件複製到 Amazon S3 儲存貯體，Lambda 服務預期會是該儲存貯體。動作也會輸出名為 的新 AWS SAM 範本檔案，`sam-template-packaged.yml`並將其置於名為 的輸出成品中`buildArtifact`。
如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ 部署動作 (`DeployCloudFormationStack`) – 完成建置動作後，部署動作會尋找建置動作 (`buildArtifact`) 產生的輸出成品，在其中尋找 AWS SAM 範本，然後執行範本。 AWS SAM 範本會建立可部署無伺服器應用程式的堆疊。
**建立工作流程**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 針對**來源儲存庫**，選擇 `codecatalyst-cfn-source-repository`。
1. 針對**分支**，選擇 `main`。
1. 選擇**建立**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML 程式碼：
**注意**
在下列 YAML 程式碼中，您可以視需要省略這些`Connections:`區段。如果您省略這些區段，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含 中所述兩個角色的許可和信任政策[步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
```
Name: codecatalyst-cfn-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
Test:
Identifier: aws/managed-test@v1
Inputs:
Sources:
- WorkflowSource
Outputs:
Reports:
CoverageReport:
Format: CLOVERXML
IncludePaths:
- "coverage/*"
TestReport:
Format: JUNITXML
IncludePaths:
- junit.xml
Configuration:
Steps:
- Run: npm install
- Run: npm run test
BuildBackend:
Identifier: aws/build@v1
DependsOn:
- Test
Environment:
Name: codecatalyst-cfn-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-build-role
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: . ./setup-sam.sh
- Run: sam package --template-file sam-template.yml --s3-bucket codecatalyst-cfn-s3-bucket --output-template-file sam-template-packaged.yml --region us-west-2
Outputs:
Artifacts:
- Name: buildArtifact
Files:
- "**/*"
DeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
DependsOn:
- BuildBackend
Environment:
Name: codecatalyst-cfn-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-deploy-role
Inputs:
Artifacts:
- buildArtifact
Sources: []
Configuration:
name: codecatalyst-cfn-stack
region: us-west-2
role-arn: arn:aws:iam::111122223333:role/StackRole
template: ./sam-template-packaged.yml
capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
```
在上述程式碼中，取代：
+ 兩個具有您環境名稱的 *codecatalyst-cfn-environment* 執行個體。
+ 這兩個 *codecatalyst-account-connection* 執行個體都具有您帳戶連線的顯示名稱。顯示名稱可能是數字。如需詳細資訊，請參閱[步驟 3：將 AWS 角色新增至 CodeCatalyst](#deploy-tut-lambda-cfn-roles-add)。
+ *codecatalyst-build-role* 使用您在 中建立的建置角色名稱[步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)。
+ *codecatalyst-cfn-s3-bucket*，內含您在 中建立的 Amazon S3 儲存貯體名稱[步驟 4：建立 Amazon S3 儲存貯體](#deploy-tut-lambda-cfn-s3)。
+ Amazon S3 儲存貯體所在的區域 （第一個執行個體） 和堆疊將部署的區域 （第二個執行個體） 為 *us-west-2* 的兩個執行個體。這些區域可能不同。本教學假設兩個區域都設為 `us-west-2`。如需 Amazon S3 和 支援區域的詳細資訊 CloudFormation，請參閱《》中的[服務端點和配額](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)*AWS 一般參考*。
+ *codecatalyst-deploy-role* 使用您在 中建立的部署角色名稱[步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)。
+ *codecatalyst-cfn-environment*，其中包含您在 中建立的環境名稱[先決條件](#deploy-tut-lambda-cfn-prereqs)。
+ *arn：aws：iam：：111122223333：role/StackRole*，其中包含您在 中建立之堆疊角色的 Amazon Resource Name (ARN)[步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)。
**注意**
如果您決定不建立建置、部署和堆疊角色，請將 *codecatalyst-build-role*、 *codecatalyst-deploy-role*和 *arn：aws：iam：：111122223333：role/StackRole* 取代為`CodeCatalystWorkflowDevelopmentRole-spaceName`角色的名稱或 ARN。如需有關此角色的詳細資訊，請參閱 [步驟 2：建立 AWS 角色](#deploy-tut-lambda-cfn-roles)。
如需先前所示程式碼中屬性的相關資訊，請參閱 [「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇 **Commit** (遞交)。
1. 在**遞交工作流程**對話方塊中，輸入下列內容：
1. 對於**工作流程檔案名稱**，請保留預設值 `codecatalyst-cfn-workflow`。
1. 針對**遞交訊息**，輸入：
```
add initial workflow file
```
1. 針對**儲存庫**，選擇 **codecatalyst-cfn-source-repository**。
1. 針對**分支名稱**，選擇**主要**。
1. 選擇 **Commit** (遞交)。
您現在已建立工作流程。由於工作流程頂端定義的觸發條件，工作流程執行會自動啟動。具體而言，當您將`codecatalyst-cfn-workflow.yaml`檔案遞交 （並推送） 到您的來源儲存庫時，觸發會啟動工作流程執行。
**檢視進行中工作流程執行**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇您剛建立的工作流程：`codecatalyst-cfn-workflow`。
1. 選擇**執行**索引標籤。
1. 在**執行 ID** 欄中，選擇執行 ID。
1. 選擇**測試**以查看測試進度。
1. 選擇 **BuildBackend** 以查看建置進度。
1. 選擇 **DeployCloudFormationStack** 以查看部署進度。
如需檢視執行詳細資訊的詳細資訊，請參閱 [檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
1. 當 **DeployCloudFormationStack** 動作完成時，請執行下列動作：
+ 如果工作流程執行成功，請前往下一個程序。
+ 如果工作流程在**測試**或 **BuildBackend** 動作上執行失敗，請選擇**日誌**來疑難排解問題。
+ 如果在 **DeployCloudFormationStack** 動作上執行工作流程失敗，請選擇部署動作，然後選擇**摘要**索引標籤。捲動至 **CloudFormation 事件**區段以檢視詳細的錯誤訊息。如果發生轉返，請在重新執行工作流程之前，透過 中的 AWS CloudFormation 主控台刪除`codecatalyst-cfn-stack`堆疊。
**驗證部署**
1. 成功部署後，從頂端附近的水平選單列中選擇**變數 (7)**。（請勿在右側窗格中選擇**變數**。)
1. 在 **HelloWorldApi** 旁邊，將 `https://` URL 貼到瀏覽器。
隨即顯示來自 Lambda 函數的 **hello world** JSON 訊息，指出工作流程已成功部署和設定 Lambda 函數和 API Gateway。
**提示**
您可以使用幾個小型組態，讓 CodeCatalyst 在工作流程圖表中顯示此 URL。如需詳細資訊，請參閱[在工作流程圖表中顯示應用程式 URL](deploy-app-url.md)。
**驗證單位測試結果和程式碼涵蓋範圍**
1. 在工作流程圖表中，選擇**測試**，然後選擇**報告**。
1. 選擇 **TestReport** 以檢視單位測試結果，或選擇 **CoverageReport** 以檢視測試中檔案的程式碼涵蓋範圍詳細資訊，在此情況下為 `app.js`和 `test-handler.js`。
**驗證已部署的資源**
1. 登入 AWS 管理主控台 並開啟 API Gateway 主控台，網址為 https：//[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。
1. 觀察 AWS SAM 範本建立的 **codecatalyst-cfn-stack** API。API 名稱來自工作流程定義檔案 () 中的 `Configuration/name`值`codecatalyst-cfn-workflow.yaml`。
1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。
1. 在導覽視窗中，選擇**函數**。
1. 選擇您的 Lambda 函數 `codecatalyst-cfn-stack-HelloWorldFunction-string`。
1. 您可以查看 API Gateway 如何觸發函數。此整合是由 資源類型自動設定 AWS SAM `AWS::Serverless::Function`。
## 步驟 7：進行變更
在此步驟中，您會變更並遞交 Lambda 原始程式碼。此遞交會啟動新的工作流程執行。此執行會使用 Lambda 主控台中指定的預設流量轉移組態，在藍綠配置中部署新的 Lambda 函數。
**變更您的 Lambda 來源**
1. 在 CodeCatalyst 中，導覽至您的專案。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇您的來源儲存庫 `codecatalyst-cfn-source-repository`。
1. 變更應用程式檔案：
1. 選擇 `hello-world` 資料夾。
1. 選擇 `app.js` 檔案。
1. 選擇**編輯**。
1. 在第 23 行，`hello world`變更為 **Tutorial complete\$1**。
1. 選擇**遞交**，然後再次選擇**遞交**。
遞交會導致工作流程執行開始。此執行將會失敗，因為您尚未更新單元測試以反映名稱變更。
1. 更新單元測試：
1. 選擇 `hello-world\tests\unit\test-handler.js`。
1. 選擇**編輯**。
1. 在第 19 行，`hello world`變更為 **Tutorial complete\$1**。
1. 選擇**遞交**，然後再次選擇**遞交**。
遞交會導致另一個工作流程執行開始。此執行將會成功。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇 `codecatalyst-cfn-workflow`，然後選擇**執行**。
1. 選擇最新執行的執行 ID。它應該仍在進行中。
1. 選擇**測試**、 **BuildBackend** 和 **DeployCloudFormationStack** 以查看工作流程執行進度。
1. 當工作流程完成時，請選擇頂端附近的**變數 (7)**。
1. 在 **HelloWorldApi** 旁邊，將 `https://` URL 貼到瀏覽器中。
瀏覽器中會出現一`Tutorial complete!`則訊息，指出您的新應用程式已成功部署。
## 清除
清除本教學課程中使用的檔案和服務，以避免收取這些檔案和服務的費用。
**在 CodeCatalyst 主控台中清除**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 刪除 `codecatalyst-cfn-workflow`。
1. 刪除 `codecatalyst-cfn-environment`。
1. 刪除 `codecatalyst-cfn-source-repository`。
1. 刪除 `codecatalyst-cfn-project`。
**在 中清除 AWS 管理主控台**
1. 在 CloudFormation 中清除，如下所示：
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
1. 刪除`codecatalyst-cfn-stack`。
刪除堆疊會從 API Gateway 和 Lambda 服務中移除所有教學課程資源。
1. 在 Amazon S3 中清除，如下所示：
1. 開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 選擇 `codecatalyst-cfn-s3-bucket`。
1. 刪除儲存貯體內容。
1. 刪除儲存貯體。
1. 在 IAM 中清除，如下所示：
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 刪除`codecatalyst-deploy-policy`。
1. 刪除`codecatalyst-build-policy`。
1. 刪除`codecatalyst-stack-policy`。
1. 刪除`codecatalyst-deploy-role`。
1. 刪除`codecatalyst-build-role`。
1. 刪除`codecatalyst-stack-role`。
在本教學課程中，您已了解如何使用 CodeCatalyst 工作流程和部署堆疊動作，將無伺服器應用程式部署為 CloudFormation ** CloudFormation 堆疊**。
# 新增「部署 CloudFormation 堆疊」動作
使用下列指示將**部署 CloudFormation 堆疊**動作新增至您的工作流程。
------
#### [ Visual ]
**使用視覺化編輯器新增「部署 CloudFormation 堆疊」動作**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署 CloudFormation 堆疊**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署 CloudFormation 堆疊**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增「部署 CloudFormation 堆疊」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**部署 CloudFormation 堆疊**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**部署 CloudFormation 堆疊**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中會提供每個可用屬性的說明[「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 設定轉返
根據預設，如果**部署 CloudFormation 堆疊**動作失敗，將導致 將堆疊 CloudFormation 復原至最後已知的穩定狀態。您可以變更行為，讓回復不僅發生在動作失敗時，也發生在指定的 Amazon CloudWatch 警示發生時。如需有關 CloudWatch 警示的詳細資訊，請參閱 *Amazon CloudWatch 使用者指南*中的[使用 Amazon CloudWatch 警示](https://docs.aws.amazon.com/)。
您也可以變更預設行為，讓 CloudFormation 在動作失敗時不會轉返堆疊。
請使用下列指示來設定轉返。
**注意**
您無法手動啟動轉返。
------
#### [ Visual ]
**開始之前**
1. 請確定您的[工作流程](workflow.md)包含正常運作的**部署 CloudFormation 堆疊**動作。如需詳細資訊，請參閱[部署 CloudFormation 堆疊](deploy-action-cfn.md)。
1. 在**部署堆疊 CloudFormation **動作的堆疊**角色 - 選用**欄位中指定的角色中，請務必包含 **CloudWatchFullAccess** 許可。如需使用適當許可建立此角色的資訊，請參閱 [步驟 2：建立 AWS 角色](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles)。
**設定「部署 CloudFormation 堆疊」動作的轉返警示**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**部署 CloudFormation 堆疊**動作。
1. 在詳細資訊窗格中，選擇**組態**。
1. 在底部，展開**進階**。
1. 在**監控警示 ARNs**下，選擇**新增警示**。
1. 在下列欄位中輸入資訊。
+ **警示 ARN**
指定 Amazon CloudWatch 警示的 Amazon Resource Name (ARN)，以用作轉返觸發。例如 `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`。您最多可以有五個轉返觸發條件。
**注意**
如果您指定 CloudWatch 警示 ARN，您還需要設定其他許可，以啟用 動作來存取 CloudWatch。如需詳細資訊，請參閱[設定轉返](#deploy-consumption-enable-alarms)。
+ **監控時間**
指定 0 到 180 分鐘的時間量，在此期間CloudFormation 會監控指定的警示。監控會在部署所有堆疊資源*之後*開始。如果警示在指定的監控時間內發生，則部署會失敗，CloudFormation 會復原整個堆疊操作。
預設：0. CloudFormation 只會在部署堆疊資源時監控警示，而不是在部署之後。
------
#### [ YAML ]
**設定「部署 CloudFormation 堆疊」動作的復原觸發**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇包含**部署 CloudFormation 堆疊**動作的工作流程名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 YAML 程式碼中新增 `monitor-alarm-arns`和 `monitor-timeout-in-minutes` 屬性，以新增轉返觸發條件。如需每個屬性的說明，請參閱 [「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。
1. 在**部署 CloudFormation 堆疊**動作的 `role-arn` 屬性中指定的角色中，請務必包含 **CloudWatchFullAccess** 許可。如需使用適當許可建立此角色的資訊，請參閱 [步驟 2：建立 AWS 角色](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles)。
------
------
#### [ Visual ]
**關閉「部署 CloudFormation 堆疊」動作的轉返**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇包含**部署 CloudFormation 堆疊**動作的工作流程名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**部署 CloudFormation 堆疊**動作。
1. 在詳細資訊窗格中，選擇**組態**。
1. 在底部，展開**進階**。
1. 開啟**停用轉返**。
------
#### [ YAML ]
**關閉「部署 CloudFormation 堆疊」動作的轉返**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇包含**部署 CloudFormation 堆疊**動作的工作流程名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 YAML 程式碼中新增 `disable-rollback: 1` 屬性以停止轉返。如需此屬性的說明，請參閱 [「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。
------
# 「部署 CloudFormation 堆疊」變數
**部署 CloudFormation 堆疊**動作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| deployment-platform | 部署平台的名稱。 硬式編碼為 `AWS:CloudFormation`。 |
| region | 在工作流程執行期間 AWS 區域 部署至 的 區域碼。 範例：`us-west-2` |
| stack-id | 部署堆疊的 Amazon Resource Name (ARN)。 範例：`arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cfn-stack/6aad4380-100a-11ec-a10a-03b8a84d40df` |
# 「部署 CloudFormation 堆疊」動作 YAML
以下是**部署 CloudFormation 堆疊**動作的 YAML 定義。若要了解如何使用此動作，請參閱 [部署 CloudFormation 堆疊](deploy-action-cfn.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素會與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
DeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
DependsOn:
- build-action
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: DeployRole
Inputs:
Sources:
- source-name-1
Artifacts:
- CloudFormation-artifact
Configuration:
name: stack-name
region: us-west-2
template: template-path
role-arn: arn:aws:iam::123456789012:role/StackRole
capabilities: CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
parameter-overrides: KeyOne=ValueOne,KeyTwo=ValueTwo | path-to-JSON-file
no-execute-changeset: 1|0
fail-on-empty-changeset: 1|0
disable-rollback: 1|0
termination-protection: 1|0
timeout-in-minutes: minutes
notification-arns: arn:aws:sns:us-east-1:123456789012:MyTopic,arn:aws:sns:us-east-1:123456789012:MyOtherTopic
monitor-alarm-arns: arn:aws:cloudwatch::123456789012:alarm/MyAlarm,arn:aws:cloudwatch::123456789012:alarm/MyOtherAlarm
monitor-timeout-in-minutes: minutes
tags: '[{"Key":"MyKey1","Value":"MyValue1"},{"Key":"MyKey2","Value":"MyValue2"}]'
```
## DeployCloudFormationStack
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在動作名稱中啟用特殊字元和空格。
預設：`DeployCloudFormationStack_nn`。
對應的 UI：組態索引標籤/**動作顯示名稱**
## Identifier
(*DeployCloudFormationStack*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/cfn-deploy@v1`。
對應的 UI：工作流程圖表/DeployCloudFormationStack\$1nn/**aws/cfn-deploy@v1** 標籤
## DependsOn
(*DeployCloudFormationStack*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*DeployCloudFormationStack*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*DeployCloudFormationStack*/Compute/**Type**)
（如果[Compute](#deploy.action.cfn.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/進階 - 選用/**運算類型**
## Fleet
(*DeployCloudFormationStack*/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`。
對應的 UI：組態索引標籤/進階 - 選用/**運算機群**
## Timeout
(*DeployCloudFormationStack*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/以**分鐘為單位的逾時 - 選用 **
## Environment
(*DeployCloudFormationStack*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將 動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*DeployCloudFormationStack*/Environment/**Name**)
（如果[Environment](#deploy.action.cfn.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*DeployCloudFormationStack*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*DeployCloudFormationStack*/Environment/Connections/**Name**)
（如果[Connections](#deploy.action.cfn.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*DeployCloudFormationStack*/Environment/Connections/**Role**)
（如果[Connections](#deploy.action.cfn.environment.connections)包含 則為必要）
指定**部署 CloudFormation 堆疊**動作用來存取 AWS 和 CloudFormation 服務的 IAM 角色名稱。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
**注意**
第一次使用角色時，請在資源政策陳述式中使用下列萬用字元，然後在可用的資源名稱縮小政策範圍。
```
"Resource": "*"
```
+ 下列自訂信任政策：
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Inputs
(*DeployCloudFormationStack*/**Inputs**)
(選用)
`Inputs` 區段定義工作流程執行期間 `DeployCloudFormationStack`所需的資料。
**注意**
每個**部署 CloudFormation 堆疊**動作最多允許四個輸入 （一個來源和三個成品）。
如果您需要參考位於不同輸入中的檔案 （例如來源和成品），則來源輸入是主要輸入，而成品是次要輸入。對次要輸入中檔案的參考需要特殊的字首，才能將其從主要輸入中消除。如需詳細資訊，請參閱[範例：參考多個成品中的檔案](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file)。
對應的 UI：**輸入**索引標籤
## Sources
(*DeployCloudFormationStack*/Inputs/**Sources**)
（如果您的 CloudFormation 或 AWS SAM 範本存放在來源儲存庫中，則為必要項目）
如果您的 CloudFormation 或 AWS SAM 範本存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的 CloudFormation 或 AWS SAM 範本不包含在來源儲存庫中，則必須位於另一個動作所產生的成品中，或位於 Amazon S3 儲存貯體中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*DeployCloudFormationStack*/Inputs/**Artifacts**)
（如果您的 CloudFormation 或 AWS SAM 範本存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要項目）
如果您想要部署的 CloudFormation 或 AWS SAM 範本包含在先前動作產生的成品中，請在此處指定該成品。如果您的 CloudFormation 範本不包含在成品中，則必須位於來源儲存庫或 Amazon S3 儲存貯體中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**文章 - 選用**
## Configuration
(*DeployCloudFormationStack*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## name
(*DeployCloudFormationStack*/Configuration/**name**)
(必要)
指定部署堆疊動作建立或更新的 CloudFormation 堆疊名稱。 ** CloudFormation **
對應的 UI：組態索引標籤/**堆疊名稱**
## region
(*DeployCloudFormationStack*/Configuration/**region**)
(必要)
指定要部署堆疊的 AWS 區域 。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)。
對應的 UI：組態索引標籤/**堆疊區域**
## template
(*DeployCloudFormationStack*/Configuration/**template**)
(必要)
指定 CloudFormation 或 AWS SAM 範本檔案的名稱和路徑。範本可以是 JSON 或 YAML 格式，並且可以位於來源儲存庫、先前動作的成品或 Amazon S3 儲存貯體中。如果範本檔案位於來源儲存庫或成品中，則路徑會相對於來源或成品根目錄。如果範本位於 Amazon S3 儲存貯體中，則路徑是範本的**物件 URL** 值。
範例：
`./MyFolder/MyTemplate.json`
`MyFolder/MyTemplate.yml`
`https://MyBucket.s3.us-west-2.amazonaws.com/MyTemplate.yml`
**注意**
您可能需要將字首新增至範本的檔案路徑，以指出要尋找的成品或來源。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)及[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：組態索引標籤/**範本**
## role-arn
(*DeployCloudFormationStack*/Configuration/**role-arn**)
(必要)
指定堆疊角色的 Amazon Resource Name (ARN)。CloudFormation 使用此角色來存取和修改堆疊中的資源。例如：`arn:aws:iam::123456789012:role/StackRole`。
請確定堆疊角色包含：
+ 一或多個許可政策。這些政策取決於您在堆疊中擁有的資源。例如，如果您的堆疊包含 AWS Lambda 函數，您需要新增授予 Lambda 存取權的許可。如果您遵循 中所述的教學課程[教學課程：部署無伺服器應用程式](deploy-tut-lambda.md)，它包含標題為 的程序，[建立堆疊角色](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles-stack)其中列出當您部署典型的無伺服器應用程式堆疊時堆疊角色所需的許可。
**警告**
將許可限制為 CloudFormation 服務存取堆疊中資源所需的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
+ 下列信任政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "cloudformation.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
或者，將此角色與您的帳戶連線建立關聯。若要進一步了解如何將 IAM 角色與帳戶連線建立關聯，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。如果您未將堆疊角色與帳戶連線建立關聯，堆疊角色就不會出現在視覺化編輯器的**堆疊角色**下拉式清單中；不過，仍然可以使用 YAML 編輯器在 `role-arn` 欄位中指定角色 ARN。
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：組態索引標籤/**堆疊角色 - 選用**
## capabilities
(*DeployCloudFormationStack*/Configuration/**capabilities**)
(必要)
指定允許 CloudFormation 建立特定堆疊所需的 IAM 功能清單。在大多數情況下，您可以使用預設值 `capabilities` 來離開 `CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND`。
如果您在**部署 CloudFormation 堆疊**動作的日誌`##[error] requires capabilities: [capability-name]`中看到 ，請參閱 以取得如何修正問題[如何修正 IAM 功能錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-capabilities)的相關資訊。
如需 IAM 功能的詳細資訊，請參閱《[IAM 使用者指南》中的在 CloudFormation 範本中確認 IAM 資源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities)。 **
對應的 UI：組態索引標籤/進階/**功能**
## parameter-overrides
(*DeployCloudFormationStack*/Configuration/**parameter-overrides**)
(選用)
在 CloudFormation 或 AWS SAM 範本中指定沒有預設值的參數，或您要為其指定非預設值的參數。如需參數的詳細資訊，請參閱* AWS CloudFormation 《 使用者指南*》中的[參數](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html)。
`parameter-overrides` 屬性接受：
+ 包含參數和值的 JSON 檔案。
+ 參數和值的逗號分隔清單。
**指定 JSON 檔案**
1. 請確定 JSON 檔案使用以下其中一個語法：
```
{
"Parameters": {
"Param1": "Value1",
"Param2": "Value2",
...
}
}
```
或者...
```
[
{
"ParameterKey": "Param1",
"ParameterValue": "Value1"
},
...
]
```
（還有其他語法，但撰寫時 CodeCatalyst 不支援這些語法。) 如需在 JSON 檔案中指定 CloudFormation 參數的詳細資訊，請參閱《 *AWS CLI 命令參考*》中的[支援的 JSON 語法](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/deploy/index.html#supported-json-syntax)。
1. 使用下列其中一種格式指定 JSON 檔案的路徑：
+ 如果您的 JSON 檔案位於先前動作的輸出成品中，請使用：
`file:///artifacts/current-action-name/output-artifact-name/path-to-json-file`
如需詳細資訊，請參閱**範例 1**。
+ 如果您的 JSON 檔案位於來源儲存庫中，請使用：
`file:///sources/WorkflowSource/path-to-json-file`
如需詳細資訊，請參閱**範例 2**。
**範例 1** – JSON 檔案位於輸出成品中
```
##My workflow YAML
...
Actions:
MyBuildAction:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ParamArtifact
Files:
- params.json
Configuration:
...
MyDeployCFNStackAction:
Identifier: aws/cfn-deploy@v1
Configuration:
parameter-overrides: file:///artifacts/MyDeployCFNStackAction/ParamArtifact/params.json
```
**範例 2** – JSON 檔案位於名為 的資料夾中的來源儲存庫中 `my/folder`
```
##My workflow YAML
...
Actions:
MyDeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
parameter-overrides: file:///sources/WorkflowSource/my/folder/params.json
```
**使用逗號分隔的參數清單**
+ 使用下列格式在 `parameter-overrides` 屬性中新增參數名稱/值對：
`param-1=value-1,param-2=value-2`
例如，假設下列 CloudFormation 範本：
```
##My CloudFormation template
Description: My CloudFormation template
Parameters:
InstanceType:
Description: Defines the Amazon EC2 compute for the production server.
Type: String
Default: t2.micro
AllowedValues:
- t2.micro
- t2.small
- t3.medium
Resources:
...
```
...您可以設定 `parameter-overrides` 屬性，如下所示：
```
##My workflow YAML
...
Actions:
...
DeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
Configuration:
parameter-overrides: InstanceType=t3.medium,UseVPC=true
```
**注意**
您可以使用 `undefined`做為值，指定沒有對應值的參數名稱。例如：
`parameter-overrides: MyParameter=undefined`
效果是，在堆疊更新期間，CloudFormation 會使用指定參數名稱的現有參數值。
對應的 UI：
+ 組態索引標籤/進階/**參數覆寫**
+ 組態tab/Advanced/Parameter覆寫/**使用檔案指定覆寫**
+ 組態tab/Advanced/Parameter覆寫/**使用值集指定覆寫**
## no-execute-changeset
(*DeployCloudFormationStack*/Configuration/**no-execute-changeset**)
(選用)
指定您是否希望 CodeCatalyst 建立 CloudFormation 變更集，然後在執行之前停止。這可讓您在 CloudFormation 主控台中檢閱變更集。如果您判斷變更集看起來不錯，請停用此選項，然後重新執行工作流程，讓 CodeCatalyst 可以在不停止的情況下建立和執行變更集。預設值是在不停止的情況下建立和執行變更集。如需詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 CloudFormation [部署](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html)參數。如需檢視變更集的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[檢視變更集](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-view.html)。
對應的 UI：組態索引標籤/進階/**未執行變更集**
## fail-on-empty-changeset
(*DeployCloudFormationStack*/Configuration/**fail-on-empty-changeset**)
(選用)
如果 CloudFormation 變更集為空，請指定您是否希望 CodeCatalyst 失敗**部署 CloudFormation 堆疊**動作。（如果變更集是空的，表示在最新的部署期間不會對堆疊進行任何變更。) 預設值是在變更集為空時允許動作繼續，即使堆疊未更新，也會傳回`UPDATE_COMPLETE`訊息。
如需此設定的詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 CloudFormation [部署](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html)參數。如需變更集的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[使用變更集更新堆疊](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html)。
對應的 UI：**空白變更集上的組態索引標籤/進階/失敗**
## disable-rollback
(*DeployCloudFormationStack*/Configuration/**disable-rollback**)
(選用)
指定您是否希望 CodeCatalyst 在堆疊部署失敗時復原堆疊部署。轉返會將堆疊傳回至上次已知的穩定狀態。預設為啟用轉返。如需此設定的詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 CloudFormation [部署](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html)參數。
如需**部署 CloudFormation 堆疊**動作如何處理轉返的詳細資訊，請參閱 [設定轉返](deploy-consumption-enable-alarms.md)。
如需復原堆疊的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[堆疊失敗選項](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html)。
對應的 UI：組態索引標籤/進階/**停用復原**
## termination-protection
(*DeployCloudFormationStack*/Configuration/**termination-protection**)
(選用)
指定您是否希望**部署 CloudFormation 堆疊**為其正在部署的堆疊新增終止保護。如果使用者嘗試刪除啟用終止保護的堆疊，則刪除會失敗，且堆疊及其狀態保持不變。預設為停用終止保護。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[防止堆疊遭到刪除](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html)。
對應的 UI：組態索引標籤/進階/**終止保護**
## timeout-in-minutes
(*DeployCloudFormationStack*/Configuration/**timeout-in-minutes**)
(選用)
指定 CloudFormation 在逾時堆疊建立操作並將堆疊狀態設定為 之前應分配的時間量，以分鐘為單位`CREATE_FAILED`。如果 CloudFormation 無法在分配的時間內建立整個堆疊，操作便會因為逾時而失敗，並復原堆疊。
依預設，堆疊建立沒有逾時。不過，個別資源可能會因其實作的服務性質而有自己的逾時。例如，如果堆疊中的個別資源逾時，堆疊建立也會逾時，即使尚未達到您指定的堆疊建立逾時。
對應的 UI：組態索引標籤/進階/**CloudFormation 逾時**
## notification-arns
(*DeployCloudFormationStack*/Configuration/**notification-arns**)
(選用)
指定您希望 CodeCatalyst 傳送通知訊息的 Amazon SNS 主題 ARN。例如 `arn:aws:sns:us-east-1:111222333:MyTopic`。**部署 CloudFormation 堆疊**動作執行時，CodeCatalyst 會與 CloudFormation 協調，針對堆疊建立或更新程序期間發生的每個 CloudFormation 事件傳送一個通知。（事件會顯示在 CloudFormation 主控台的堆疊**事件**索引標籤中。) 您最多可以指定五個主題。如需詳細資訊，請參閱[什麼是 Amazon SNS？](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)。
對應的 UI：組態索引標籤/進階/**通知 ARNs**
## monitor-alarm-arns
(*DeployCloudFormationStack*/Configuration/**monitor-alarm-arns**)
(選用)
指定 Amazon CloudWatch 警示的 Amazon Resource Name (ARN)，以用作轉返觸發。例如 `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`。您最多可以有五個轉返觸發。
**注意**
如果您指定 CloudWatch 警示 ARN，您還需要設定其他許可，以啟用 動作來存取 CloudWatch。如需詳細資訊，請參閱[設定轉返](deploy-consumption-enable-alarms.md)。
對應的 UI：組態索引標籤/進階/**監控警示 ARNs **
## monitor-timeout-in-minutes
(*DeployCloudFormationStack*/Configuration/**monitor-timeout-in-minutes**)
(選用)
指定時間量，從 0 到 180 分鐘，在此期間CloudFormation 會監控指定的警示。部署所有堆疊資源*之後*，監控就會開始。如果警示在指定的監控時間內發生，則部署會失敗，CloudFormation 會復原整個堆疊操作。
預設：0. CloudFormation 只會在部署堆疊資源時監控警示，而不是在部署之後。
對應的 UI：組態索引標籤/進階/**監控時間**
## tags
(*DeployCloudFormationStack*/Configuration/**tags**)
(選用)
指定要連接到 CloudFormation 堆疊的標籤。標籤是任意索引鍵/值組，可用於識別堆疊，例如成本分配。如需有關標籤定義及標籤使用方式的詳細資訊，請參閱《Amazon EC2 使用者指南》中的[標記您的資源](https://docs.aws.amazon.com/)。如需在 CloudFormation 中標記的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[設定 CloudFormation 堆疊選項](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-add-tags.html)。
金鑰可以有英數字元或空格，且最多可有 127 個字元。值可以有英數字元或空格，且最多可有 255 個字元。
您最多可以為每個堆疊新增 50 個唯一的標籤。
對應的 UI：組態索引標籤/進階/**標籤**
# 使用工作流程部署 AWS CDK 應用程式
本節說明如何使用工作流程將 AWS Cloud Development Kit (AWS CDK) 應用程式部署到您的 AWS 帳戶。若要達成此目的，您必須將**AWS CDK 部署**動作新增至工作流程。**AWS CDK 部署**動作會合成您的 AWS Cloud Development Kit (AWS CDK) 應用程式並將其部署到其中 AWS。如果您的應用程式已存在於 中 AWS，則動作會視需要更新它。
如需使用 撰寫應用程式的一般資訊 AWS CDK，請參閱[什麼是 AWS CDK？](https://docs.aws.amazon.com/cdk/v2/guide/home.html) 《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的 。
**Topics**
+ [何時使用 'AWS CDK deploy' 動作](#cdk-dep-action-when-to-use)
+ [「AWS CDK 部署」動作的運作方式](#cdk-dep-action-how-it-works)
+ [「AWS CDK 部署」動作使用的 CDK CLI 版本](#cdk-dep-action-cdk-version)
+ [「AWS CDK 部署」動作使用的執行期映像](#cdk-dep-action-runtime)
+ [動作可以部署多少個堆疊？](#cdk-dep-action-how-many-stacks)
+ [範例：部署 AWS CDK 應用程式](cdk-dep-action-example-workflow.md)
+ [新增「AWS CDK 部署」動作](cdk-dep-action-add.md)
+ [「AWS CDK 部署」變數](cdk-dep-action-variables.md)
+ [「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)
## 何時使用 'AWS CDK deploy' 動作
如果您已使用 開發應用程式 AWS CDK，且現在想要將其自動部署為自動化持續整合和交付 (CI/CD) 工作流程的一部分，請使用此動作。例如，您可能想要在有人合併與 AWS CDK 應用程式來源相關的提取請求時自動部署 AWS CDK 應用程式。
## 「AWS CDK 部署」動作的運作方式
**AWS CDK 部署**的運作方式如下：
1. 在執行時間，如果您指定 動作的 1.0.12 版或更早版本，動作會將最新的 CDK CLI （也稱為 AWS CDK Tookit) 下載至 CodeCatalyst [執行時間環境映像](#cdk-dep-action-runtime)。
如果您指定 1.0.13 版或更新版本，動作會隨附[特定版本的](#cdk-dep-action-cdk-version) CDK CLI，因此不會進行下載。
1. 動作會使用 CDK CLI 來執行 `cdk deploy`命令。此命令會合成您的 AWS CDK 應用程式並將其部署到其中 AWS。如需此命令的詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的 [AWS CDK Toolkit (cdk 命令）](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) 主題。
## 「AWS CDK 部署」動作使用的 CDK CLI 版本
下表顯示部署**AWS CDK **動作不同版本預設使用的 CDK CLI 版本。
**注意**
您可能可以覆寫預設值。如需詳細資訊，請參閱 [「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md) 中的 [CdkCliVersion](cdk-dep-action-ref.md#cdk.dep.cdk.cli.version)。
| 「AWS CDK 部署」動作版本 | AWS CDK CLI 版本 |
| --- | --- |
| 1.0.0 – 1.0.12 | 最新 |
| 1.0.13 或更新版本 | 2.99.1 |
## 「AWS CDK 部署」動作使用的執行期映像
下表顯示 CodeCatalyst 用來執行不同版本**AWS CDK 部署**動作的執行期環境映像。影像包含不同的預先安裝工具集。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
**注意**
我們建議您將**AWS CDK 部署**動作升級至 2.x 版，以利用 2024 年 3 月映像中可用的最新工具。若要升級動作，`aws/cdk-deploy@v2`請在工作流程定義檔案中將其`Identifier`屬性設定為 。如需詳細資訊，請參閱[「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。
| 「AWS CDK 部署」動作版本 | 執行期環境映像 |
| --- | --- |
| 1.x | 2022 年 11 月影像 |
| 2.x | 2024 年 3 月影像 |
## 動作可以部署多少個堆疊？
**AWS CDK 部署**只能部署單一堆疊。如果您的 AWS CDK 應用程式包含多個堆疊，您必須建立具有巢狀堆疊的父堆疊，並使用此動作部署父堆疊。
# 範例：部署 AWS CDK 應用程式
下列範例工作流程包含**AWS CDK 部署**動作，以及**AWS CDK 引導**操作。工作流程包含下列依順序執行的建置區塊：
+ **觸發**條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。此儲存庫包含您的 AWS CDK 應用程式。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **AWS CDK 引導**操作 (`CDKBootstrap`) – 在觸發時，該動作會將`CDKToolkit`引導堆疊部署到其中 AWS。如果`CDKToolkit`堆疊已存在於環境中，將會視需要升級；否則不會發生任何情況，且動作會標示為成功。
+ **AWS CDK 部署**動作 (`AWS CDK Deploy`) – **AWS CDK 引導**動作完成後，**AWS CDK 部署**動作會將您的 AWS CDK 應用程式程式碼合成至 CloudFormation 範本，並將範本中定義的堆疊部署至其中 AWS。
**注意**
下列工作流程範例僅供說明之用，如果沒有其他組態，將無法運作。
**注意**
在後續的 YAML 程式碼中，您可以視需要省略這些`Connections:`區段。如果您省略這些區段，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含**AWS CDK 引導**和**AWS CDK 部署**動作所需的許可和信任政策。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。如需**AWS CDK 引導**和**AWS CDK 部署**動作所需許可和信任政策的詳細資訊，請參閱 [「AWS CDK 引導」動作 YAML](cdk-boot-action-ref.md)和 中的 `Role` 屬性描述[「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。
```
Name: codecatalyst-cdk-deploy-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
CDKBootstrap:
Identifier: aws/cdk-bootstrap@v2
Inputs:
Sources:
- WorkflowSource
Environment:
Name: codecatalyst-cdk-deploy-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-cdk-bootstrap-role
Configuration:
Region: us-west-2
CDKDeploy:
Identifier: aws/cdk-deploy@v2
DependsOn:
- CDKBootstrap
Environment:
Name: codecatalyst-cdk-deploy-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-cdk-deploy-role
Inputs:
Sources:
- WorkflowSource
Configuration:
StackName: my-app-stack
Region: us-west-2
```
# 新增「AWS CDK 部署」動作
使用下列指示將**AWS CDK 部署**動作新增至您的工作流程。
**開始之前**
在您可以將**AWS CDK 部署**動作新增至工作流程之前，請先完成下列任務：
1. **準備好 AWS CDK 應用程式**。您可以使用 AWS CDK v1 或 v2，以 支援的任何程式設計語言撰寫 AWS CDK 應用程式 AWS CDK。確保您的 AWS CDK 應用程式檔案可用於：
+ CodeCatalyst [來源儲存庫](source.md)，或
+ 由另一個工作流程動作產生的 CodeCatalyst [輸出成品](workflows-working-artifacts.md)
1. **引導您的 AWS 環境**。若要引導，您可以：
+ 使用《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中[如何引導](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-howto)所述的其中一種方法。
+ 使用**AWS CDK 引導**操作。您可以在與**AWS CDK 部署**相同的工作流程中新增此動作，或在不同的工作流程中新增此動作。只要確定引導操作在執行**AWS CDK 部署**動作之前至少執行一次，以便有必要的資源。如需**AWS CDK 引導**操作的詳細資訊，請參閱 [使用工作流程引導 AWS CDK 應用程式](cdk-boot-action.md)。
如需引導的詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的[引導](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)。
------
#### [ Visual ]
**使用視覺化編輯器新增「AWS CDK 部署」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS CDK 部署**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**AWS CDK 部署**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
**注意**
如果您的**AWS CDK 部署**動作失敗並發生錯誤`npm install`，請參閱 以取得如何修正錯誤[如何修正「npm 安裝」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-npm)的資訊。
------
#### [ YAML ]
**使用 YAML 編輯器新增「AWS CDK 部署」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS CDK 部署**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**AWS CDK 部署**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**下載**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
**注意**
如果您的**AWS CDK 部署**動作失敗並發生錯誤`npm install`，請參閱 以取得如何修正錯誤[如何修正「npm 安裝」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-npm)的資訊。
------
# 「AWS CDK 部署」變數
**AWS CDK 部署**動作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| stack-id | 在工作流程執行期間部署至 之 AWS CDK 應用程式堆疊的 Amazon Resource Name (ARN)。 範例：`arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cdk-app-stack/6aad4380-100a-11ec-a10a-03b8a84d40df` |
| deployment-platform | 部署平台的名稱。 硬式編碼為 `AWS:CloudFormation`。 |
| region | 在工作流程執行期間 AWS 區域 部署至 的 區域碼。 範例：`us-west-2` |
| SKIP-DEPLOYMENT | 值 `true`表示在工作流程執行期間略過 AWS CDK 應用程式堆疊的部署。如果堆疊自上次部署以來沒有變更，則會略過堆疊部署。 只有在其值為 時，才會產生此變數`true`。 硬式編碼為 `true`。 |
| *CloudFormation 變數* | 除了產生先前列出的變數之外，**AWS CDK 部署**動作還會將 *CloudFormation* 輸出變數公開為*工作流程*變數，以供後續工作流程動作使用。根據預設， 動作只會公開其找到的前四個 （或更少） CloudFormation 變數。若要判斷哪些公開，請執行一次**AWS CDK 部署**動作，然後查看執行詳細資訊頁面的**變數**索引標籤。如果變數索引標籤上列出的變數不是您想要的變數，您可以使用 `CfnOutputVariables` YAML 屬性來設定不同的**變數**。如需詳細資訊，請參閱 中的 [CfnOutputVariables](cdk-dep-action-ref.md#cdk.dep.cfn.out) 屬性描述[「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。 |
# 「AWS CDK 部署」動作 YAML
以下是**AWS CDK 部署**動作的 YAML 定義。若要了解如何使用此動作，請參閱 [使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
CDKDeploy\$1nn:
Identifier: aws/cdk-deploy@v2
DependsOn:
- CDKBootstrap
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- artifact-name
Outputs:
Artifacts:
- Name: cdk_artifact
Files:
- "cdk.out/**/*"
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Configuration:
StackName: my-cdk-stack
Region: us-west-2
Tags: '{"key1": "value1", "key2": "value2"}'
Context: '{"key1": "value1", "key2": "value2"}'
CdkCliVersion: version
CdkRootPath: directory-containing-cdk.json-file
CfnOutputVariables: '["CnfOutputKey1","CfnOutputKey2","CfnOutputKey3"]'
CloudAssemblyRootPath: path-to-cdk.out
```
## CDKDeploy
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
預設：`CDKDeploy_nn`。
對應的 UI：組態索引標籤/**動作名稱**
## Identifier
(*CDKDeploy*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
**注意**
指定 `aws/cdk-deploy@v2`會導致 動作在 [2024 年 3 月映像](build-images.md#build.default-image)上執行，其中包括較新的工具，例如 Node.js 18。指定 `aws/cdk-deploy@v1`會導致 動作在 [2022 年 11 月映像](build-images.md#build.previous-image)上執行，其中包含舊版工具，例如 Node.js 16。
預設：`aws/cdk-deploy@v2`。
對應的 UI：工作流程圖表/CDKDeploy\$1nn/**aws/cdk-deploy@v2** 標籤
## DependsOn
(*CDKDeploy*/**DependsOn**)
(選用)
指定必須成功執行的動作或動作群組，才能執行**AWS CDK 部署**動作。建議您在 `DependsOn` 屬性中指定**AWS CDK 引導**操作，如下所示：
```
CDKDeploy:
Identifier: aws/cdk-deploy@v2
DependsOn:
- CDKBootstrap
```
**注意**
[引導](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)是部署 AWS CDK 應用程式的強制性先決條件。如果您未在工作流程中包含**AWS CDK 引導**操作，則必須先找到另一種方法來部署 AWS CDK 引導堆疊，才能執行**AWS CDK 部署**動作。如需詳細資訊，請參閱 [使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md) 中的 [新增「AWS CDK 部署」動作](cdk-dep-action-add.md)。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*CDKDeploy*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*CDKDeploy*/Compute/**Type**)
（如果[Compute](#cdk.dep.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
針對動作執行期間的彈性進行最佳化。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/進階 - 選用/**運算類型**
## Fleet
(*CDKDeploy*/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`。
對應的 UI：組態索引標籤/進階 - 選用/**運算機群**
## Timeout
(*CDKDeploy*/**Timeout**)
(必要)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Inputs
(*CDKDeploy*/**Inputs**)
(選用)
`Inputs` 區段定義工作流程執行期間 `CDKDeploy`所需的資料。
**注意**
每個**AWS CDK 部署**動作只允許一個輸入 （來源或成品）。
對應的 UI：**輸入**索引標籤
## Sources
(*CDKDeploy*/Inputs/**Sources**)
（如果您要部署 AWS CDK 的應用程式存放在來源儲存庫中，則為必要項目）
如果您的 AWS CDK 應用程式存放在來源儲存庫中，請指定該來源儲存庫的標籤。**AWS CDK 部署**動作會在開始部署程序之前，在此儲存庫中合成應用程式。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的 AWS CDK 應用程式不包含在來源儲存庫中，則必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*CDKDeploy*/Inputs/**Artifacts**)
（如果您要部署 AWS CDK 的應用程式存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要）
如果您的 AWS CDK 應用程式包含在先前動作產生的成品中，請在此處指定該成品。部署動作會在啟動**AWS CDK 部署**程序之前，將指定成品中的應用程式合成至 CloudFormation 範本。如果您的 AWS CDK 應用程式不包含在成品中，則必須位於您的來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸入索引標籤/**成品 - 選用**
## Outputs
(*CDKDeploy*/**Outputs**)
(選用)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts - output
(*CDKDeploy*/Outputs/**Artifacts**
(選用)
指定 動作產生的成品。您可以在其他動作中參考這些成品做為輸入。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/**成品**
## Name
(*CDKDeploy*/Outputs/Artifacts/**Name**)
（如果[Artifacts - output](#cdk.dep.outputs.artifacts)包含 則為必要）
指定成品的名稱，該成品將包含由**AWS CDK 部署**動作在執行時間合成的 CloudFormation 範本。預設值為 `cdk_artifact`。如果您未指定成品，則動作會合成範本，但不會將其儲存在成品中。考慮將合成的範本儲存在成品中，以保留記錄以供測試或故障診斷之用。
對應的 UI：輸出tab/Artifacts/Add成品/**建置成品名稱**
## Files
(*CDKDeploy*/Outputs/Artifacts/**Files**)
（如果[Artifacts - output](#cdk.dep.outputs.artifacts)包含 則為必要）
指定要包含在成品中的檔案。您必須指定 `"cdk.out/**/*"`以包含 AWS CDK 應用程式的合成 CloudFormation 範本。
**注意**
`cdk.out` 是將合成檔案儲存到其中的預設目錄。如果您在 `cdk.json` 檔案中指定 `cdk.out`以外的輸出目錄，請在此處指定該目錄，而非 `cdk.out`。
對應的 UI：輸出tab/Artifacts/Add**建置產生的成品/檔案**
## Environment
(*CDKDeploy*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*CDKDeploy*/Environment/**Name**)
（如果[Environment](#cdk.dep.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*CDKDeploy*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*CDKDeploy*/Environment/Connections/**Name**)
（如果[Connections](#cdk.dep.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*CDKDeploy*/Environment/Connections/**Role**)
（如果[Connections](#cdk.dep.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
指定**AWS CDK 部署**動作用來存取 AWS 和部署 AWS CDK 應用程式堆疊的 IAM 角色名稱。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStackEvents",
"cloudformation:DescribeChangeSet",
"cloudformation:DescribeStacks",
"cloudformation:ListStackResources"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/cdk-*"
}
]
}
```
------
+ 下列自訂信任政策：
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Configuration
(*CDKDeploy*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## StackName
(*CDKDeploy*/Configuration/**StackName**)
(必要)
應用程式 AWS CDK 堆疊的名稱，如應用程式 AWS CDK `bin`目錄中的進入點檔案中所示。下列範例顯示 TypeScript 進入點檔案的內容，堆疊名稱以*紅色斜體*反白顯示。如果您的進入點檔案使用不同的語言，它看起來會相似。
```
import * as cdk from 'aws-cdk-lib';
import { CdkWorksopTypescriptStack } from '../lib/cdk_workshop_typescript-stack';
const app = new cdk.App();
new CdkWorkshopTypescriptStack(app, 'CdkWorkshopTypescriptStack');
```
您只能指定一個堆疊。
**提示**
如果您有多個堆疊，您可以使用巢狀堆疊建立父堆疊。然後，您可以在此動作中指定父堆疊來部署所有堆疊。
對應的 UI：組態索引標籤/**堆疊名稱**
## Region
(*CDKDeploy*/Configuration/**Region**)
(選用)
指定要部署 AWS CDK 應用程式堆疊的 AWS 區域 。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)。
如果您未指定區域，**AWS CDK 部署**動作會部署到 AWS CDK 程式碼中指定的區域。如需詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*[》中的環境](https://docs.aws.amazon.com/cdk/v2/guide/environments.html)。
對應的 UI：組態索引標籤/**區域**
## Tags
(*CDKDeploy*/Configuration/**Tags**)
(選用)
指定您要套用至 AWS CDK 應用程式堆疊中 AWS 資源的標籤。標籤會套用至堆疊本身，以及堆疊中的個別資源。如需標記的詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的[標記](https://docs.aws.amazon.com/cdk/v2/guide/tagging.html)。
對應的 UI：組態索引標籤/進階 - 選用/**標籤**
## Context
(*CDKDeploy*/Configuration/**Context**)
(選用)
以鍵值對的形式指定要與 AWS CDK 應用程式堆疊建立關聯的內容。如需內容的詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的[執行期內容](https://docs.aws.amazon.com/cdk/v2/guide/context.html)。
對應的 UI：組態索引標籤/進階 - 選用/**內容**
## CdkCliVersion
(*CDKDeploy*/Configuration/**CdkCliVersion**)
(選用)
此屬性適用於 1.0.13 版或更新版本的**AWS CDK 部署**動作，以及 1.0.8 版或更新版本的**AWS CDK 引導**動作。
請指定下列其中一項：
+ 您希望此動作使用的 AWS Cloud Development Kit (AWS CDK) 命令列界面 (CLI) 完整版本 （也稱為 AWS CDK Toolkit)。範例：`2.102.1`。請考慮指定完整版本，以確保建置和部署應用程式時的一致性和穩定性。
或
+ `latest`。 考慮指定 `latest`以利用 CDK CLI 的最新功能和修正。
動作會將指定的 CLI AWS CDK 版本 （或最新版本） 下載至 CodeCatalyst [建置映像](build-images.md)，然後使用此版本來執行部署 CDK 應用程式或引導環境 AWS 所需的命令。
如需您可以使用的支援 CDK CLI 版本清單，請參閱[AWS CDK 版本](https://docs.aws.amazon.com/cdk/api/versions.html)。
如果您省略此屬性，動作會使用下列其中一個主題所述的預設 AWS CDK CLI 版本：
+ [「AWS CDK 部署」動作使用的 CDK CLI 版本](cdk-dep-action.md#cdk-dep-action-cdk-version)
+ ["AWS CDK bootstrap" 動作使用的 CDK CLI 版本](cdk-boot-action.md#cdk-boot-action-cdk-version)
對應的 UI：組態索引標籤/**AWS CDK CLI 版本**
## CdkRootPath
(*CDKDeploy*/Configuration/**CdkRootPath**)
(選用)
包含 AWS CDK 專案`cdk.json`檔案的目錄路徑。**AWS CDK 部署**動作會從此資料夾執行，而動作建立的任何輸出都會新增至此目錄。如果未指定，**AWS CDK 部署**動作會假設 `cdk.json` 檔案位於 AWS CDK 專案的根目錄中。
對應的 UI：組態索引標籤/**cdk.json 所在的目錄**
## CfnOutputVariables
(*CDKDeploy*/Configuration/**CfnOutputVariables**)
(選用)
指定您要在 AWS CDK 應用程式程式碼中公開為工作流程輸出變數的`CfnOutput`建構。然後，您可以在工作流程的後續動作中參考工作流程輸出變數。如需 CodeCatalyst 中變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
例如，如果您 AWS CDK 的應用程式程式碼如下所示：
```
import { Duration, Stack, StackProps, CfnOutput, RemovalPolicy} from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
export class HelloCdkStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: RemovalPolicy.DESTROY,
});
new CfnOutput(this, 'bucketName', {
value: bucket.bucketName,
description: 'The name of the s3 bucket',
exportName: 'amzn-s3-demo-bucket',
});
const table = new dynamodb.Table(this, 'todos-table', {
partitionKey: {name: 'todoId', type: dynamodb.AttributeType.NUMBER},
billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
removalPolicy: RemovalPolicy.DESTROY,
})
new CfnOutput(this, 'tableName', {
value: table.tableName,
description: 'The name of the dynamodb table',
exportName: 'myDynamoDbTable',
});
...
}
}
```
...而您的`CfnOutputVariables`屬性如下所示：
```
Configuration:
...
CfnOutputVariables: '["bucketName","tableName"]'
```
...然後動作會產生下列工作流程輸出變數：
| 金鑰 | 值 |
| --- | --- |
| bucketName | `bucket.bucketName` |
| tableName | `table.tableName` |
然後，您可以在後續動作中參考 `bucketName`和 `tableName`變數。若要了解如何在後續動作中參考工作流程輸出變數，請參閱 [參考預先定義的變數](workflows-working-with-variables-reference-output-vars.md)。
如果您未在 `CfnOutputVariables` 屬性中指定任何`CfnOutput`建構，則動作會公開其視為工作流程輸出變數的前四個 （或更少） CloudFormation 輸出變數。如需詳細資訊，請參閱[「AWS CDK 部署」變數](cdk-dep-action-variables.md)。
**提示**
若要取得動作產生的所有 CloudFormation 輸出變數清單，請執行包含**AWS CDK 部署**動作的工作流程一次，然後查看動作的**日誌**索引標籤。日誌包含與您的 AWS CDK 應用程式相關聯的所有 CloudFormation 輸出變數清單。知道所有 CloudFormation 變數是什麼後，您可以使用 `CfnOutputVariables` 屬性指定要轉換為工作流程輸出變數的變數。
如需 CloudFormation 輸出變數的詳細資訊，請參閱 API `CfnOutput` 參考中的建構文件，可在 [ CfnOutput （建構） 類別](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutput.html)取得。 *AWS Cloud Development Kit (AWS CDK) *
對應的 UI：組態索引標籤/**CloudFormation 輸出變數**
## CloudAssemblyRootPath
(*CDKDeploy*/Configuration/**CloudAssemblyRootPath**)
(選用)
如果您已將 AWS CDK 應用程式的堆疊合成至雲端組件 （使用 `cdk synth`操作），請指定雲端組件目錄的根路徑 (`cdk.out`)。位於指定雲端組件目錄中的 CloudFormation 範本，將由**AWS CDK 部署**動作 AWS 帳戶 使用 `cdk deploy --app`命令部署至您的 。當 `--app`選項存在時，不會發生 `cdk synth`操作。
如果您未指定雲端組件目錄，則**AWS CDK 部署**動作將在沒有 `--app`選項的情況下執行 `cdk deploy`命令。如果沒有 `--app`選項，`cdk deploy`操作將同時合成 (`cdk synth`) 並將您的 AWS CDK 應用程式部署到您的 AWS 帳戶。
**當「AWS CDK 部署」動作可以在執行時間進行合成時，為什麼要指定現有的合成雲端組件？**
您可能想要指定現有的合成雲端組件，以：
+ **確保每次「部署」動作執行時，都會AWS CDK 部署完全相同的資源集**
如果您未指定雲端組件，**AWS CDK 則部署**動作可能會根據執行時間來合成和部署不同的檔案。例如，**AWS CDK 部署**動作可能會在測試階段期間合成具有一組相依性的雲端組件，以及在生產階段期間合成另一組相依性 （如果這些相依性在階段之間變更）。為了確保測試內容與部署內容之間的完全相同性，我們建議合成一次，然後使用**路徑到雲端組件目錄**欄位 （視覺化編輯器） 或`CloudAssemblyRootPath`屬性 (YAML 編輯器） 來指定已合成的雲端組件。
+ **搭配 AWS CDK 應用程式使用非標準套件管理員和工具**
在`synth`操作期間，**AWS CDK 部署**動作會嘗試使用標準工具執行您的應用程式，例如 npm 或 pip。如果動作無法使用這些工具成功執行您的應用程式，則不會進行合成，且動作會失敗。若要解決此問題，您可以在應用程式的 AWS CDK `cdk.json` 檔案中指定成功執行應用程式所需的確切命令，然後使用不涉及**AWS CDK 部署**動作的方法合成應用程式。產生雲端組件之後，您可以在**AWS CDK 部署**動作的**雲端組件目錄路徑**欄位 （視覺化編輯器） 或`CloudAssemblyRootPath`屬性 (YAML 編輯器） 中指定它。
如需設定 `cdk.json` 檔案以包含安裝和執行 AWS CDK 應用程式的命令的詳細資訊，請參閱[指定應用程式命令](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-app-command)。
如需 `cdk deploy`和 `cdk synth`命令以及 `--app`選項的相關資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的[部署堆疊](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy)、[合成堆疊](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-synth)和[略過合成](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-nosynth)。
如需雲端組件的相關資訊，請參閱 *AWS Cloud Development Kit (AWS CDK) API 參考*中的[雲端組件](https://docs.aws.amazon.com/cdk/api/v2/docs/cloud-assembly-schema-readme.html)。
對應的 UI：組態索引標籤/**通往雲端組件目錄的路徑**
# 使用工作流程引導 AWS CDK 應用程式
本節說明如何使用 CodeCatalyst 工作流程引導 AWS CDK 應用程式。若要達成此目的，您必須將**AWS CDK 引導**操作新增至工作流程。**AWS CDK 引導**操作會使用[現代範本](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-template)在您的 AWS 環境中佈建引導堆疊。如果引導堆疊已存在，動作會視需要更新它。在 中具有引導堆疊 AWS 是部署 AWS CDK 應用程式的先決條件。
如需引導的詳細資訊，請參閱《 *AWS Cloud Development Kit (AWS CDK) 開發人員指南*》中的[引導](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)。
**Topics**
+ [何時使用 'AWS CDK bootstrap' 動作](#cdk-boot-action-when-to-use)
+ [「AWS CDK bootstrap」動作的運作方式](#cdk-boot-action-how-it-works)
+ ["AWS CDK bootstrap" 動作使用的 CDK CLI 版本](#cdk-boot-action-cdk-version)
+ [「AWS CDK bootstrap」動作所使用的執行期映像](#cdk-boot-action-runtime)
+ [範例：引導 AWS CDK 應用程式](cdk-boot-action-example-workflow.md)
+ [新增 'AWS CDK bootstrap' 動作](cdk-boot-action-add.md)
+ ['AWS CDK bootstrap' 變數](cdk-boot-action-variables.md)
+ [「AWS CDK 引導」動作 YAML](cdk-boot-action-ref.md)
## 何時使用 'AWS CDK bootstrap' 動作
如果您有部署 AWS CDK 應用程式的工作流程，而且您想要同時部署 （並視需要更新） 引導堆疊，請使用此動作。在此情況下，您會將**AWS CDK 引導**操作新增至與部署 AWS CDK 應用程式相同的工作流程。
如果符合下列任一條件，**請勿使用**此動作：
+ 您已使用另一個機制部署引導堆疊，而且想要保持完整 （無更新）。
+ 您想要使用[自訂引導範本，該範本](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-customizing)不受**AWS CDK 引導**動作支援。
## 「AWS CDK bootstrap」動作的運作方式
**AWS CDK 引導運作**方式如下：
1. 在執行時間，如果您指定 動作的 1.0.7 版或更早版本，動作會將最新的 CDK CLI （也稱為 AWS CDK Tookit) 下載至 CodeCatalyst [建置映像](build-images.md)。
如果您指定 1.0.8 版或更新版本，動作會隨附[特定版本的](cdk-dep-action.md#cdk-dep-action-cdk-version) CDK CLI，因此不會進行下載。
1. 動作會使用 CDK CLI 來執行 `cdk bootstrap`命令。此命令會執行*AWS Cloud Development Kit (AWS CDK) 開發人員指南*中引導主題中所述的[引導](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)任務。
## "AWS CDK bootstrap" 動作使用的 CDK CLI 版本
下表顯示不同的**AWS CDK 引導**操作版本預設使用的 CDK CLI 版本。
**注意**
您可能可以覆寫預設值。如需詳細資訊，請參閱 [「AWS CDK 引導」動作 YAML](cdk-boot-action-ref.md) 中的 [CdkCliVersion](cdk-boot-action-ref.md#cdk.boot.cdk.cli.version)。
| 'AWS CDK bootstrap' 動作版本 | AWS CDK CLI 版本 |
| --- | --- |
| 1.0.0 – 1.0.7 | 最新 |
| 1.0.8 或更新版本 | 2.99.1 |
## 「AWS CDK bootstrap」動作所使用的執行期映像
下表顯示 CodeCatalyst 用來執行不同版本**AWS CDK 引導**操作的執行期環境映像。影像包含不同的預先安裝工具集。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
**注意**
我們建議您將**AWS CDK 引導**操作升級至 2.x 版，以利用 2024 年 3 月映像中可用的最新工具。若要升級動作，`aws/cdk-bootstrap@v2`請在工作流程定義檔案中將其`Identifier`屬性設定為 。如需詳細資訊，請參閱[「AWS CDK 部署」動作 YAML](cdk-dep-action-ref.md)。
| 'AWS CDK bootstrap' 動作版本 | 執行期環境映像 |
| --- | --- |
| 1.x | 2022 年 11 月影像 |
| 2.x | 2024 年 3 月影像 |
# 範例：引導 AWS CDK 應用程式
如需包含**AWS CDK 引導**操作的[使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)工作流程，請參閱 [範例：部署 AWS CDK 應用程式](cdk-dep-action-example-workflow.md) 中的 。
# 新增 'AWS CDK bootstrap' 動作
使用下列指示將**AWS CDK 引導**操作新增至您的工作流程。
**開始之前**
在您可以使用**AWS CDK 引導**操作之前，請確定您已備妥 AWS CDK 應用程式。引導操作會在引導之前合成 AWS CDK 應用程式。您可以使用 支援的任何程式設計語言撰寫應用程式 AWS CDK。
確保您的 AWS CDK 應用程式檔案可用於：
+ CodeCatalyst [來源儲存庫](source.md)，或
+ 由另一個工作流程動作產生的 CodeCatalyst [輸出成品](workflows-working-artifacts.md)
------
#### [ Visual ]
**使用視覺化編輯器新增 'AWS CDK bootstrap' 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS CDK 引導**操作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**AWS CDK 引導。**動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**、**組態**和**輸出**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「AWS CDK 引導」動作 YAML](cdk-boot-action-ref.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
**注意**
如果您的**AWS CDK 引導**操作失敗並發生錯誤`npm install`，請參閱 以取得如何修正錯誤[如何修正「npm 安裝」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-npm)的資訊。
------
#### [ YAML ]
**使用 YAML 編輯器新增 'AWS CDK bootstrap' 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS CDK 引導**操作，然後選擇 **\$1** 將其新增至工作流程圖表，並開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「AWS CDK 引導」動作 YAML](cdk-boot-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
**注意**
如果您的**AWS CDK 引導**操作失敗並發生錯誤`npm install`，請參閱 以取得如何修正錯誤[如何修正「npm 安裝」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-npm)的資訊。
------
# 'AWS CDK bootstrap' 變數
**AWS CDK 引導**操作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| deployment-platform | 部署平台的名稱。 硬式編碼為 `AWS:CloudFormation`。 |
| region | 在工作流程執行期間 AWS CDK 部署引導堆疊 AWS 區域 的 區域碼。 範例：`us-west-2` |
| stack-id | 部署 AWS CDK 引導堆疊的 Amazon Resource Name (ARN)。 範例：`arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cdk-bootstrap-stack/6aad4380-100a-11ec-a10a-03b8a84d40df` |
| SKIP-DEPLOYMENT | 值 `true`表示在工作流程執行期間略過 AWS CDK 了引導堆疊的部署。如果堆疊自上次部署以來沒有變更，則會略過堆疊部署。 只有在其值為 時，才會產生此變數`true`。 硬式編碼為 `true`。 |
# 「AWS CDK 引導」動作 YAML
以下是**AWS CDK 引導**操作的 YAML 定義。若要了解如何使用此動作，請參閱 [使用工作流程引導 AWS CDK 應用程式](cdk-boot-action.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
CDKBootstrapAction\$1nn:
Identifier: aws/cdk-bootstrap@v2
DependsOn:
- action-name
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- artifact-name
Outputs:
Artifacts:
- Name: cdk_bootstrap_artifacts
Files:
- "cdk.out/**/*"
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Configuration:
Region: us-west-2
CdkCliVersion: version
```
## CDKBootstrapAction
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
預設：`CDKBootstrapAction_nn`。
對應的 UI：組態索引標籤/**動作顯示名稱**
## Identifier
(*CDKBootstrapAction*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
**注意**
指定 `aws/cdk-bootstrap@v2`會導致 動作在 [2024 年 3 月映像](build-images.md#build.default-image)上執行，其中包括較新的工具，例如 Node.js 18。指定 `aws/cdk-bootstrap@v1`會導致 動作在 [2022 年 11 月映像](build-images.md#build.previous-image)上執行，其中包含舊版工具，例如 Node.js 16。
預設：`aws/cdk-bootstrap@v2`。
對應的 UI：工作流程圖表/CDKBootstrapAction\$1nn/**aws/cdk-bootstrap@v2** 標籤
## DependsOn
(*CDKBootstrapAction*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*CDKBootstrapAction*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*CDKBootstrapAction*/Compute/**Type**)
（如果[Compute](#cdk.boot.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
針對動作執行期間的彈性進行最佳化。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/進階 - 選用/**運算類型**
## Fleet
(*CDKBootstrapAction*/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`。
對應的 UI：組態索引標籤/進階 - 選用/**運算機群**
## Timeout
(*CDKBootstrapAction*/**Timeout**)
(必要)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Inputs
(*CDKBootstrapAction*/**Inputs**)
(選用)
`Inputs` 區段定義在工作流程執行期間**AWS CDK 引導**操作所需的資料。
對應的 UI：**輸入**索引標籤
**注意**
每個**AWS CDK 引導**操作只允許一個輸入 （來源或成品）。
## Sources
(*CDKBootstrapAction*/Inputs/**Sources**)
（如果您 AWS CDK 的應用程式存放在來源儲存庫中，則為必要項目）
如果您的 AWS CDK 應用程式存放在來源儲存庫中，請指定該來源儲存庫的標籤。**AWS CDK 引導**操作會在啟動引導程序之前，在此儲存庫中合成應用程式。目前，唯一支援的儲存庫標籤是 `WorkflowSource`。
如果您的 AWS CDK 應用程式不包含在來源儲存庫中，則必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*CDKBootstrapAction*/Inputs/**Artifacts**)
（如果您 AWS CDK 的應用程式存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要）
如果您的 AWS CDK 應用程式包含在先前動作產生的成品中，請在此處指定該成品。**AWS CDK 引導**操作會在啟動引導程序之前，將指定成品中的應用程式合成為 CloudFormation 範本。如果您的 AWS CDK 應用程式不包含在成品中，它必須位於您的來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸入索引標籤/**文章 - 選用**
## Outputs
(*CDKBootstrapAction*/**Outputs**)
(選用)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts - output
(*CDKBootstrapAction*/Outputs/**Artifacts**)
(選用)
指定 動作產生的成品。您可以在其他動作中參考這些成品做為輸入。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/**成品**
## Name
(*CDKBootstrapAction*/Outputs/Artifacts/**Name**)
（如果[Artifacts - output](#cdk.boot.outputs.artifacts)包含 則為必要）
指定成品的名稱，該成品將包含由**AWS CDK 引導**操作在執行時間合成的 CloudFormation 範本。預設值為 `cdk_bootstrap_artifacts`。如果您未指定成品，則動作會合成範本，但不會將其儲存在成品中。考慮將合成的範本儲存在成品中，以保留記錄以供測試或故障診斷之用。
對應的 UI：輸出tab/Artifacts/Add成品/**建置成品名稱**
## Files
(*CDKBootstrapAction*/Outputs/Artifacts/**Files**)
（如果[Artifacts - output](#cdk.boot.outputs.artifacts)包含 則為必要）
指定要包含在成品中的檔案。您必須指定 `"cdk.out/**/*"`以包含 AWS CDK 應用程式的合成 CloudFormation 範本。
**注意**
`cdk.out` 是將合成檔案儲存到其中的預設目錄。如果您在 `cdk.json` 檔案中指定 `cdk.out`以外的輸出目錄，請在此處指定該目錄，而非 `cdk.out`。
對應的 UI：輸出tab/Artifacts/Add**建置產生的成品/檔案**
## Environment
(*CDKBootstrapAction*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*CDKBootstrapAction*/Environment/**Name**)
（如果[Environment](#cdk.boot.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*CDKBootstrapAction*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*CDKBootstrapAction*/Environment/Connections/**Name**)
（如果[Connections](#cdk.boot.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*CDKBootstrapAction*/Environment/Connections/**Role**)
（如果[Connections](#cdk.boot.environment.connections)包含 則為必要）
指定**AWS CDK 引導**操作用來存取 AWS 和新增引導堆疊的 IAM 角色名稱。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有適當的政策。
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Configuration
(*CDKBootstrapAction*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## Region
(*CDKBootstrapAction*/Configuration/**Region**)
(必要)
指定要部署引導堆疊的 AWS 區域 。此區域應與您的 AWS CDK 應用程式部署所在的區域相符。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)。
對應的 UI：組態索引標籤/**區域**
## CdkCliVersion
(*CDKBootstrapAction*/Configuration/**CdkCliVersion**)
(選用)
此屬性適用於 1.0.13 版或更新版本的**AWS CDK 部署**動作，以及 1.0.8 版或更新版本的**AWS CDK 引導**動作。
請指定下列其中一項：
+ 您希望此動作使用的 AWS Cloud Development Kit (AWS CDK) 命令列界面 (CLI) 完整版本 （也稱為 AWS CDK Toolkit)。範例：`2.102.1`。請考慮指定完整版本，以確保建置和部署應用程式時的一致性和穩定性。
或
+ `latest`。 考慮指定 `latest`以利用 CDK CLI 的最新功能和修正。
動作會將指定的 CLI AWS CDK 版本 （或最新版本） 下載至 CodeCatalyst [建置映像](build-images.md)，然後使用此版本來執行部署 CDK 應用程式或引導環境 AWS 所需的命令。
如需您可以使用的支援 CDK CLI 版本清單，請參閱[AWS CDK 版本](https://docs.aws.amazon.com/cdk/api/versions.html)。
如果您省略此屬性，動作會使用下列其中一個主題所述的預設 AWS CDK CLI 版本：
+ [「AWS CDK 部署」動作使用的 CDK CLI 版本](cdk-dep-action.md#cdk-dep-action-cdk-version)
+ ["AWS CDK bootstrap" 動作使用的 CDK CLI 版本](cdk-boot-action.md#cdk-boot-action-cdk-version)
對應的 UI：組態索引標籤/**AWS CDK CLI 版本**
# 使用工作流程將檔案發佈至 Amazon S3
本節說明如何使用 CodeCatalyst 工作流程將檔案發佈至 Amazon S3。若要達成此目的，您必須將 **Amazon S3 發佈**動作新增至工作流程。**Amazon S3 發佈**動作會將檔案從來源目錄複製到 Amazon S3 儲存貯體。來源目錄可以位於：
+ [來源儲存庫](source.md)，或
+ 另一個工作流程動作產生的[輸出成品](workflows-working-artifacts.md)
**Topics**
+ [何時使用 'Amazon S3 發佈' 動作](#s3-pub-action-when-to-use)
+ [「Amazon S3 發佈」動作使用的執行期映像](#s3-pub-action-runtime)
+ [範例：將檔案發佈至 Amazon S3](s3-pub-action-example-workflow.md)
+ [新增「Amazon S3 發佈」動作](s3-pub-action-add.md)
+ [「Amazon S3 發佈」動作 YAML](s3-pub-action-ref.md)
## 何時使用 'Amazon S3 發佈' 動作
在以下情況下使用此動作：
+ 您的工作流程會產生要存放在 Amazon S3 中的檔案。
例如，您可能有一個工作流程，其會建置您想要在 Amazon S3 中託管的靜態網站。在這種情況下，您的工作流程將包括建置網站 HTML 和支援檔案的[建置動作](build-add-action.md)，以及將檔案複製到 **Amazon S3 的 Amazon S3 發佈**動作。 Amazon S3
+ 您有一個來源儲存庫，其中包含要存放在 Amazon S3 中的檔案。
例如，您可能有一個來源儲存庫，其中包含您想要在夜間封存至 Amazon S3 的應用程式來源檔案。
## 「Amazon S3 發佈」動作使用的執行期映像
**Amazon S3 發佈**動作會在 [2022 年 11 月的映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 範例：將檔案發佈至 Amazon S3
下列範例工作流程包含 **Amazon S3 發佈**動作，以及建置動作。工作流程會建置靜態文件網站，然後將其發佈至託管的 Amazon S3。工作流程包含下列依順序執行的建置區塊：
+ **觸發**條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **建置**動作 (`BuildDocs`) – 在觸發時，動作會建置靜態文件網站 (`mkdocs build`)，並將相關聯的 HTML 檔案和支援中繼資料新增至名為 的成品`MyDocsSite`。如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ **Amazon S3 發佈**動作 (`PublishToS3`) – 建置動作完成後，此動作會將`MyDocsSite`成品中的網站複製到 Amazon S3 進行託管。
**注意**
下列工作流程範例僅供說明之用，如果沒有其他組態，將無法運作。
**注意**
在後續的 YAML 程式碼中，您可以視需要省略 `Connections:`區段。如果您省略本節，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含 **Amazon S3 發佈**動作所需的許可和信任政策。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。如需 **Amazon S3 發佈**動作所需許可和信任政策的詳細資訊，請參閱 中的 [Role](s3-pub-action-ref.md#s3.pub.environment.connections.role) 屬性描述[「Amazon S3 發佈」動作 YAML](s3-pub-action-ref.md)。
```
Name: codecatalyst-s3-publish-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
BuildDocs:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: echo BuildDocs started on `date`
- Run: pip install --upgrade pip
- Run: pip install mkdocs
- Run: mkdocs build
- Run: echo BuildDocs completed on `date`
Outputs:
Artifacts:
- Name: MyDocsSite
Files:
- "site/**/*"
PublishToS3:
Identifier: aws/s3-publish@v1
Environment:
Name: codecatalyst-s3-publish-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-s3-publish-build-role
Inputs:
Sources:
- WorkflowSource
Artifacts:
- MyDocsSite
Configuration:
DestinationBucketName: amzn-s3-demo-bucket
SourcePath: /artifacts/PublishToS3/MyDocSite/site
TargetPath: my/docs/site
```
# 新增「Amazon S3 發佈」動作
使用下列指示將 **Amazon S3 發佈**動作新增至您的工作流程。
------
#### [ Visual ]
**使用視覺化編輯器新增「Amazon S3 發佈」動作**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中選擇 **Amazon CodeCatalyst**。
1. 搜尋 **Amazon S3 發佈**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 **Amazon S3 發佈**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**、**組態**和**輸出**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「Amazon S3 發佈」動作 YAML](s3-pub-action-ref.md)。此參考提供每個欄位 （和對應的 YAML 屬性值） 的詳細資訊，如 YAML 和視覺化編輯器所示。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增「Amazon S3 發佈」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋 **Amazon S3 發佈**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 **Amazon S3 發佈**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「Amazon S3 發佈」動作 YAML](s3-pub-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 「Amazon S3 發佈」動作 YAML
以下是 **Amazon S3 發佈**動作的 YAML 定義。若要了解如何使用此動作，請參閱 [使用工作流程將檔案發佈至 Amazon S3](s3-pub-action.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
S3Publish\$1nn:
Identifier: aws/s3-publish@v1
DependsOn:
- build-action
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Inputs:
Sources:
- source-name-1
Artifacts:
- artifact-name
Variables:
- Name: variable-name-1
Value: variable-value-1
- Name: variable-name-2
Value: variable-value-2
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Configuration:
SourcePath: my/source
DestinationBucketName: amzn-s3-demo-bucket
TargetPath: my/target
```
## S3Publish
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
預設：`S3Publish_nn`。
對應的 UI：組態索引標籤/**動作名稱**
## Identifier
(*S3Publish*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/s3-publish@v1`。
對應的 UI：工作流程圖表/S3Publish\$1nn/**aws/s3-publish@v1** 標籤
## DependsOn
(*S3Publish*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*S3Publish*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在相同的執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*S3Publish*/Compute/**Type**)
（如果[Compute](#s3.pub.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/**運算類型**
## Fleet
(*S3Publish*/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`。
對應的 UI：組態索引標籤/**運算機群**
## Timeout
(*S3Publish*/**Timeout**)
(必要)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Inputs
(*S3Publish*/**Inputs**)
(選用)
`Inputs` 區段定義工作流程執行期間 `S3Publish`所需的資料。
**注意**
每個**AWS CDK 部署**動作最多允許四個輸入 （一個來源和三個成品）。變數不會計入此總計。
如果您需要參考位於不同輸入中的檔案 （例如來源和成品），則來源輸入是主要輸入，而成品是次要輸入。對次要輸入中檔案的參考需要特殊的字首，才能將其從主要輸入中消除。如需詳細資訊，請參閱[範例：參考多個成品中的檔案](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file)。
對應的 UI：**輸入**索引標籤
## Sources
(*S3Publish*/Inputs/**Sources**)
（如果您要發佈至 Amazon S3 的檔案存放在來源儲存庫中，則為必要項目）
如果您要發佈至 Amazon S3 的檔案存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您想要發佈至 Amazon S3 的檔案不包含在來源儲存庫中，它們必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*S3Publish*/Inputs/**Artifacts**)
（如果您要發佈至 Amazon S3 的檔案存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要項目）
如果您想要發佈至 Amazon S3 的檔案包含在先前動作產生的成品中，請在此處指定該成品。如果您的檔案不包含在成品中，它們必須位於您的來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**成品 - 選用**
## Variables - input
(*S3Publish*/Inputs/**Variables**)
(選用)
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸入索引標籤/**變數 - 選用**
## Environment
(*S3Publish*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*S3Publish*/Environment/**Name**)
（如果[Environment](#s3.pub.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*S3Publish*/Environment/**Connections**)
（動作的較新版本為選用；較舊版本為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*S3Publish*/Environment/Connections/**Name**)
（如果[Connections](#s3.pub.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*S3Publish*/Environment/Connections/**Role**)
（如果[Connections](#s3.pub.environment.connections)包含 則為必要）
指定 **Amazon S3 發佈**動作用來存取 AWS 和複製檔案至 Amazon S3 的 IAM 角色名稱。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:ListBucket",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::bucket-name",
"arn:aws:s3:::bucket-name/*"
]
}
]
}
```
------
+ 下列自訂信任政策：
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Configuration
(*S3Publish*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## SourcePath
(*S3Publish*/Configuration/**SourcePath**)
(必要)
指定您要發佈至 Amazon S3 的目錄或檔案的名稱和路徑。目錄或檔案可以位於來源儲存庫或先前動作的成品中，並與來源儲存庫或成品根相關。
範例：
指定 會將 的內容`./myFolder/`複製到 `/myFolder` Amazon S3，並保留基礎目錄結構。
*僅*`myfile.txt`指定`./myFolder/myfile.txt`複本至 Amazon S3。（目錄結構已移除。)
您無法使用萬用字元。
**注意**
您可能需要將字首新增至目錄或檔案路徑，以指出要在其中找到的成品或來源。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)及[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：組態索引標籤/**來源路徑**
## DestinationBucketName
(*S3Publish*/Configuration/**DestinationBucketName**)
(必要)
指定您要發佈檔案的 Amazon S3 儲存貯體名稱。
對應的 UI：組態索引標籤/**目的地儲存貯體 - 選用**
## TargetPath
(*S3Publish*/Configuration/**TargetPath**)
(選用)
在 Amazon S3 中指定您要發佈檔案的目錄名稱和路徑。如果目錄不存在，則會建立該目錄。目錄路徑不得包含儲存貯體名稱。
範例：
`myS3Folder`
`./myS3Folder/myS3Subfolder`
對應的 UI：組態索引標籤/**目的地目錄 - 選用**
# 部署至 AWS 帳戶 和 VPCs
使用 [CodeCatalyst 工作流程](workflow.md)，您可以部署應用程式和其他資源以鎖定 AWS 雲端中的 AWS 帳戶和 Amazon VPCs。若要啟用這些部署，您必須設定 CodeCatalyst 環境。
CodeCatalyst *環境*，不與[開發環境](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html)混淆，定義 CodeCatalyst [工作流程](workflow.md)連線的目標 AWS 帳戶 和選用 Amazon VPC。環境也會定義工作流程存取目標帳戶中 AWS 的服務和資源所需的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
您可以設定多個環境並為其命名，例如開發、測試、預備和生產等名稱。當您部署到這些環境中時，有關部署的資訊會顯示於環境中的 CodeCatalyst **部署活動**和**部署目標**標籤上。
## 如何開始使用環境？
新增和使用 CodeCatalyst 環境的高階步驟如下：
1. 在您的 CodeCatalyst 空間中，**連接一或多個 AWS 帳戶**。在此程序中，新增工作流程存取 中資源所需的 IAM 角色 AWS 帳戶。如需詳細資訊，請參閱[允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。
1. 在 CodeCatalyst 專案中，**建立包含步驟 1 中其中一個 和 IAM 角色的環境**。 AWS 帳戶如需詳細資訊，請參閱[建立環境](deploy-environments-creating-environment.md)。
1. 在 CodeCatalyst 專案的工作流程中，**新增指向您在步驟 2 中所建立環境[的動作](workflows-actions.md)**。如需詳細資訊，請參閱[將動作新增至工作流程](workflows-add-action.md)。
您現在已設定環境。動作現在可以將資源部署到環境中 AWS 帳戶 指定的 。
**注意**
您也可以將 Amazon VPC 新增至環境。如需詳細資訊，請參閱 *CodeCatalyst 管理指南*中的[新增空間的 VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)和 [將 VPC 與環境建立關聯](deploy-environments-associate-vpc.md)。
## 單一工作流程中可以存在多個環境嗎？
是。如果工作流程包含多個動作，則可以為每個動作指派一個環境。例如，您可以有一個工作流程，其中包含兩個部署動作，其中一個指派`my-staging-enviroment`環境，另一個指派`my-production-environment`環境。
## 哪些工作流程動作支援環境？
將資源部署到 AWS 雲端，或基於其他原因 （例如監控和報告） 與 AWS 服務通訊的任何工作流程動作都支援環境。
## 哪些動作支援在 CodeCatalyst 中顯示其部署資訊？
在支援環境的工作流程動作中，只有少數支援將其部署資訊顯示在 CodeCatalyst 主控台的**部署活動**和**部署目標**頁面上。
下列工作流程動作支援顯示其部署資訊：
+ **部署 CloudFormation 堆疊** – 如需詳細資訊，請參閱 [部署 CloudFormation 堆疊](deploy-action-cfn.md)
+ **部署至 Amazon ECS** – 如需詳細資訊，請參閱 [使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)
+ **部署至 Kubernetes 叢集** – 如需詳細資訊，請參閱 [使用工作流程部署至 Amazon EKS](deploy-action-eks.md)
+ **AWS CDK 部署** – 如需詳細資訊，請參閱 [使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)
## 支援的區域
**環境**頁面可以顯示任何 AWS 區域中的資源。
## 環境是強制性的嗎？
如果獲指派的工作流程動作將資源部署到 AWS 雲端，或基於其他原因 （例如監控和報告） 與 AWS 服務通訊，則環境為強制性。
例如，如果您有一個建置動作來建置應用程式，但不需要與您的 AWS 帳戶 或 Amazon VPC 通訊，則不需要將環境指派給動作。不過，如果建置動作將日誌傳送至 中的 Amazon CloudWatch 服務 AWS 帳戶，則動作必須指派環境。
**Topics**
+ [如何開始使用環境？](#deploy-environments-get-started)
+ [單一工作流程中可以存在多個環境嗎？](#deploy-environments-multiple)
+ [哪些工作流程動作支援環境？](#deploy-environments-supported)
+ [哪些動作支援在 CodeCatalyst 中顯示其部署資訊？](#deploy-environments-supported-targets)
+ [支援的區域](#deploy-environments-supported-regions)
+ [環境是強制性的嗎？](#deploy-environments-optional-or-mandatory)
+ [建立環境](deploy-environments-creating-environment.md)
+ [將環境與 動作建立關聯](deploy-environments-add-app-to-environment.md)
+ [將 VPC 與環境建立關聯](deploy-environments-associate-vpc.md)
+ [將 AWS 帳戶 與 環境建立關聯](deploy-environments-associate-account.md)
+ [變更 動作的 IAM 角色](deploy-environments-switch-role.md)
# 建立環境
使用以下指示來建立您稍後可以與工作流程動作建立關聯的環境。
**開始之前**
您需要下列項目：
+ CodeCatalyst 空間。如需詳細資訊，請參閱[設定並登入 CodeCatalyst設定並登入 CodeCatalyst](setting-up-topnode.md)。
+ CodeCatalyst 專案。如需詳細資訊，請參閱[使用藍圖建立專案](projects-create.md#projects-create-console-template)。
+ AWS 帳戶連線，其中包含工作流程動作需要存取的 IAM 角色 AWS。如需建立帳戶連線的資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。每個環境最多只能使用一個帳戶連線。
**注意**
您可以建立沒有帳戶連線的環境；不過，稍後需要返回並新增連線。
+ 下列其中一個 CodeCatalyst 角色：
+ **空間管理員**
+ **專案管理員**
+ **Contributor (作者群)**
**注意**
如果您有 **Contributor 角色**，您可以建立環境，但無法將其與 AWS 帳戶 連線建立關聯。您需要要求具有 **Space 管理員**或**專案管理員**角色的人員將環境與 AWS 帳戶 連線建立關聯。
如需許可和角色的詳細資訊，請參閱 [授予使用者專案許可](projects-members.md)。
**建立環境**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 在**環境名稱**中，輸入名稱，例如 **Production**或 **Staging**。
1. 在**環境類型**中，選取下列其中一項：
+ **非生產** – 在將應用程式移至生產環境之前，您可以測試應用程式以確保其如預期般運作的環境。
+ **生產** – 可公開取得並託管您完成之應用程式的「即時」環境。
如果您選擇**生產**，**生產**徽章會顯示在 UI 中與環境相關聯的任何動作旁。徽章有助於您快速查看目前哪些動作正在部署到生產中。除了徽章的外觀之外，生產環境和非生產環境之間沒有差異。
1. （選用） 在**描述**中，輸入描述，例如 **Production environment for the hello-world app**。
1. 在**AWS 帳戶 連線中 - 選用**，選擇您要與此環境建立關聯的 AWS 帳戶連線。指派給此環境的工作流程動作將能夠連線至相關聯的 AWS 帳戶。如需在 CodeCatalyst 中建立 AWS 帳戶 連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。
如果您想要使用的 AWS 帳戶 連線未列出，可能是因為您的專案中不允許。如需詳細資訊，請參閱《*Amazon CodeCatalyst 管理員指南*》中的[設定專案限制帳戶連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
1. 在**預設 IAM 角色**中，選擇您要與此環境建立關聯的 IAM 角色。指派給此環境的工作流程動作會繼承此 IAM 角色，並能夠用來連線到 中的 服務和資源 AWS 帳戶。
如果您需要將環境指派給多個動作，而且這些動作需要與此處指定的預設角色不同的 IAM 角色，則可以使用切換角色選項，在每個動作的**組態**索引標籤上指定不同的角色。 ****如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如果您想要用作預設值的 IAM 角色未列出，可能是因為您尚未將其新增至 AWS 帳戶 連線。若要將 IAM 角色新增至帳戶連線，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
1. （選用） 在 **VPC 連線**中，選擇您要與此環境建立關聯的 VPC 連線。如需建立 VPC 連線的詳細資訊，請參閱[《Amazon CodeCatalyst 管理員指南》中的管理 Amazon Virtual Private Clouds](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html)。 * CodeCatalyst *
如果您想要使用的 VPC 連線未列出，可能是因為其中包含專案中不允許的 AWS 帳戶 連線。如需詳細資訊，請參閱《*Amazon CodeCatalyst 管理員指南*》中的[設定專案限制帳戶連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
1. 選擇 **Create environment** (建立環境)。CodeCatalyst 會建立空的環境。
**後續步驟**
+ 現在您已建立環境，即可將其與工作流程動作建立關聯。如需詳細資訊，請參閱[將環境與 動作建立關聯](deploy-environments-add-app-to-environment.md)。
# 將環境與 動作建立關聯
當您將環境與[支援的工作流程動作](deploy-environments.md#deploy-environments-supported)建立關聯時，環境的預設 AWS 帳戶 IAM 角色和選用的 Amazon VPC 會指派給動作。然後， 動作可以使用 IAM 角色來連接和部署到 AWS 帳戶 ，也可以連接到選用的 Amazon VPC。
使用以下指示，將環境與 動作建立關聯。
## 步驟 1：將環境與工作流程動作建立關聯
使用下列程序將環境與工作流程動作建立關聯。
------
#### [ Visual ]
**使用視覺化編輯器將環境與工作流程動作建立關聯**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇環境支援的動作。如需詳細資訊，請參閱[哪些動作支援在 CodeCatalyst 中顯示其部署資訊？](deploy-environments.md#deploy-environments-supported-targets)。
1. 選擇**組態**索引標籤，然後在**環境**欄位中指定資訊，如下所示。
**Environment (環境)**
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將 動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
1. （選用） 變更與動作相關聯的 IAM 角色。如果角色包含動作的錯誤許可集，您可能想要變更角色。
若要變更角色：
1. 在***我的環境中*是什麼？** 方塊，然後選擇垂直省略符號圖示 (![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/elipsis.png))。
1. 選擇下列其中一項：
+ **切換角色**。選擇此選項可變更此動作所使用的 IAM 角色，且僅變更此動作。其他動作會繼續使用其相關聯環境中指定的預設 IAM 角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
+ **編輯環境**。選擇此選項可變更您環境中列出的預設 IAM 角色。當您選擇此選項時，您的動作以及與相同環境相關聯的任何其他動作都會開始使用新的預設 IAM 角色。
**重要**
更新預設 IAM 角色時請小心。如果角色中的許可不足以用於共用環境的所有動作，變更角色可能會導致動作失敗。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器將環境與工作流程動作建立關聯**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在您要與環境建立關聯的工作流程動作中，新增類似下列的程式碼：
```
action-name:
Environment:
Name: environment-name
```
如需詳細資訊，請參閱 [動作類型](workflows-actions.md#workflows-actions-types)主題。本主題包含每個動作的文件連結，包括其 YAML 參考。
1. （選用） 如果您想要動作使用與環境中列出的預設 IAM 角色不同的角色，請新增包含您要使用之角色的`Connections:`區段。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 步驟 2：填入部署活動頁面
將環境與工作流程動作建立關聯後，您可以在 CodeCatalyst 主控台**的環境**區段中，將部署資訊填入部署**活動**和部署**目標**頁面。使用下列指示來填入這些頁面。
**注意**
只有幾個動作支援在 CodeCatalyst 主控台中顯示其部署資訊。如需詳細資訊，請參閱[哪些動作支援在 CodeCatalyst 中顯示其部署資訊？](deploy-environments.md#deploy-environments-supported-targets)。
**將部署資訊新增至 CodeCatalyst**
1. 如果您在 中遞交變更時，工作流程執行未自動啟動[步驟 1：將環境與工作流程動作建立關聯](#deploy-environments-add-app-to-environment-assoc)，請手動啟動執行，如下所示：
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**執行**。
工作流程執行會啟動新的部署，這會導致 CodeCatalyst 將部署資訊新增至 CodeCatalyst。
1. 確認部署活動已新增至 CodeCatalyst 主控台：
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇您的環境 （例如 `Production`)。
1. 選擇**部署活動**索引標籤，並確認部署顯示為 **SUCCEEDED** **狀態**。這表示工作流程執行成功部署您的應用程式資源。
1. 選擇**部署目標**索引標籤，並確認您的應用程式資源是否出現。
# 將 VPC 與環境建立關聯
使用具有 VPC 連線的環境設定動作時，該動作將執行連線至 VPC，遵守網路規則並存取相關聯 VPC 指定的資源。一個或多個環境可以使用相同的 VPC 連線。
使用下列指示將 VPC 連線與 環境建立關聯。
**將 VPC 連線與環境建立關聯**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇您的環境 （例如 `Production`)。
1. 選擇**環境屬性**索引標籤。
1. 選擇**管理 VPC 連線**，選擇所需的 VPC 連線，然後選擇**確認**。這會將您選取的 VPC 連線與此環境建立關聯。
**注意**
如果您想要使用的 VPC 連線未列出，可能是因為其中包含專案中不允許的 AWS 帳戶 連線。如需詳細資訊，請參閱《*Amazon CodeCatalyst 管理員指南*》中的[設定專案限制帳戶連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
如需詳細資訊，請參閱 *CodeCatalyst 管理員指南*中的[管理 Amazon Virtual Private Cloud](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html)。
# 將 AWS 帳戶 與 環境建立關聯
使用以下指示，將 AWS 帳戶 與 環境建立關聯。當您將 AWS 帳戶 與 環境建立關聯時，指派給環境的工作流程動作將能夠連線到 AWS 帳戶。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。
**開始之前**
您需要下列項目：
+ AWS 帳戶連線，其中包含工作流程動作需要存取的 IAM 角色 AWS。如需建立帳戶連線的資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。每個環境最多只能使用一個帳戶連線。
+ 下列其中一個 CodeCatalyst 角色：**空間管理員**或**專案管理員**。如需詳細資訊，請參閱[授予使用者專案許可](projects-members.md)。
**將 AWS 帳戶 與 環境建立關聯**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇您的環境 （例如 `Production`)。
1. 選擇**編輯環境**。
1. 在**環境屬性**下，於**AWS 帳戶 連線 - 選用**下拉式清單中，選擇所需的 AWS 帳戶。
如果您想要使用的 AWS 帳戶 連線未列出，可能是因為您的專案中不允許。如需詳細資訊，請參閱《*Amazon CodeCatalyst 管理員指南*》中的[設定專案限制帳戶連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
1. 在**預設 IAM 角色**中，選擇您要與此環境建立關聯的 IAM 角色。指派給此環境的工作流程動作會繼承此 IAM 角色，並能夠用來連線至 中的 服務和資源 AWS 帳戶。
如果您想要用作預設值的 IAM 角色未列出，可能是因為您尚未將其新增至 AWS 帳戶 連線。若要將 IAM 角色新增至帳戶連線，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
# 變更 動作的 IAM 角色
根據預設，當您將[環境](deploy-environments.md)與工作流程[動作](workflows-actions.md)建立關聯時，動作會繼承環境中指定的預設 IAM 角色。您可以變更此行為，讓動作使用不同的角色。如果預設 IAM 角色缺少動作在 AWS 雲端中操作所需的許可，您可能會希望動作使用不同的角色。
若要將不同的 IAM 角色指派給動作，您可以在視覺化編輯器中使用**切換角色**選項，或在 YAML 編輯器中使用 `Connections:` 屬性。新角色會覆寫環境中指定的預設 IAM 角色，讓您將預設 IAM 角色保持原狀。如果有其他動作使用預設 IAM 角色，建議您保持原狀。
使用下列指示來設定 動作，以使用與其環境中指定的 IAM 角色不同的 IAM 角色。
------
#### [ Visual ]
**將不同的 IAM 角色指派給動作 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇代表您要更新其 IAM 角色之動作的方塊。
1. 選擇 **Configuration** (組態) 索引標籤。
1. 在***我的環境中*是什麼？** 方塊，選擇垂直省略號圖示 (![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/elipsis.png))。
1. 選擇**切換角色**。
1. 在**切換角色**對話方塊中的 **IAM 角色**下拉式清單中，選擇您要動作使用的 IAM 角色。此角色會覆寫環境中的預設 IAM 角色。如果您想要使用的角色不在清單中，請確定您已將其新增至您的空間。如需詳細資訊，請參閱[新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
所選角色現在會出現在***我的環境中*的內容中？** 方塊，以及**工作流程徽章中定義的** 。該角色也會出現在 `Connections:`區段的工作流程定義檔案中。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**將不同的 IAM 角色指派給動作 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在您想要使用不同 IAM 角色的工作流程動作中，新增 `Connections:`區段，如下所示：
```
action-name:
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
```
在上述程式碼中，將 *account-connection-name* 取代為包含 IAM 角色[的帳戶連線](ipa-connect-account.md)名稱，並將 *iam-role-name* 取代為您希望動作使用的 IAM 角色名稱。此角色會覆寫環境中的預設 IAM 角色。請確定您已將 角色新增至您的空間。如需詳細資訊，請參閱[新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
如需詳細資訊，請參閱 [動作類型](workflows-actions.md#workflows-actions-types)主題。本主題包含每個動作的文件連結，包括其 YAML 參考。
------
# 在工作流程圖表中顯示應用程式 URL
如果您的工作流程部署應用程式，您可以設定 Amazon CodeCatalyst，將應用程式的 URL 顯示為可點選的連結。此連結會出現在 CodeCatalyst 主控台的部署動作內。下列工作流程圖表顯示出現在動作底部的**檢視應用程式** URL。
![\[檢視應用程式 URL\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/deploy/view-app-url.png)
透過在 CodeCatalyst 主控台中啟用此 URL，您可以快速驗證應用程式部署。
**注意**
**部署至 Amazon ECS **動作不支援應用程式 URL。
若要啟用此功能，請使用包含 `appurl`或 的名稱，將輸出變數新增至您的動作`endpointurl`。您可以使用有或沒有聯結破折號 (`-`)、底線 (`_`) 或空格 () 的名稱` `。字串不區分大小寫。將變數的值設定為已部署應用程式的 `http`或 `https` URL。
**注意**
如果您要更新現有的輸出變數以包含 `app url`或 `endpoint url`字串，請更新此變數的所有參考，以使用新的變數名稱。
如需詳細步驟，請參閱下列其中一個程序：
+ [在「AWS CDK 部署」動作中顯示應用程式 URL](#deploy-app-url-cdk)
+ [在「部署 CloudFormation 堆疊」動作中顯示應用程式 URL](#deploy-app-url-cfn)
+ [在所有其他動作中顯示應用程式 URL](#deploy-app-url-other)
當您完成設定 URL 後，請依照下列指示確認 URL 是否如預期顯示：
+ [驗證已新增應用程式 URL](#deploy-app-url-verify)
**在「AWS CDK 部署」動作中顯示應用程式 URL**
1. 如果您使用的是**AWS CDK 部署**動作，請在 AWS CDK 應用程式程式碼中新增建構 `CfnOutput` （即索引鍵/值對）：
+ 索引鍵名稱必須包含 `appurl`、 或 `endpointurl`，包含或不包含聯結破折號 (`-`)、底線 (`_`) 或空格 ()` `。字串不區分大小寫。
+ 值必須是已部署應用程式的 `http`或 `https` URL。
例如，您的 AWS CDK 程式碼可能如下所示：
```
import { Duration, Stack, StackProps, CfnOutput, RemovalPolicy} from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
export class HelloCdkStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: RemovalPolicy.DESTROY,
});
new CfnOutput(this, 'APP-URL', {
value: https://mycompany.myapp.com,
description: 'The URL of the deployed application',
exportName: 'myApp',
});
...
}
}
```
如需建構模組的詳細資訊，請參閱 API `CfnOutput` 參考中的[界面 CfnOutputProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutputProps.html)。 *AWS Cloud Development Kit (AWS CDK) *
1. 儲存並遞交您的程式碼。
1. 繼續執行「[驗證已新增應用程式 URL](#deploy-app-url-verify)」。
**在「部署 CloudFormation 堆疊」動作中顯示應用程式 URL**
1. 如果您使用的是**部署 CloudFormation 堆疊**動作，請將輸出新增至 CloudFormation 範本或 AWS SAM 範本中具有下列特性的 `Outputs`區段：
+ 金鑰 （也稱為邏輯 ID) 必須包含 `appurl`、 或 `endpointurl`，包含或不包含聯結破折號 (`-`)、底線 (`_`) 或空格 ()` `。字串不區分大小寫。
+ 值必須是已部署應用程式的 `http`或 `https` URL。
例如，您的 CloudFormation 範本可能如下所示：
```
"Outputs" : {
"APP-URL" : {
"Description" : "The URL of the deployed app",
"Value" : "https://mycompany.myapp.com",
"Export" : {
"Name" : "My App"
}
}
}
```
如需 CloudFormation 輸出的詳細資訊，請參閱*AWS CloudFormation *[《 使用者指南》中的輸出](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html)。
1. 儲存並遞交您的程式碼。
1. 繼續執行「[驗證已新增應用程式 URL](#deploy-app-url-verify)」。
**在所有其他動作中顯示應用程式 URL**
如果您使用另一個動作來部署應用程式，例如建置動作或 **GitHub 動作**，請執行下列動作以顯示應用程式 URL。
1. 在工作流程定義檔案中 動作的 `Inputs`或 `Steps`區段中定義環境變數。變數必須具有下列特性：
+ `name` 必須包含 `appurl`、 或 `endpointurl`，包含或不包含聯結破折號 (`-`)、底線 (`_`) 或空格 ()` `。字串不區分大小寫。
+ 值必須是已部署應用程式的 `http`或 `https` URL。
例如，建置動作可能如下所示：
```
Build-action:
Identifier: aws/build@v1
Inputs:
Variables:
- Name: APP-URL
Value: https://mycompany.myapp.com
```
...或此項目：
```
Actions:
Build:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: APP-URL=https://mycompany.myapp.com
```
如需定義環境變數的詳細資訊，請參閱 [定義變數](workflows-working-with-variables-define-input.md)。
1. 匯出 變數。
例如，您的建置動作可能如下所示：
```
Build-action:
...
Outputs:
Variables:
- APP-URL
```
如需匯出變數的詳細資訊，請參閱 [匯出變數，讓其他動作可以使用它](workflows-working-with-variables-export-input.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
1. 繼續執行「[驗證已新增應用程式 URL](#deploy-app-url-verify)」。
**驗證已新增應用程式 URL**
+ 如果工作流程尚未自動啟動，請啟動工作流程執行。新執行應該在其工作流程圖表中將應用程式 URL 顯示為可點選連結。如需啟動執行的詳細資訊，請參閱 [手動啟動工作流程執行](workflows-manually-start.md)。
# 移除部署目標
您可以從 CodeCatalyst 主控台的部署目標頁面移除**部署目標**，例如 Amazon ECS 叢集或 CloudFormation 堆疊。
**重要**
當您移除部署目標時，該目標會從 CodeCatalyst 主控台中移除，但在託管目標 AWS 的服務中仍然可用 （如果仍然存在）。
如果目標在 CodeCatalyst 中過時，請考慮移除部署目標。在以下情況下，目標可能會過時：
+ 您已刪除部署到目標的工作流程。
+ 您已變更要部署的堆疊或叢集。
+ 您已從 主控台的 CloudFormation 或 Amazon ECS 服務 AWS 中刪除堆疊或叢集。
**移除部署目標**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇包含您要移除之部署目標的環境名稱。如需環境的相關資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
1. 選擇**部署目標**索引標籤。
1. 選擇您要移除之部署目標旁的選項按鈕。
1. 選擇**移除**。
目標會從頁面中移除。
# 依遞交追蹤部署狀態
在開發生命週期的任何時候，請務必了解特定遞交的部署狀態，例如錯誤修正、新功能或其他有影響力的變更。請考慮下列部署狀態追蹤功能對開發團隊有幫助的案例：
+ 身為開發人員，您已修正 以解決錯誤，並想要報告其在團隊部署環境中的部署狀態。
+ 身為發行管理員，您想要檢視已部署遞交的清單，以追蹤和報告其部署狀態。
CodeCatalyst 提供檢視，可讓您快速判斷個別遞交或變更的部署位置，以及部署到哪個環境。此檢視包括：
+ 遞交的清單。
+ 包含遞交的部署狀態。
+ 成功部署遞交的環境。
+ 任何測試的狀態會針對 CI/CD 工作流程中的遞交執行。
下列程序詳細說明如何導覽至 ，並使用此檢視來追蹤專案中的變更。
**注意**
僅 [CodeCatalyst 儲存庫](source.md)支援依遞交追蹤部署狀態。您無法將此功能與 [GitHub 儲存庫、Bitbucket 儲存庫或 GitLab 專案儲存庫](extensions.md)搭配使用。
**依遞交追蹤部署狀態**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**變更追蹤**。
1. 在主窗格頂端的兩個下拉式清單中，選擇包含您要檢視其發行狀態之遞交的來源儲存庫和分支。
1. 選擇**檢視變更**。
遞交清單隨即出現。
對於每個遞交，您可以檢視下列項目：
+ 遞交資訊，例如 ID、作者、訊息以及遞交時間。如需詳細資訊，請參閱[將程式碼與 CodeCatalyst 中的來源儲存庫一起存放和協作儲存程式碼並與來源儲存庫協作](source.md)。
+ 每個環境的部署狀態。如需詳細資訊，請參閱[部署至 AWS 帳戶 和 VPCs](deploy-environments.md)。
+ 測試和程式碼涵蓋範圍結果。如需詳細資訊，請參閱[使用工作流程進行測試使用工作流程進行測試](test-workflow-actions.md)。
**注意**
軟體合成分析 (SCA) 結果不會顯示。
1. （選用） 若要檢視與特定遞交相關的變更的詳細資訊，包括最新的部署和詳細的程式碼涵蓋範圍和單位測試資訊，請選擇**檢視該遞交的詳細資訊**。
# 檢視部署日誌
您可以檢視與特定部署動作相關的日誌，以疑難排解 Amazon CodeCatalyst 中的問題。
您可以檢視從[工作流程](workflow.md)或[環境](deploy-environments.md)開始的日誌。
**從工作流程開始檢視部署動作的日誌**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**執行**。
1. 選擇部署您應用程式的工作流程執行。
1. 在工作流程圖表中，選擇您要檢視其日誌的動作。
1. 選擇**日誌**索引標籤並展開區段，以顯示日誌訊息。
1. 若要檢視更多日誌，請選擇**摘要**索引標籤，然後選擇在 ** CloudFormation 中檢視** （如果有的話） 以檢視更多日誌。您可能需要登入 AWS。
**從 環境開始檢視部署動作的日誌**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇部署應用程式的環境。
1. 在**部署活動中**，尋找**工作流程執行 ID** 欄，然後選擇部署堆疊的工作流程執行。
1. 在工作流程圖表中，選擇您要檢視其日誌的動作。
1. 選擇**日誌**索引標籤並展開區段以顯示日誌訊息。
1. 若要檢視更多日誌，請選擇**摘要**索引標籤，然後選擇 ** CloudFormation 中的檢視** （如果有的話） 來檢視更多日誌。您可能需要登入 AWS。
# 檢視部署資訊
您可以在 Amazon CodeCatalyst 中檢視部署的下列相關資訊：
+ 部署活動，包括部署狀態、開始時間、結束時間、歷史記錄和事件持續時間。
+ 堆疊名稱 AWS 區域、上次更新時間和相關聯的工作流程。
+ 遞交和提取請求。
+ 動作特定資訊，例如 CloudFormation 事件和輸出。
您可以檢視從[工作流程](workflow.md)、[環境](deploy-environments.md)或工作流程[動作](workflows-concepts.md#workflows-concepts-actions)開始的部署資訊。
**從工作流程開始檢視部署資訊**
+ 前往部署您應用程式的工作流程執行。如需說明，請參閱[檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
**從 環境開始檢視部署資訊**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**環境**。
1. 選擇部署堆疊的環境，例如 `Production`。
1. 選擇**部署活動**以檢視堆疊的部署歷史記錄、部署狀態 （例如 **SUCCEEDED **或 **FAILED**)，以及其他部署相關資訊。
1. 選擇**部署目標**以檢視部署到環境中的堆疊、叢集或其他目標的相關資訊。您可以檢視堆疊名稱、區域、提供者和識別符等資訊。
**從 動作開始檢視部署資訊**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程圖表中，選擇部署應用程式的工作流程動作。例如，您可以選擇 **DeployCloudFormationStack**。
1. 檢閱右側窗格中的內容，以取得動作特定的部署資訊。
# 建立工作流程
*工作流程*是一種自動化程序，說明如何建置、測試和部署程式碼，做為持續整合和持續交付 (CI/CD) 系統的一部分。工作流程定義了工作流程執行期間要採取的一系列步驟或*動作*。工作流程也會定義導致工作流程啟動的事件或*觸發條件*。若要設定工作流程，您可以使用 CodeCatalyst 主控台的[視覺化或 YAML 編輯器](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors)建立*工作流程定義檔案*。
**提示**
若要快速了解如何在專案中使用工作流程，[請使用藍圖建立專案](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template)。每個藍圖都會部署可檢閱、執行和實驗的正常運作工作流程。
使用下列程序在 CodeCatalyst 中建立工作流程。工作流程會以 YAML 檔案形式存放在所選來源儲存庫的`~/.codecatalyst/workflows/`資料夾中。或者，您可以在遞交工作流程檔案名稱時，使用資料夾名稱`~/.codecatalyst/workflows/`預先加上工作流程檔案名稱，將工作流程存放在 的子資料夾中。如需詳細資訊，請參閱下列指示。
如需工作流程的相關詳細資訊，請參閱 [使用工作流程建置、測試和部署使用工作流程建置、測試和部署](workflow.md)。
------
#### [ Visual ]
**使用視覺化編輯器建立工作流程**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
**建立工作流程**對話方塊隨即出現。
1. 在**來源儲存庫**欄位中，選擇工作流程定義檔案所在的來源儲存庫。如果來源儲存庫不存在，[請建立一個](source-repositories-create.md)。
1. 在**分支**欄位中，選擇工作流程定義檔案所在的分支。
1. 選擇**建立**。
Amazon CodeCatalyst 會將儲存庫和分支資訊儲存在記憶體中，但工作流程尚未遞交。
1. 選擇**視覺化**。
1. 建置工作流程：
1. （選用） 在工作流程圖表中，選擇**來源**和**觸發方塊**。**觸發程序**窗格隨即出現。選擇**新增觸發**條件以新增觸發條件。如需詳細資訊，請參閱[將觸發條件新增至工作流程](workflows-add-trigger-add.md)。
1. 選擇 **\$1 動作** （左上角）。**動作**目錄隨即出現。
1. 在動作內選擇加號 (**\$1**)，將其新增至工作流程。使用右側的窗格來設定動作。如需詳細資訊，請參閱[將動作新增至工作流程](workflows-add-action.md)。
1. （選用） 選擇**工作流程屬性** （右上角）。**工作流程屬性**窗格隨即出現。設定工作流程名稱執行模式和運算。如需詳細資訊，請參閱[設定執行的佇列行為](workflows-configure-runs.md)及[設定運算和執行時間映像](workflows-working-compute.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，然後在**遞交工作流程**對話方塊中，執行下列動作：
1. 對於**工作流程檔案名稱**，請保留預設名稱或輸入您自己的名稱。檔案將存放在所選來源儲存庫和分支的`~/.codecatalyst/workflows/`資料夾中。您可以在檔案名稱前面加上資料夾或子資料夾。範例：
+ 指定 `my-workflow`（無資料夾） 將檔案存放為 `~/.codecatalyst/workflows/my-workflow.yaml`
+ 指定 會將檔案`folder/subfolder/my-workflow`儲存為 `~/.codecatalyst/workflows/folder/subfolder/my-workflow.yaml`
1. 對於**遞交訊息**，請保留預設訊息或輸入您自己的訊息。
1. 針對**儲存庫**和**分支**，選擇工作流程定義檔案的來源儲存庫和分支。這些欄位應設定為您在**建立工作流程**對話方塊中稍早指定的儲存庫和分支。如果您願意，現在可以變更儲存庫和分支。
**注意**
遞交工作流程定義檔案後，無法與另一個儲存庫或分支建立關聯，因此請務必謹慎選擇。
1. 選擇**遞交**以遞交工作流程定義檔案。
------
#### [ YAML ]
**使用 YAML 編輯器建立工作流程**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
**建立工作流程**對話方塊隨即出現。
1. 在**來源儲存庫**欄位中，選擇工作流程定義檔案所在的來源儲存庫。如果來源儲存庫不存在，[請建立一個](source-repositories-create.md)。
1. 在**分支**欄位中，選擇工作流程定義檔案所在的分支。
1. 選擇**建立**。
Amazon CodeCatalyst 會將儲存庫和分支資訊儲存在記憶體中，但工作流程尚未遞交。
1. 選擇 **YAML**。
1. 建置工作流程：
1. （選用） 將觸發條件新增至 YAML 程式碼。如需詳細資訊，請參閱[將觸發條件新增至工作流程](workflows-add-trigger-add.md)。
1. 選擇 **\$1 動作** （左上角）。**動作**目錄隨即出現。
1. 選擇動作內的加號 (**\$1**)，將其新增至工作流程。使用右側的窗格來設定動作。如需詳細資訊，請參閱[將動作新增至工作流程](workflows-add-action.md)。
1. （選用） 選擇**工作流程屬性** （右上角）。**工作流程屬性**窗格隨即出現。設定工作流程名稱、執行模式和運算。如需詳細資訊，請參閱[設定執行的佇列行為](workflows-configure-runs.md)及[設定運算和執行時間映像](workflows-working-compute.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，然後在**遞交工作流程**對話方塊中，執行下列動作：
1. 對於**工作流程檔案名稱**，請保留預設名稱或輸入您自己的名稱。檔案將存放在所選來源儲存庫和分支的`~/.codecatalyst/workflows/`資料夾中。您可以在檔案名稱前面加上資料夾或子資料夾。範例：
+ 指定 `my-workflow`（無資料夾） 將檔案存放為 `~/.codecatalyst/workflows/my-workflow.yaml`
+ 指定 會將檔案`folder/subfolder/my-workflow`儲存為 `~/.codecatalyst/workflows/folder/subfolder/my-workflow.yaml`
1. 對於**遞交訊息**，請保留預設訊息或輸入您自己的訊息。
1. 針對**儲存庫**和**分支**，選擇工作流程定義檔案的來源儲存庫和分支。這些欄位應該設定為您在**建立工作流程**對話方塊中稍早指定的儲存庫和分支。如果您願意，現在可以變更儲存庫和分支。
**注意**
遞交工作流程定義檔案後，無法與另一個儲存庫或分支建立關聯，因此請務必謹慎選擇。
1. 選擇**遞交**以遞交工作流程定義檔案。
------
# 執行工作流程
*執行*是工作流程的單一迭代。在執行期間，CodeCatalyst 會執行工作流程組態檔中定義的動作，並輸出相關的日誌、成品和變數。
您可以手動啟動執行，也可以透過*工作流程觸發*來自動啟動執行。工作流程觸發的範例可能是軟體開發人員將遞交推送到您的主分支。
如果您錯誤地啟動工作流程，也可以在處理過程中手動停止工作流程執行。
如果大約同時啟動多個工作流程執行，您可以設定如何將這些執行排入佇列。您可以使用預設佇列行為，其中執行會依啟動順序依序排入佇列，或者您可以稍後從較早的執行取代 （或「接管」)，以加速整個執行。將您的工作流程執行設定為平行執行，以便沒有執行等待任何其他執行也是可能的。
啟動工作流程執行後，您可以手動或自動檢視執行的狀態和其他詳細資訊。例如，您可以查看啟動的時間、啟動人員，以及是否仍在執行。
**Topics**
+ [手動啟動工作流程執行](workflows-manually-start.md)
+ [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)
+ [設定僅限手動的觸發](workflows-manual-only.md)
+ [停止工作流程執行](workflows-stop.md)
+ [閘道工作流程執行](workflows-gates.md)
+ [需要工作流程執行的核准](workflows-approval.md)
+ [設定執行的佇列行為](workflows-configure-runs.md)
+ [在工作流程執行之間快取檔案](workflows-caching.md)
+ [檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)
# 手動啟動工作流程執行
在 Amazon CodeCatalyst 中，您可以從 CodeCatalyst 主控台手動啟動工作流程執行。
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**注意**
您也可以[設定觸發](workflows-add-trigger.md)來自動啟動工作流程執行。
**手動啟動工作流程執行**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**執行**。
# 使用觸發程序自動啟動工作流程執行
您可以使用工作流程觸發來自動啟動 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. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 設定僅限手動的觸發
您可以限制工作流程，以便團隊只能使用 CodeCatalyst 主控台中的**執行**按鈕手動啟動。若要設定此功能，您必須移除工作流程定義檔案中的 `Triggers`區段。建立工作流程時，預設會包含 `Triggers`區段，但 區段是選用的，可以移除。
使用以下指示移除工作流程定義檔案中的 `Triggers`區段，以便只能手動啟動工作流程。
關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
如需執行工作流程的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
------
#### [ Visual ]
**移除「觸發器」區段 （視覺編輯器）**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇工作流程圖表中的**來源**方塊。
1. 在**觸發**下，選擇垃圾桶圖示，從工作流程中移除 `Triggers`區段。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**移除「觸發器」區段 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 尋找 `Triggers`區段並將其移除。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 停止工作流程執行
使用下列程序來停止進行中的工作流程執行。如果執行是意外啟動，您可能想要停止執行。
當您停止工作流程執行時，CodeCatalyst 會等待進行中的動作完成，再於 CodeCatalyst 主控台將執行標記為**已停止**。任何沒有機會啟動的動作都不會啟動，且會標示為**已捨棄**。
**注意**
如果執行已排入佇列 （也就是沒有進行中的動作），則會立即停止執行。
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**停止工作流程執行**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 在**工作流程**下，選擇**執行**，然後從清單中選擇進行中執行。
1. 選擇**停止**。
# 閘道工作流程執行
除非符合特定條件，否則*閘道*是一種工作流程元件，可用來防止工作流程執行繼續進行。閘道的範例是**核准**閘道，使用者必須在 CodeCatalyst 主控台中提交核准，工作流程執行才能繼續。
您可以在工作流程中的動作序列之間或在第一個動作之前新增閘道 （在**來源**下載之後立即執行）。如果您需要，也可以在最後一個動作之後新增閘道。
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**Topics**
+ [閘道類型](#workflows-gates-types)
+ [我可以設定閘道以平行於另一個動作執行嗎？](#workflows-approval-parallel)
+ [我可以使用閘道來防止工作流程執行啟動嗎？](#workflows-gates-prevent)
+ [閘道的限制](#workflows-gate-limitations)
+ [將閘道新增至工作流程](workflows-gates-add.md)
+ [定序閘道和動作](workflows-gates-depends-on.md)
+ [指定閘道的版本](workflows-gates-version.md)
## 閘道類型
目前，Amazon CodeCatalyst 支援一種閘道類型：**核准**閘道。如需詳細資訊，請參閱[需要工作流程執行的核准](workflows-approval.md)。
## 我可以設定閘道以平行於另一個動作執行嗎？
否。Gates 只能在動作之前或之後執行。如需詳細資訊，請參閱[定序閘道和動作](workflows-gates-depends-on.md)。
## 我可以使用閘道來防止工作流程執行啟動嗎？
是，具有資格。
您可以防止工作流程執行*執行任務*，這與防止工作流程*啟動*略有不同。
若要防止工作流程執行任務，請在工作流程中第一個動作之前新增閘道。在此案例中，工作流程執行*將開始*，這表示它將下載您的來源儲存庫檔案，但在閘道解除鎖定之前，將無法執行任務。
**注意**
開始然後被閘道封鎖的工作流程仍會計入*每個空間配額和其他配額的並行工作流程執行數目上限*。為了確保您不超過工作流程配額，請考慮使用工作流程觸發條件來有條件地啟動工作流程，而不是使用閘道。也請考慮使用提取請求核准規則，而非閘道。如需配額、觸發條件和提取請求核准規則的詳細資訊，請參閱 [CodeCatalyst 中工作流程的配額](workflows-quotas.md)、 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)和 [管理將提取請求與核准規則合併的要求](source-pull-requests-approval-rules.md)。
## 閘道的限制
Gates 有下列限制：
+ Gates 無法與運算共用功能搭配使用。如需使用此功能的詳細資訊，請參閱「[跨動作共用運算](compute-sharing.md)」。
+ 動作群組內無法使用閘道。如需動作群組的詳細資訊，請參閱 [將動作分組為動作群組](workflows-group-actions.md)。
# 將閘道新增至工作流程
在 Amazon CodeCatalyst 中，您可以將閘道新增至工作流程，以防止其繼續，除非符合特定條件。使用下列指示將閘道新增至工作流程。
如需閘道的詳細資訊，請參閱 [閘道工作流程執行](workflows-gates.md)。
**新增和設定閘道**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左側，選擇**閘道**。
1. 在閘道目錄中，搜尋閘道，然後選擇加號 (**＋**) 將閘道新增至工作流程。
1. 設定閘道。選擇**視覺化**以使用視覺化編輯器，或選擇 **YAML** 以使用 YAML 編輯器。如需詳細說明，請參閱：
+ [新增「核准」閘道](workflows-approval-add.md)
1. （選用） 選擇**驗證**以確保 YAML 程式碼有效。
1. 選擇**遞交**以遞交您的變更。
# 定序閘道和動作
在 Amazon CodeCatalyst 中，您可以設定要在工作流程動作、動作群組或閘道之前或之後執行的閘道。例如，您可以設定在`Deploy`動作之前執行的`Approval`閘道。在這種情況下，該`Deploy`動作被說是*取決於*`Approval`閘道。
若要設定閘道和動作之間的相依性，請設定閘道或動作的**相依**屬性。如需說明，請參閱 [在動作之間設定相依性](workflows-depends-on-set-up.md)。參考的指示是指工作流程*動作*，但同樣適用於閘道。
如需如何使用閘道設定**相依**屬性的範例，請參閱 [範例：「核准」閘道](workflows-approval-example.md)。
如需閘道的詳細資訊，請參閱 [閘道工作流程執行](workflows-gates.md)。
如需工作流程動作的詳細資訊，請參閱 [設定工作流程動作](workflows-actions.md)。
# 指定閘道的版本
根據預設，當您將閘道新增至工作流程時，CodeCatalyst 會使用下列格式將完整版本新增至工作流程定義檔案：
`vmajor.minor.patch`
例如：
```
My-Gate:
Identifier: aws/approval@v1
```
您可以延長版本，讓工作流程使用特定的主要或次要版本的閘道。如需說明，請參閱 [指定要使用的動作版本](workflows-action-versions.md)。參考主題是指工作流程動作，但同樣適用於閘道。
如需 CodeCatalyst 中閘道的詳細資訊，請參閱 [閘道工作流程執行](workflows-gates.md)。
# 需要工作流程執行的核准
您可以將工作流程執行設定為需要核准才能繼續。若要達成此目的，您必須將**核准**[閘道](workflows-gates.md)新增至工作流程。*核准閘道*可防止工作流程繼續進行，直到使用者或一組使用者在 CodeCatalyst 主控台中提交一或多個核准。授予所有核准後，閘道會「解鎖」，並允許工作流程執行繼續。
在您的工作流程中使用**核准**閘道，讓您的開發、營運和領導團隊有機會在將您的變更部署到更廣泛的受眾之前檢閱變更。
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**Topics**
+ [如何解鎖核准閘道？](#workflows-approval-conditions)
+ [何時使用「核准」閘道](#workflows-approval-when)
+ [誰可以提供核准？](#workflows-approval-who)
+ [如何通知使用者需要核准？](#workflows-approval-notify-methods)
+ [我可以使用「核准」閘道來防止工作流程執行啟動嗎？](#workflows-approval-prevent)
+ [工作流程核准如何使用佇列、取代和平行執行模式？](#workflows-approval-run-mode)
+ [範例：「核准」閘道](workflows-approval-example.md)
+ [新增「核准」閘道](workflows-approval-add.md)
+ [設定核准通知](workflows-approval-notify.md)
+ [核准或拒絕工作流程執行](workflows-approval-approve.md)
+ [「核准」閘道 YAML](approval-ref.md)
## 如何解鎖核准閘道？
若要解除鎖定**核准**閘道，必須符合下列*所有*條件：
+ **條件 1**：必須提交必要的核准數量。所需的核准數量是可設定的，而且每個使用者都可以提交單一核准。
+ **條件 2**：所有核准都必須在閘道逾時之前提交。閘道會在啟用 14 天後逾時。此期間無法設定。
+ **條件 3**：沒有人必須拒絕工作流程執行。單一拒絕會導致工作流程執行失敗。
+ **條件 4**：（只有在您使用取代的執行模式時才適用。) 執行不得由稍後的執行取代。如需詳細資訊，請參閱[工作流程核准如何使用佇列、取代和平行執行模式？](#workflows-approval-run-mode)。
如果不符合任何條件，CodeCatalyst 會停止工作流程，並將執行狀態設定為**失敗** （在**條件 1** 到 **3** 的情況下） 或**被取代** （在**條件 4 **的情況下）。
## 何時使用「核准」閘道
一般而言，您會在工作流程中使用**核准**閘道，將應用程式和其他資源部署到生產伺服器或任何必須驗證品質標準的環境。透過在部署到生產環境之前放置 閘道，您可以讓檢閱者有機會在新軟體修訂版可供公開使用之前進行驗證。
## 誰可以提供核准？
任何身為您專案成員且具有**貢獻者**或**專案管理員**角色的使用者都可以提供核准。具有屬於您專案空間之**空間管理員**角色的使用者也可以提供核准。
**注意**
具有 **Reviewer** 角色的使用者無法提供核准。
## 如何通知使用者需要核准？
若要通知使用者需要核准，您必須：
+ 讓 CodeCatalyst 傳送 Slack 通知給他們。如需詳細資訊，請參閱[設定核准通知](workflows-approval-notify.md)。
+ 前往 CodeCatalyst 主控台中**核准**和**拒絕**按鈕所在的頁面，並將該頁面的 URL 貼到傳送給核准者的電子郵件或簡訊應用程式中。如需如何導覽至此頁面的詳細資訊，請參閱 [核准或拒絕工作流程執行](workflows-approval-approve.md)。
## 我可以使用「核准」閘道來防止工作流程執行啟動嗎？
是，具有資格。如需詳細資訊，請參閱[我可以使用閘道來防止工作流程執行啟動嗎？](workflows-gates.md#workflows-gates-prevent)。
## 工作流程核准如何使用佇列、取代和平行執行模式？
使用佇列、取代或平行執行模式時，**核准**閘道的運作方式與 [動作](workflows-actions.md)類似。我們建議您閱讀 [關於排入佇列的執行模式](workflows-configure-runs.md#workflows-configure-runs-queued)、[關於取代的執行模式](workflows-configure-runs.md#workflows-configure-runs-superseded)、 [關於平行執行模式](workflows-configure-runs.md#workflows-configure-runs-parallel)區段，以熟悉這些執行模式。一旦您對它們有基本的了解，請返回本節以了解這些執行模式在存在**核准**閘道時的運作方式。
存在**核准**閘道時，會依下列方式處理執行：
+ 如果您使用的是[排入佇列的執行模式](workflows-configure-runs.md#workflows-configure-runs-queued)，則執行會在目前在閘道等待核准的執行後方排入佇列。當該閘道解除鎖定 （即所有核准都已授予） 時，佇列中的下一個執行會推進到閘道，並等待核准。此程序會繼續透過閘道one-by-one處理排入佇列的執行。 [Figure 1](#figure-1-workflow-queued-run-mode-ma)會說明此程序。
+ 如果您使用的是[取代的執行模式](workflows-configure-runs.md#workflows-configure-runs-superseded)，則行為與佇列執行模式的行為相同，除了讓 執行在閘道的佇列中堆積之外，較新的執行會取代 （接管） 較早的執行。沒有佇列，而且目前等待核准的任何執行都會取消，並由較新的執行取代。 會[Figure 2](#figure-2-workflow-superseded-run-mode-ma)說明此程序。
+ 如果您使用的是[平行執行模式](workflows-configure-runs.md#workflows-configure-runs-parallel)，則 會平行開始執行，而且不會形成佇列。每個執行都會立即由閘道處理，因為之前沒有執行。 [Figure 3](#figure-3-workflow-parallel-run-mode-ma)會說明此程序。
**圖 1**：「佇列執行模式」和**核准**閘道
![\[「核准」閘道如何與「佇列執行模式」搭配使用\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/runmode-queued-ma.png)
**圖 2**：「超級執行模式」和**核准**閘道
![\[「核准」閘道如何與「更新後的執行模式」搭配使用\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/runmode-superseded-ma.png)
**圖 3**：「平行執行模式」和**核准**閘道
![\[「核准」閘道如何與「平行執行模式」搭配使用\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/runmode-parallel-ma.png)
# 範例：「核准」閘道
下列範例示範如何在兩個名為 的動作`Approval_01`之間新增名為 `Staging`的**核准**閘道，以及 `Production`。`Staging` 動作會先執行，再執行`Approval_01`閘道秒，最後執行`Production`動作。只有在`Approval_01`閘道解除鎖定時，才會執行`Production`動作。`DependsOn` 屬性可確保 `Staging`、 `Approval_01`和 `Production`階段依順序執行。
如需**核准**閘道的詳細資訊，請參閱 [需要工作流程執行的核准](workflows-approval.md)。
```
Actions:
Staging: # Deploy to a staging server
Identifier: aws/ecs-deploy@v1
Configuration:
...
Approval_01:
Identifier: aws/approval@v1
DependsOn:
- Staging
Configuration:
ApprovalsRequired: 2
Production: # Deploy to a production server
Identifier: aws/ecs-deploy@v1
DependsOn:
- Approval_01
Configuration:
...
```
# 新增「核准」閘道
若要將工作流程設定為需要核准，您必須將**核准**閘道新增至工作流程。使用下列指示將**核准**閘道新增至您的工作流程。
如需此閘道的詳細資訊，請參閱 [需要工作流程執行的核准](workflows-approval.md)。
------
#### [ Visual ]
**將「核准」閘道新增至工作流程 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 在左上角，選擇**閘道**。
1. 在**閘道**目錄中的**核准**中，選擇加號 (**\$1**)。
1. 選擇**輸入**，然後在**相依**欄位中執行下列動作。
指定必須成功執行的動作、動作群組或閘道，才能執行此閘道。根據預設，當您將閘道新增至工作流程時，閘道會設定為取決於工作流程中的最後一個動作。如果您移除此屬性，閘道將不會相依於任何項目，而且 會在其他動作之前先執行。
**注意**
閘道必須設定為在動作、動作群組或閘道之前或之後執行。它無法設定為與其他動作、動作群組和閘道平行執行。
如需 **依功能而定**的詳細資訊，請參閱 [定序閘道和動作](workflows-gates-depends-on.md)。
1. 選擇 **Configuration** (組態) 索引標籤。
1. 在**閘道名稱**欄位中，執行下列動作。
指定您要提供閘道的名稱。所有閘道名稱在工作流程中必須是唯一的。閘道名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在閘道名稱中啟用特殊字元和空格。
1. （選用） 在**核准數量**欄位中，執行下列動作。
指定解鎖核准閘道所需的**最低核准**數量。最小值為 `1`。上限為 `2`。如果省略，則預設值為 `1`。
**注意**
如果您想要省略 `ApprovalsRequired` 屬性，請從工作流程定義檔案移除閘道的 `Configuration`區段。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**將「核准」閘道新增至工作流程 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 使用下列範例做為指南，新增 `Approval`區段和基礎屬性。如需詳細資訊，請參閱《[「核准」閘道 YAML](approval-ref.md)》中的 [工作流程 YAML 定義](workflow-reference.md)。
```
Actions:
MyApproval_01:
Identifier: aws/approval@v1
DependsOn:
- PreviousAction
Configuration:
ApprovalsRequired: 2
```
如需其他範例，請參閱[範例：「核准」閘道](workflows-approval-example.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 設定核准通知
您可以讓 CodeCatalyst 傳送通知至 Slack 頻道，通知使用者工作流程執行需要核准。使用者會看到通知並按一下其中的連結。此連結會將它們帶往 CodeCatalyst 核准頁面，他們可以在其中核准或拒絕工作流程。
您也可以設定通知，通知使用者工作流程已核准、遭拒，或核准請求已過期。
使用下列指示來設定 Slack 通知。
**開始之前**
請確定您已將**核准**閘道新增至工作流程。如需詳細資訊，請參閱[新增「核准」閘道](workflows-approval-add.md)。
**傳送工作流程核准通知至 Slack 頻道**
1. 使用 Slack 設定 CodeCatalyst。如需詳細資訊，請參閱[Slack 通知入門](getting-started-notifications.md)。
1. 在包含需要核准之工作流程的 CodeCatalyst 專案中，如果通知尚未啟用，請啟用通知。若要啟用通知：
1. 導覽至您的專案，然後在導覽窗格中選擇**專案設定**。
1. 在頂端，選擇**通知**。
1. 在**通知事件**中，選擇**編輯通知**。
1. 開啟**工作流程核准待定**，然後選擇 CodeCatalyst 將傳送通知的 Slack 頻道。
1. （選用） 開啟其他通知，提醒人員核准、拒絕和過期的核准。您可以開啟**工作流程執行已核准**、**工作流程執行遭拒**、**工作流程核准已取代**，以及**工作流程核准逾時**。在每個通知旁，選擇 CodeCatalyst 將傳送通知的 Slack 頻道。
1. 選擇 **Save** (儲存)。
# 核准或拒絕工作流程執行
包含**核准**閘道的工作流程執行將需要核准或拒絕。使用者可以提供核准或拒絕，從：
+ CodeCatalyst 主控台
+ 團隊成員提供的連結
+ 自動化 Slack 通知
使用者提供核准或拒絕後，此決策將無法復原。
**注意**
只有特定使用者可以核准或拒絕工作流程執行。如需詳細資訊，請參閱[誰可以提供核准？](workflows-approval.md#workflows-approval-who)。
**開始之前**
請確定您已將**核准**閘道新增至工作流程。如需詳細資訊，請參閱[新增「核准」閘道](workflows-approval-add.md)。
**從 CodeCatalyst 主控台開始核准或拒絕工作流程執行**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程圖表中，選擇代表**核准**閘道的方塊。
側邊面板隨即出現。
**注意**
此時，您可以視需要將此頁面的 URL 傳送給其他核准者。
1. 在**檢閱決策**下，選擇**核准**或拒絕****。
1. （選用） 在**註解 - 選用**中，輸入註解，指出您核准或拒絕工作流程執行的原因。
1. 選擇**提交**。
**從團隊成員提供的連結開始核准或拒絕工作流程執行**
1. 選擇團隊成員傳送給您的連結。（您可以讓團隊成員閱讀上述程序以取得連結。)
1. 如果系統要求，請登入 CodeCatalyst。
系統會將您重新導向至工作流程執行核准頁面。
1. 在**檢閱決策**下，選擇**核准**或拒絕****。
1. （選用） 在**註解 - 選用**中，輸入註解，指出您核准或拒絕工作流程執行的原因。
1. 選擇**提交**。
**從自動化 Slack 通知開始核准或拒絕工作流程執行**
1. 確定已設定 Slack 通知。請參閱 [設定核准通知](workflows-approval-notify.md)。
1. 在 Slack 中，在傳送核准通知的管道中，選擇核准通知中的連結。
1. 如果系統要求，請登入 CodeCatalyst。
系統會將您重新導向至工作流程執行頁面。
1. 在工作流程圖表中，選擇核准閘道。
1. 在**檢閱決策**下，選擇**核准**或拒絕****。
1. （選用） 在**註解 - 選用**中，輸入註解，指出您核准或拒絕工作流程執行的原因。
1. 選擇**提交**。
# 「核准」閘道 YAML
以下是**核准**閘道的 YAML 定義。若要了解如何使用此閘道，請參閱 [需要工作流程執行的核准](workflows-approval.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The 'Approval' gate definition starts here.
Approval:
Identifier: aws/approval@v1
DependsOn:
- another-action
Configuration:
ApprovalsRequired: number
```
## Approval
(必要)
指定您要提供閘道的名稱。工作流程中的所有閘道名稱都必須是唯一的。閘道名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在閘道名稱中啟用特殊字元和空格。
預設：`Approval_nn`。
對應的 UI：組態索引標籤/**閘道名稱**
## Identifier
(*Approval*/**Identifier**)
(必要)
識別閘道。**核准**閘道支援版本 `1.0.0`。除非您想要縮短版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/approval@v1`。
對應的 UI：工作流程圖表/Approval\$1nn/**aws/approval@v1** 標籤
## DependsOn
(*Approval*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此閘道。根據預設，當您將閘道新增至工作流程時，閘道會設定為取決於工作流程中的最後一個動作。如果您移除此屬性，閘道將不會相依於任何項目，而且 會在其他動作之前先執行。
**注意**
閘道必須設定為在動作、動作群組或閘道之前或之後執行。它無法設定為與其他動作、動作群組和閘道平行執行。
如需 **依功能而定**的詳細資訊，請參閱 [定序閘道和動作](workflows-gates-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於**
## Configuration
(*Approval*/**Configuration**)
(選用)
您可以在此區段定義閘道的組態屬性。
對應的 UI：**組態**索引標籤
## ApprovalsRequired
(*Approval*/Configuration/**ApprovalsRequired**)
(選用)
指定解鎖核准閘道所需的**最低核准**數量。最小值為 `1`。上限為 `2`。如果省略，則預設值為 `1`。
**注意**
如果您想要省略 `ApprovalsRequired` 屬性，請從工作流程定義檔案移除閘道的 `Configuration`區段。
對應的 UI：組態索引標籤/**核准數目**
# 設定執行的佇列行為
根據預設，在 Amazon CodeCatalyst 中，當多個工作流程執行同時發生時，CodeCatalyst 會將它們排入佇列，並依啟動順序逐一處理。您可以指定*執行模式*來變更此預設行為。有幾種執行模式：
+ （預設） 佇列執行模式 – CodeCatalyst 程序會逐一執行
+ 取代的執行模式 – CodeCatalyst 程序會逐一執行，而較新的執行會覆寫較舊的執行
+ 平行執行模式 – CodeCatalyst 程序平行執行
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**Topics**
+ [關於排入佇列的執行模式](#workflows-configure-runs-queued)
+ [關於取代的執行模式](#workflows-configure-runs-superseded)
+ [關於平行執行模式](#workflows-configure-runs-parallel)
+ [設定執行模式](#workflows-configure-runs-configure)
## 關於排入佇列的執行模式
在*佇列執行模式中*，執行會依序發生，等待執行會形成佇列。
佇列會在動作和動作群組的進入點形成，因此您可以在*相同的工作流程中擁有多個佇列* （請參閱 [Figure 1](#figure-1-workflow-queued-run-mode))。當排入佇列的執行進入動作時，動作會遭到鎖定，而且無法進入其他執行。當執行完成並結束動作時，動作會變成解除鎖定並準備好供下次執行使用。
[Figure 1](#figure-1-workflow-queued-run-mode) 說明在佇列執行模式中設定的工作流程。它顯示：
+ 七個執行透過工作流程運作。
+ 兩個佇列：一個在輸入來源的項目之外 (**Repo：main**)，另一個在 **BuildTestActionGroup** 動作的項目之外。
+ 兩個鎖定的區塊：輸入來源 (**Repo：main**) 和 **BuildTestActionGroup**。
以下是當工作流程執行完成處理時，實物會轉傳的方式：
+ 當 **Run-4d444** 完成來源儲存庫的複製時，它會結束輸入來源，並加入 **Run-3c333** 後面的佇列。然後，**Run-5e555** 將輸入輸入來源。
+ 當 **Run-1a111** 完成建置和測試時，它會結束 **BuildTestActionGroup** 動作並輸入 **DeployAction** 動作。然後，**Run-2b222** 將輸入 **BuildTestActionGroup** 動作。
**圖 1**：在「佇列執行模式」中設定的工作流程
![\[在「佇列執行模式」中設定的工作流程\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/RunMode-Queued.png)
在以下情況下使用佇列執行模式：
+ **您想要在功能和執行之間保持one-to-one的關係 – 使用取代模式時，這些功能可能會分組**。例如，當您在遞交 1 中合併功能 1 時，執行 1 會啟動，而當您在遞交 2 中合併功能 2 時，執行 2 會啟動，以此類推。如果您要使用取代模式而非佇列模式，您的功能 （和遞交） 將在取代其他功能的執行中分組在一起。
+ **您想要避免使用平行模式時可能發生的競爭條件和非預期問題**。例如，如果兩個軟體開發人員 Wang 和 Saanvi 開始工作流程大約同時執行以部署到 Amazon ECS 叢集，Wang 的執行可能會開始叢集上的整合測試，而 Saanvi 的執行則會將新的應用程式程式碼部署到叢集，導致 Wang 的測試失敗或測試錯誤的程式碼。另一個範例是，您可能有一個沒有鎖定機制的目標，在這種情況下，兩個執行可能會以非預期的方式覆寫彼此的變更。
+ **您想要限制 CodeCatalyst 用來處理執行之運算資源的負載**。 CodeCatalyst 例如，如果您的工作流程中有三個動作，您最多可以同時發生三個執行。對一次可發生的執行次數施加限制，可讓執行輸送量更可預測。
+ **您想要限制工作流程對第三方服務提出的請求數量**。例如，您的工作流程可能有建置動作，其中包含從 Docker Hub 提取映像的指示。[Docker Hub 會將您可以提出的提取請求數量限制](https://www.docker.com/increase-rate-limits)為每個帳戶每小時特定數量，如果您超過限制，將會鎖定您。使用排入佇列的執行模式來減慢您的執行輸送量，將產生每小時對 Docker Hub 的較少請求，從而限制鎖定和導致建置和執行失敗的可能性。
**佇列大小上限**：50
**佇列大小上限**的注意事項：
+ 最大佇列大小是指工作流程中*所有佇列*允許的執行次數上限。
+ 如果佇列的執行時間超過 50 次，則 CodeCatalyst 會捨棄第 51 次和後續的執行。
**失敗行為**：
如果執行在動作處理時變得沒有回應，則其後面的執行會保留在佇列中，直到動作逾時為止。動作在一小時後逾時。
如果 動作內的執行失敗，則允許其後方的第一個佇列執行繼續。
## 關於取代的執行模式
*取代的執行模式*與排入*佇列的執行模式*相同，但：
+ 如果佇列的執行追上佇列中的另一個執行，則稍後的執行會取代 （接管） 較早的執行，而較早的執行會取消並標示為 'upersed'。
+ 做為第一個項目符號中所述行為的結果，佇列只能在使用取代的執行模式時包含一次執行。
使用 中的工作流程[Figure 1](#figure-1-workflow-queued-run-mode)做為指南，將取代的執行模式套用至此工作流程將導致下列情況：
+ **Run-7g777** 會取代佇列中的其他兩個執行，並且會是**佇列 \$11** 中剩餘的唯一執行。**Run-6f666** 和 **Run-5e555** 將會取消。
+ **Run-3c333** 會取代 **Run-2b222**，並且是**佇列 \$12** 中剩餘的唯一執行。**Run-2b222** 將被取消。
如果您想要的話，請使用取代的執行模式：
+ 比使用佇列模式的輸送量更好
+ 與排入佇列模式相比，對第三方服務的請求更少；如果第三方服務具有速率限制，例如 Docker Hub，這就很有幫助
## 關於平行執行模式
在*平行執行模式中*，執行彼此獨立，且不會等待其他執行完成再開始。沒有佇列，且執行輸送量只會受到工作流程內動作完成的速度限制。
在開發環境中使用平行執行模式，其中每個使用者都有自己的功能分支，並部署到其他使用者未共用的目標。
**重要**
如果您有多個使用者可以部署的共用目標，例如生產環境中的 Lambda 函數，請勿使用平行模式，因為可能會導致競爭條件。當平行工作流程執行嘗試同時變更共用資源，導致無法預測的結果時，就會發生*競爭條件*。
**平行執行的最大數量**：每個 CodeCatalyst 空間 1000 個
## 設定執行模式
您可以將執行模式設定為已排入佇列、已取代或平行。預設值已排入佇列。
當您將執行模式從佇列或取代變更為平行時，CodeCatalyst 會取消已佇列的執行，並允許動作目前正在處理的執行完成，然後再取消它們。
當您將執行模式從平行變更為佇列或取代時，CodeCatalyst 會讓目前執行的所有平行執行完成。您在將執行模式變更為已排入佇列或已取代後啟動的任何執行都會使用新的模式。
------
#### [ Visual ]
**使用視覺化編輯器變更執行模式**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 在右上角，選擇**工作流程屬性**。
1. 展開**進階**，然後在**執行模式下**，選擇下列其中一項：
1. **已排入佇列** – 請參閱 [關於排入佇列的執行模式](#workflows-configure-runs-queued)
1. **取代** – 請參閱 [關於取代的執行模式](#workflows-configure-runs-superseded)
1. **平行** – 請參閱 [關於平行執行模式](#workflows-configure-runs-parallel)
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器變更執行模式**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 新增 `RunMode` 屬性，如下所示：
```
Name: Workflow_6d39
SchemaVersion: "1.0"
RunMode: QUEUED|SUPERSEDED|PARALLEL
```
如需詳細資訊，請參閱《》中 [最上層屬性](workflow-reference.md#workflow.top.level) 區段的 `RunMode` 屬性描述[工作流程 YAML 定義](workflow-reference.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 在工作流程執行之間快取檔案
啟用檔案快取時，建置和測試動作會將磁碟上檔案儲存至快取，並在後續工作流程執行中從該快取還原這些檔案。快取可減少建置或下載未在執行之間變更的相依性所導致的延遲。CodeCatalyst 也支援備用快取，可用於還原包含一些所需相依性的部分快取。這有助於減少快取遺漏的延遲影響。
**注意**
檔案快取僅適用於 Amazon CodeCatalyst [建置](build-workflow-actions.md)和[測試](test-workflow-actions.md)動作，且僅當它們設定為使用 **EC2** [運算類型](workflows-working-compute.md#compute.types)時。
**Topics**
+ [關於檔案快取](#workflows-caching.files)
+ [建立快取](#workflows-caching.fallback)
+ [檔案快取限制條件](#workflows-caching.constraints)
## 關於檔案快取
檔案快取可讓您將資料整理成多個快取，每個快取都在 `FileCaching` 屬性下參考。每個快取都會儲存指定路徑指定的目錄。指定的目錄將在未來的工作流程執行中還原。以下是使用名為 `cacheKey1`和 的多個快取進行快取的範例 YAML 程式碼片段`cacheKey2`。
```
Actions:
BuildMyNpmApp:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: npm install
- Run: npm run test
Caching:
FileCaching:
cacheKey1:
Path: file1.txt
RestoreKeys:
- restoreKey1
cacheKey2:
Path: /root/repository
RestoreKeys:
- restoreKey2
- restoreKey3
```
**注意**
CodeCatalyst 使用多層快取，其中包含本機快取和遠端快取。當佈建的機群或隨需機器在本機快取上遇到快取遺失時，將從遠端快取還原相依性。因此，某些動作執行可能會因為下載遠端快取而遇到延遲。
CodeCatalyst 會套用快取存取限制，以確保某個工作流程中的動作無法修改來自不同工作流程的快取。這可保護每個工作流程，避免其他工作流程推送可能影響建置或部署的不正確資料。快取範圍會強制執行限制，將快取隔離到每個工作流程和分支配對。例如， `workflow-A` 分支`feature-A`中的檔案快取與 同級分支 `workflow-A`中的檔案快取不同`feature-B`。
當工作流程尋找指定的檔案快取且找不到它時，就會發生快取遺漏。這可能有多種原因，例如建立新分支或參考新快取且尚未建立時。也可能在快取過期時發生，依預設，會在上次使用後 14 天發生。為了減輕快取遺漏並提高快取命中率，CodeCatalyst 支援備用快取。備用快取是替代快取，提供還原部分快取的機會，這可能是快取的較舊版本。快取會先在 下搜尋屬性名稱`FileCaching`的相符項目來還原，如果找不到， 會評估 `RestoreKeys`。如果屬性名稱和所有 都存在快取遺漏`RestoreKeys`，工作流程將繼續執行，因為快取是盡最大努力且不保證的。
## 建立快取
您可以使用下列指示將快取新增至工作流程。
------
#### [ Visual ]
**使用視覺化編輯器新增快取**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要新增快取的動作。
1. 選擇 **Configuration (組態)**。
1. 在**檔案快取 - 選用**下，選擇**新增快取**並在欄位中輸入資訊，如下所示：
**索引鍵**
指定主要快取屬性名稱的名稱。快取屬性名稱在工作流程中必須是唯一的。每個動作在 中最多可以有五個項目`FileCaching`。
**路徑**
指定快取的關聯路徑。
**還原金鑰 - 選用**
找不到主要快取屬性時，指定要用作備用的還原金鑰。還原金鑰名稱在工作流程中必須是唯一的。每個快取在 中最多可以有五個項目`RestoreKeys`。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增快取**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在工作流程動作中，新增類似下列的程式碼：
```
action-name:
Configuration:
Steps: ...
Caching:
FileCaching:
key-name:
Path: file-path
# # Specify any additional fallback caches
# RestoreKeys:
# - restore-key
```
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 檔案快取限制條件
以下是 屬性名稱 和 的限制`RestoreKeys`條件：
+ 名稱在工作流程中必須是唯一的。
+ 名稱僅限於英數字元 (A-Z、a-z、0-9)、連字號 (-) 和底線 (\$1)。
+ 名稱最多可有 180 個字元。
+ 每個動作在 中最多可以有五個快取`FileCaching`。
+ 每個快取在 中最多可以有五個項目`RestoreKeys`。
以下是路徑的限制：
+ 不允許星號 (\$1)。
+ 路徑最多可有 255 個字元。
# 檢視工作流程執行狀態和詳細資訊
在 Amazon CodeCatalyst 中，您可以檢視單一工作流程執行的狀態和詳細資訊，或同時檢視多個執行。
如需可能執行狀態的清單，請參閱 [工作流程執行狀態](workflows-view-run-status.md)。
**注意**
您也可以檢視工作流程狀態，這與工作流程*執行*狀態不同。如需詳細資訊，請參閱[檢視工作流程的狀態](workflows-view-status.md)。
如需工作流程執行的詳細資訊，請參閱 [執行工作流程](workflows-working-runs.md)。
**Topics**
+ [檢視單一執行的狀態和詳細資訊](#workflows-view-run-single)
+ [檢視專案中所有執行的狀態和詳細資訊](#workflows-view-run-all)
+ [檢視特定工作流程所有執行的狀態和詳細資訊](#workflows-view-run-wf)
+ [在工作流程圖表中檢視工作流程的執行](#workflows-view-run-wf-diagram)
## 檢視單一執行的狀態和詳細資訊
您可能想要檢視單一工作流程執行的狀態和詳細資訊，以檢查其是否成功、查看何時完成，或檢視啟動的人員或項目。
**檢視單一執行的狀態和詳細資訊**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程的名稱下，選擇**執行**。
1. 在**執行歷史記錄**的**執行 ID** 欄中，選擇執行。例如 `Run-95a4d`。
1. 在執行的名稱下，執行下列其中一項操作：
+ **視覺化**查看工作流程圖表，其中顯示工作流程執行的動作及其狀態 （請參閱 [工作流程執行狀態](workflows-view-run-status.md))。此檢視也會顯示執行期間使用的來源儲存庫和分支。
在工作流程圖表中，選擇動作以查看詳細資訊，例如 動作在執行期間產生的日誌、報告和輸出。顯示的資訊取決於選取的動作類型。如需檢視建置或部署日誌的詳細資訊，請參閱 [檢視建置動作的結果](build-view-results.md)或 [檢視部署日誌](deploy-deployment-logs.md)。
+ **YAML** 查看用於執行的工作流程定義檔案。
+ 查看工作流程執行所產生成品的**成品**。如需成品的詳細資訊，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
+ **用於**查看測試報告和工作流程執行產生之其他類型的報告的報告。如需報告的詳細資訊，請參閱 [品質報告類型](test-workflow-actions.md#test-reporting)。
+ **變數**，用於查看工作流程執行所產生的輸出變數。如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**注意**
如果已刪除執行的父工作流程，則執行詳細資訊頁面頂端會顯示指出此事實的訊息。
## 檢視專案中所有執行的狀態和詳細資訊
您可能想要檢視專案中所有工作流程執行的狀態和詳細資訊，以了解專案中的工作流程活動進行程度，並了解工作流程的整體運作狀態。
**檢視專案中所有執行的狀態和詳細資訊**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 在**工作流程**下，選擇**執行**。
系統會顯示專案中所有儲存庫中所有分支中所有工作流程的所有執行。
此頁面包含下列資料欄：
+ **執行 ID** – 執行的唯一識別符。選擇執行 ID 連結，以檢視執行的詳細資訊。
+ **狀態** – 工作流程執行的處理狀態。如需執行狀態的詳細資訊，請參閱 [工作流程執行狀態](workflows-view-run-status.md)。
+ **觸發** – 啟動工作流程執行的人員、遞交、提取請求 (PR) 或排程。如需詳細資訊，請參閱[使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **工作流程** – 啟動執行的工作流程名稱，以及工作流程定義檔案所在的來源儲存庫和分支。您可能需要展開資料欄寬度才能查看此資訊。
**注意**
如果此欄設定為**無法使用**，通常是因為關聯的工作流程已刪除或移動。
+ **開始時間** – 工作流程執行開始的時間。
+ **持續時間** – 工作流程執行處理所需的時間。持續時間非常長或非常短可能表示發生問題。
+ **結束時間** – 工作流程執行結束的時間。
## 檢視特定工作流程所有執行的狀態和詳細資訊
您可能想要檢視與特定工作流程關聯之所有執行的狀態和詳細資訊，以查看是否有任何執行正在工作流程中建立瓶頸，或查看哪些執行目前正在進行中或已完成。
**檢視特定工作流程所有執行的狀態和詳細資訊**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程的名稱下，選擇**執行**。
與所選工作流程相關聯的執行隨即出現。
頁面分為兩個部分：
+ **作用中執行** – 顯示正在進行的執行。這些執行將處於下列其中一種狀態：**進行中**。
+ **執行歷史記錄** – 顯示已完成的執行 （即未進行）。
如需執行狀態的詳細資訊，請參閱 [工作流程執行狀態](workflows-view-run-status.md)。
## 在工作流程圖表中檢視工作流程的執行
您可以在工作流程一起進行時，檢視工作流程所有執行的狀態。執行會顯示在工作流程圖表中 （而不是在清單檢視中）。這可讓您以視覺化方式呈現哪些執行正在由哪些動作處理，以及哪些執行正在佇列中等待。
**檢視多個執行在工作流程中一起進行時的狀態**
**注意**
此程序僅適用於您的工作流程使用佇列或取代的執行模式。如需詳細資訊，請參閱[設定執行的佇列行為](workflows-configure-runs.md)。
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
**注意**
請務必查看工作流程頁面，而不是執行頁面。
1. 選擇左上角**的最新狀態**索引標籤。
工作流程圖表隨即出現。
1. 檢閱工作流程圖表。圖表顯示工作流程中目前正在進行的所有執行，以及已完成的最新執行。更具體地說：
+ 在**來源**排入佇列並等待啟動之前，出現在頂端的執行。
+ 動作之間出現的執行會排入佇列，並等待下一個動作處理。
+ 動作中出現的執行為 1. 動作目前正在處理中、2. 動作已完成處理，或 3. 動作未處理 （通常是因為先前的動作失敗）。
# 設定工作流程動作
*動作*是工作流程的主要建置區塊，並定義要在工作流程執行期間執行的邏輯工作單位或任務。一般而言，工作流程包含多個動作，這些動作會根據您設定的方式依序或平行執行。
**Topics**
+ [動作類型](#workflows-actions-types)
+ [將動作新增至工作流程](workflows-add-action.md)
+ [從工作流程移除動作](workflows-delete-action.md)
+ [開發自訂動作](workflows-custom-action.md)
+ [將動作分組為動作群組](workflows-group-actions.md)
+ [定序動作](workflows-depends-on.md)
+ [在動作之間共用成品和檔案](workflows-working-artifacts.md)
+ [指定要使用的動作版本](workflows-action-versions.md)
+ [列出可用的動作版本](workflows-action-versions-determine.md)
+ [檢視動作的原始程式碼](workflows-view-source.md)
+ [與 GitHub 動作整合](integrations-github-actions.md)
## 動作類型
在 Amazon CodeCatalyst 工作流程中，您可以使用下列類型的動作。
**Topics**
+ [CodeCatalyst 動作](#workflows-actions-types-cc)
+ [CodeCatalyst 實驗室動作](#workflows-actions-types-cc-labs)
+ [GitHub Actions](#workflows-actions-types-github)
+ [第三方動作](#workflows-actions-types-3p)
### CodeCatalyst 動作
*CodeCatalyst 動作*是由 CodeCatalyst 開發團隊撰寫、維護和完全支援的動作。
有 CodeCatalyst 動作可用來建置、測試和部署應用程式，以及執行各種任務，例如叫用 AWS Lambda 函數。
下列 CodeCatalyst 動作可供使用：
+ **建置**
此動作會建置您的成品，並在 Docker 容器中執行您的單元測試。如需詳細資訊，請參閱[新增建置動作](build-add-action.md)。
+ **測試**
此動作會針對您的應用程式或成品執行整合和系統測試。如需詳細資訊，請參閱[新增測試動作](test-add-action.md)。
+ **Amazon S3 發佈**
此動作會將您的應用程式成品複製到 Amazon S3 儲存貯體。如需詳細資訊，請參閱[使用工作流程將檔案發佈至 Amazon S3](s3-pub-action.md)。
+ **AWS CDK 引導**
此動作會佈建 部署 CDK 應用程式 AWS CDK 所需的資源。如需詳細資訊，請參閱[使用工作流程引導 AWS CDK 應用程式](cdk-boot-action.md)。
+ **AWS CDK 部署**
此動作會合成和部署 AWS Cloud Development Kit (AWS CDK) 應用程式。如需詳細資訊，請參閱[使用工作流程部署 AWS CDK 應用程式](cdk-dep-action.md)。
+ **AWS Lambda 叫用**
此動作會叫用 AWS Lambda 函數。如需詳細資訊，請參閱[使用工作流程叫用 Lambda 函數](lam-invoke-action.md)。
+ **GitHub 動作**
此動作是 *CodeCatalyst* 動作，可讓您在 CodeCatalyst 工作流程中執行 GitHub 動作。如需詳細資訊，請參閱[使用工作流程叫用 Lambda 函數](lam-invoke-action.md)。
+ **部署 CloudFormation 堆疊**
此動作會部署 CloudFormation 堆疊。如需詳細資訊，請參閱[部署 CloudFormation 堆疊](deploy-action-cfn.md)。
+ **部署至 Amazon ECS**
此動作會註冊 Amazon ECS 任務定義，並將其部署到 Amazon ECS 服務。如需詳細資訊，請參閱[使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)。
+ **部署至 Kubernetes 叢集**
此動作會將應用程式部署到 Kubernetes 叢集。如需詳細資訊，請參閱[使用工作流程部署至 Amazon EKS](deploy-action-eks.md)。
+ **轉譯 Amazon ECS 任務定義**
此動作會將容器映像 URI 插入 Amazon ECS 任務定義 JSON 檔案，建立新的任務定義檔案。如需詳細資訊，請參閱[修改 Amazon ECS 任務定義](render-ecs-action.md)。
CodeCatalyst 動作的文件可在本指南和每個動作的讀我檔案中找到。
如需可用 CodeCatalyst 動作以及如何將一個新增至工作流程的資訊，請參閱 [將動作新增至工作流程](workflows-add-action.md)。
### CodeCatalyst 實驗室動作
*CodeCatalyst Labs 動作*是 Amazon CodeCatalyst Labs 的一部分，為實驗應用程式提供了證明。已開發 CodeCatalyst 實驗室動作來展示 AWS 與服務的整合。
下列 CodeCatalyst 實驗室動作可供使用：
+ **部署至 AWS Amplify 託管**
此動作會將應用程式部署到 Amplify 託管。
+ **部署至 AWS App Runner**
此動作會將來源映像儲存庫中的最新映像部署至 App Runner。
+ **部署至 Amazon CloudFront 和 Amazon S3**
此動作會將應用程式部署到 CloudFront 和 Amazon S3。
+ **使用 部署 AWS SAM**
此動作會使用 AWS Serverless Application Model () 部署您的無伺服器應用程式AWS SAM。
+ **使 Amazon CloudFront 快取失效**
此動作會使指定路徑集的 CloudFront 快取失效。
+ **傳出 Webhook**
此動作可讓使用者使用 HTTPS 請求，將工作流程中的訊息傳送至任意 Web 伺服器。
+ **發佈至 AWS CodeArtifact**
此動作會將套件發佈至 CodeArtifact 儲存庫。
+ **發佈至 Amazon SNS**
此動作可讓使用者透過建立主題、發佈至主題或訂閱主題來與 Amazon SNS 整合。
+ **推送至 Amazon ECR**
此動作會建置 Docker 映像並將其發佈至 Amazon Elastic Container Registry (Amazon ECR) 儲存庫。
+ **使用 Amazon CodeGuru Security 進行掃描**
此動作會建立已設定程式碼路徑的 zip 封存檔，並使用 CodeGuru Security 執行程式碼掃描。
+ **Terraform Community Edition**
此動作會執行 Terraform Community Edition `plan`和 `apply` 操作。
CodeCatalyst 實驗室動作的文件可在每個動作的讀我檔案中找到。
如需將 CodeCatalyst 實驗室動作新增至工作流程和檢視其讀我檔案的詳細資訊，請參閱 [將動作新增至工作流程](workflows-add-action.md)。
### GitHub Actions
*GitHub 動作*非常類似 [CodeCatalyst 動作](#workflows-actions-types-cc)，但其開發用於 GitHub 工作流程。如需 GitHub 動作的詳細資訊，請參閱 [GitHub 動作](https://docs.github.com/en/actions)文件。
您可以在 CodeCatalyst 工作流程中使用 GitHub 動作與原生 CodeCatalyst 動作。
為了方便起見，CodeCatalyst 主控台可讓您存取數個熱門的 GitHub 動作。您也可以使用 GitHub [Marketplace 中列出的任何 GitHub ](https://github.com/marketplace/actions) 動作 （受到一些限制）。
GitHub 動作的文件可在每個動作的讀我檔案中找到。
如需詳細資訊，請參閱[與 GitHub 動作整合](integrations-github-actions.md)。
### 第三方動作
*第三方動作*是由第三方供應商撰寫，並在 CodeCatalyst 主控台中提供的動作。第三方動作的範例包括 **Mend SCA** 和 **SonarCloud Scan** 動作，分別由 Mend 和 Sonar 撰寫。
每個動作的讀我檔案都可以使用第三方動作的文件。第三方廠商也可能提供其他文件。
如需將第三方動作新增至工作流程和檢視其讀我檔案的詳細資訊，請參閱 [將動作新增至工作流程](workflows-add-action.md)。
# 將動作新增至工作流程
使用以下指示將 動作新增至工作流程，然後加以設定。
**新增和設定 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 在左上角，選擇 **\$1 動作**，即會顯示**動作**目錄。
1. 在下拉式清單中，執行下列其中一項操作：
+ 選擇 **Amazon CodeCatalyst** 以檢視 [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc)、[CodeCatalyst 實驗室 ](workflows-actions.md#workflows-actions-types-cc-labs)[或第三方](workflows-actions.md#workflows-actions-types-3p)動作。
+ CodeCatalyst 動作具有**依 AWS**標籤的 。
+ CodeCatalyst 實驗室動作具有 ** CodeCatalyst 實驗室**標籤的 。
+ 第三方動作具有**按*廠商***標籤的 ，其中*廠商*是第三方廠商的名稱。
+ 選擇 **GitHub** 以檢視 [ GitHub 動作的精選清單](integrations-github-action-add-curated.md)。
1. 在動作目錄中，搜尋動作，然後執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程。
+ 選擇動作的名稱以檢視其讀我檔案。
1. 設定 動作。選擇**視覺化**以使用視覺化編輯器，或選擇 **YAML** 以使用 YAML 編輯器。如需詳細說明，請參閱下列連結。
如需新增 [CodeCatalyst 動作](workflows-actions.md#workflows-actions-types-cc)的說明，請參閱：
+ [新增建置動作](build-add-action.md)
+ [新增測試動作](test-add-action.md)
+ [將 'Deploy 新增至 Amazon ECS' 動作](deploy-action-ecs-adding.md)
+ [將 'Deploy 新增至 Kubernetes 叢集' 動作](deploy-action-eks-adding.md)
+ [新增「部署 CloudFormation 堆疊」動作](deploy-action-cfn-adding.md)
+ [新增「AWS CDK 部署」動作](cdk-dep-action-add.md)
+ [新增 'AWS CDK bootstrap' 動作](cdk-boot-action-add.md)
+ [新增「Amazon S3 發佈」動作](s3-pub-action-add.md)
+ [新增「AWS Lambda 調用」動作](lam-invoke-action-add.md)
+ [新增「轉譯 Amazon ECS 任務定義」動作](render-ecs-action-add.md)
如需新增 [CodeCatalyst 實驗室動作](workflows-actions.md#workflows-actions-types-cc-labs)的說明，請參閱：
+ 動作的讀我檔案。您可以在動作目錄中選擇動作的名稱來尋找讀我檔案。
如需新增 [GitHub 動作](workflows-actions.md#workflows-actions-types-github)的說明，請參閱：
+ [與 GitHub 動作整合](integrations-github-actions.md)
如需新增[第三方動作](workflows-actions.md#workflows-actions-types-3p)的說明，請參閱：
+ 動作的讀我檔案。您可以在動作目錄中選擇動作的名稱來尋找讀我檔案。
1. （選用） 選擇**驗證**以確保 YAML 程式碼有效。
1. 選擇**遞交**以遞交您的變更。
# 從工作流程移除動作
使用以下指示從工作流程中移除 動作。
------
#### [ Visual ]
**使用視覺化編輯器移除動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，在您要移除的動作中，選擇垂直省略號圖示 (![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/images/flows/elipsis.png))，然後選擇**移除**。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器移除動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 尋找包含您要移除之動作的 YAML 區段。
選取 區段，然後按鍵盤上的刪除鍵。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 開發自訂動作
您可以使用 CodeCatalyst 動作開發套件 (ADK) 開發要在工作流程中使用的自訂動作。然後，您可以將動作發佈到 CodeCatalyst 動作目錄，以便其他 CodeCatalyst 使用者可以在工作流程中檢視和使用它。
**開發、測試和發佈動作 （高階任務）**
1. 安裝開發 動作所需的工具和套件。
1. 建立 CodeCatalyst 儲存庫以存放您的動作程式碼。
1. 初始化 動作。這會配置 動作所需的來源檔案，包括您可以使用自己的程式碼更新的動作定義檔案 (`action.yml`)。
1. 引導動作程式碼，以取得建置、測試和發行動作專案所需的工具和程式庫。
1. 在本機電腦上建置 動作，並將變更推送至 CodeCatalyst 儲存庫。
1. 在本機使用單元測試測試動作，並在 CodeCatalyst 中執行 ADK 產生的工作流程。
1. 選擇 CodeCatalyst 主控台中的**發佈**按鈕，將動作發佈至 CodeCatalyst 動作目錄。
如需詳細步驟，請參閱《[Amazon CodeCatalyst 動作開發套件開發人員指南](https://docs.aws.amazon.com/codecatalyst/latest/adk/what-is-action-development-kit.html)》。
# 將動作分組為動作群組
*動作群組*包含一或多個動作。將動作分組為動作群組可協助您整理工作流程，也可讓您設定不同群組之間的相依性。
**注意**
您無法在其他動作群組或動作中巢狀化動作群組。
**Topics**
+ [定義動作群組](#workflows-define-action-group)
+ [範例：定義兩個動作群組](workflows-group-actions-example.md)
## 定義動作群組
使用下列指示來定義 CodeCatalyst 動作群組。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**定義群組**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 中`Actions`，新增類似下列的程式碼：
```
Actions:
action-group-name:
Actions:
action-1:
Identifier: aws/build@v1
Configuration:
...
action-2:
Identifier: aws/build@v1
Configuration:
...
```
如需其他範例，請參閱[範例：定義兩個動作群組](workflows-group-actions-example.md)。如需詳細資訊，請參閱 中 [動作](workflow-reference.md#actions-reference)的 `action-group-name` 屬性描述[工作流程 YAML 定義](workflow-reference.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 範例：定義兩個動作群組
下列範例示範如何定義兩個 Amazon CodeCatalyst 動作群組： `BuildAndTest`和 `Deploy`。`BuildAndTest` 群組包含兩個動作 (`Build` 和 `Test`)，而`Deploy`群組也包含兩個動作 (`DeployCloudFormationStack` 和 `DeployToECS`)。
```
Actions:
BuildAndTest: # Action group 1
Actions:
Build:
Identifier: aws/build@v1
Configuration:
...
Test:
Identifier: aws/managed-test@v1
Configuration:
Deploy: #Action group 2
Actions:
DeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
Configuration:
...
DeployToECS:
Identifier: aws/ecs-deploy@v1
Configuration:
...
```
# 定序動作
根據預設，當您將動作新增至工作流程時，它們會在[視覺化編輯器](workflow.md#workflow.editors)中並排新增。這表示當您啟動工作流程執行時，動作會平行執行。如果您希望動作按順序執行 （並在視覺化編輯器中垂直顯示），您必須在它們之間設定相依性。例如，您可以設定`Test`動作來相依`Build`動作，讓測試動作在建置動作之後執行。
您可以在動作和動作群組之間設定相依性。您也可以設定one-to-many相依性，讓一個動作依賴其他幾個動作才能開始。請參閱 中的準則[在動作之間設定相依性](workflows-depends-on-set-up.md)，以確保您的相依性設定符合工作流程的 YAML 語法。
**Topics**
+ [如何在動作之間設定相依性的範例](workflows-depends-on-examples.md)
+ [在動作之間設定相依性](workflows-depends-on-set-up.md)
# 如何在動作之間設定相依性的範例
下列範例示範如何在工作流程定義檔案中設定動作和群組之間的相依性。
**Topics**
+ [範例：設定簡單的相依性](#workflows-depends-on-example-simple)
+ [範例：設定動作群組以相依於 動作](#workflows-depends-on-example-action-groups-actions)
+ [範例：設定動作群組以依賴另一個動作群組](#workflows-depends-on-example-two-action-groups)
+ [範例：設定動作群組以相依於多個動作](#workflows-depends-on-example-advanced)
## 範例：設定簡單的相依性
下列範例示範如何使用 `DependsOn` 屬性將`Test`動作設定為相依於`Build`動作。
```
Actions:
Build:
Identifier: aws/build@v1
Configuration:
...
Test:
DependsOn:
- Build
Identifier: aws/managed-test@v1
Configuration:
...
```
## 範例：設定動作群組以相依於 動作
下列範例示範如何設定`DeployGroup`動作群組以相依於 `FirstAction`動作。請注意，動作和動作群組位於相同層級。
```
Actions:
FirstAction: #An action outside an action group
Identifier: aws/github-actions-runner@v1
Configuration:
...
DeployGroup: #An action group containing two actions
DependsOn:
- FirstAction
Actions:
DeployAction1:
...
DeployAction2:
...
```
## 範例：設定動作群組以依賴另一個動作群組
下列範例顯示如何設定`DeployGroup`動作群組以相依於`BuildAndTestGroup`動作群組。請注意，動作群組位於相同層級。
```
Actions:
BuildAndTestGroup: # Action group 1
Actions:
BuildAction:
...
TestAction:
...
DeployGroup: #Action group 2
DependsOn:
- BuildAndTestGroup
Actions:
DeployAction1:
...
DeployAction2:
...
```
## 範例：設定動作群組以相依於多個動作
下列範例示範如何設定`DeployGroup`動作群組以相依於`FirstAction`動作、`SecondAction`動作以及`BuildAndTestGroup`動作群組。請注意， `DeployGroup` 與 `FirstAction`、 `SecondAction`和 位於相同層級`BuildAndTestGroup`。
```
Actions:
FirstAction: #An action outside an action group
...
SecondAction: #Another action
...
BuildAndTestGroup: #Action group 1
Actions:
Build:
...
Test:
...
DeployGroup: #Action group 2
DependsOn:
- FirstAction
- SecondAction
- BuildAndTestGroup
Actions:
DeployAction1:
...
DeployAction2:
...
```
# 在動作之間設定相依性
使用下列指示來設定工作流程中動作之間的相依性。
設定相依性時，請遵循下列準則：
+ 如果動作位於群組中，則該動作只能依賴相同群組中的其他動作。
+ 動作和動作群組可以依賴 YAML 階層中*相同層級*的其他動作和動作群組，但*不能*依賴不同層級的動作和動作群組。
------
#### [ Visual ]
**使用視覺化編輯器設定相依性**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇將相依於另一個動作的動作。
1. 選擇**輸入**索引標籤。
1. 在 **中，視 - 選用**而定，執行下列動作：
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器設定相依性**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在相依於另一個動作的動作中，新增類似下列的程式碼：
```
action-name:
DependsOn:
- action-1
```
如需更多範例，請參閱[如何在動作之間設定相依性的範例](workflows-depends-on-examples.md)。如需一般準則，請參閱 [在動作之間設定相依性](#workflows-depends-on-set-up)。如需詳細資訊，請參閱 中 [工作流程 YAML 定義](workflow-reference.md) 動作的 `DependsOn` 屬性描述。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 在動作之間共用成品和檔案
*成品*是工作流程動作的輸出，通常由資料夾或檔案封存組成。成品很重要，因為它們允許您在動作之間共用檔案和資訊。
例如，您可能有一個*產生*`sam-template.yml`檔案的建置動作，但您希望部署動作*使用*它。在此案例中，您會使用成品來允許建置動作與部署動作共用`sam-template.yml`檔案。程式碼看起來可能會像這樣：
```
Actions:
BuildAction:
Identifier: aws/build@v1
Steps:
- Run: sam package --output-template-file sam-template.yml
Outputs:
Artifacts:
- Name: MYARTIFACT
Files:
- sam-template.yml
DeployAction:
Identifier: aws/cfn-deploy@v1
Inputs:
Artifacts:
- MYARTIFACT
Configuration:
template: sam-template.yml
```
在先前的程式碼中，建置動作 (`BuildAction`) 會產生`sam-template.yml`檔案，然後將其新增至名為 的輸出成品`MYARTIFACT`。後續部署動作 (`DeployAction`) 會指定 `MYARTIFACT`做為輸入，讓它能夠存取 `sam-template.yml` 檔案。
**Topics**
+ [我是否可以共用成品，而不將其指定為輸出和輸入？](#workflows-working-artifacts-share)
+ [我可以在工作流程之間共用成品嗎？](#workflows-working-artifacts-share-wf)
+ [成品範例](workflows-working-artifacts-ex.md)
+ [定義輸出成品](workflows-working-artifacts-output.md)
+ [定義輸入成品](workflows-working-artifacts-refer.md)
+ [參考成品中的檔案](workflows-working-artifacts-refer-files.md)
+ [下載成品](workflows-download-workflow-outputs.md)
## 我是否可以共用成品，而不將其指定為輸出和輸入？
可以，您可以在動作之間共用成品，而無需在動作 YAML 程式碼的 `Outputs`和 `Inputs`區段中指定它們。若要這樣做，您必須開啟運算共用。如需運算共用以及如何在開啟時指定成品的詳細資訊，請參閱 [跨動作共用運算](compute-sharing.md)。
**注意**
雖然運算共用功能可讓您透過消除對 `Outputs`和 `Inputs`區段的需求來簡化工作流程的 YAML 程式碼，但此功能具有您在開啟它之前應注意的限制。如需這些限制的相關資訊，請參閱 [運算共用的考量](compute-sharing.md#compare-compute-sharing)。
## 我可以在工作流程之間共用成品嗎？
否，您無法在不同工作流程之間共用成品；不過，您可以在相同工作流程中的動作之間共用成品。
# 成品範例
下列範例示範如何在 Amazon CodeCatalyst 工作流程定義檔案中輸出、輸入和參考成品。
**Topics**
+ [範例：輸出成品](#workflows-working-artifacts-ex-basic)
+ [範例：輸入另一個動作產生的成品](#workflows-working-artifacts-ex-ref)
+ [範例：參考多個成品中的檔案](#workflows-working-artifacts-ex-ref-file)
+ [範例：參考單一成品中的檔案](#workflows-working-artifacts-ex-ref-file-one)
+ [範例：當 WorkflowSource 存在時，參考成品中的檔案](#workflows-working-artifacts-ex-ref-file-wf-source)
+ [範例：存在動作群組時參考成品中的檔案](#workflows-working-artifacts-ex-groups)
## 範例：輸出成品
下列範例示範如何輸出包含兩個 .jar 檔案的成品。
```
Actions:
Build:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ARTIFACT1
Files:
- build-output/file1.jar
- build-output/file2.jar
```
## 範例：輸入另一個動作產生的成品
下列範例示範如何輸出 `ARTIFACT4`中稱為 的成品`BuildActionA`，並將其輸入 `BuildActionB`。
```
Actions:
BuildActionA:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ARTIFACT4
Files:
- build-output/file1.jar
- build-output/file2.jar
BuildActionB:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ARTIFACT4
Configuration:
```
## 範例：參考多個成品中的檔案
下列範例示範如何在 `ART6`中輸出兩個名為 `ART5`和 的成品`BuildActionC`，然後在 `file5.txt`（在 下`ART5`) 中參考兩個名為 `file6.txt`（在成品 中） 和 `BuildActionD`（在成品 中`ART6`) 的檔案`Steps`。
**注意**
如需參考檔案的詳細資訊，請參閱 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
**注意**
雖然範例顯示正在使用的`$CATALYST_SOURCE_DIR_ART5`字首，但您可以省略它。這是因為 `ART5`是*主要輸入*。若要進一步了解主要輸入，請參閱 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
```
Actions:
BuildActionC:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART5
Files:
- build-output/file5.txt
- Name: ART6
Files:
- build-output/file6.txt
BuildActionD:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ART5
- ART6
Configuration:
Steps:
- run: cd $CATALYST_SOURCE_DIR_ART5/build-output && cat file5.txt
- run: cd $CATALYST_SOURCE_DIR_ART6/build-output && cat file6.txt
```
## 範例：參考單一成品中的檔案
下列範例示範如何在 `ART7`中輸出名為 的一個成品`BuildActionE`，然後在 `file7.txt`（在成品 `ART7`下） 中參考 `BuildActionF`（在成品 )`Steps`。
請注意，參考不需要`build-output`目錄前面的`$CATALYST_SOURCE_DIR_`*成品名稱*字首，就像在 中一樣[範例：參考多個成品中的檔案](#workflows-working-artifacts-ex-ref-file)。這是因為 下只有一個指定項目`Inputs`。
**注意**
如需參考檔案的詳細資訊，請參閱 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
```
Actions:
BuildActionE:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART7
Files:
- build-output/file7.txt
BuildActionF:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ART7
Configuration:
Steps:
- run: cd build-output && cat file7.txt
```
## 範例：當 WorkflowSource 存在時，參考成品中的檔案
下列範例示範如何在 `ART8`中輸出名為 的一個成品`BuildActionG`，然後在 `file8.txt`（在成品 `ART8`下） 中參考 `BuildActionH`（在成品 )`Steps`。
請注意，參考需要`$CATALYST_SOURCE_DIR_`*成品名稱*字首的方式，如同在 中一樣[範例：參考多個成品中的檔案](#workflows-working-artifacts-ex-ref-file)。這是因為在 `Inputs`（來源和成品） 下指定了多個項目，因此您需要 字首來指出在何處尋找檔案。
**注意**
如需參考檔案的詳細資訊，請參閱 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
```
Actions:
BuildActionG:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART8
Files:
- build-output/file8.txt
BuildActionH:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Artifacts:
- ART8
Configuration:
Steps:
- run: cd $CATALYST_SOURCE_DIR_ART8/build-output && cat file8.txt
```
## 範例：存在動作群組時參考成品中的檔案
下列範例示範如何輸出名為 `ActionGroup1`、 `ART9`的成品`ActionI`，然後在 中參考 `file9.txt`（成品 `ART9`)`ActionJ`。
如需參考檔案的詳細資訊，請參閱 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
```
Actions:
ActionGroup1:
Actions:
ActionI:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART9
Files:
- build-output/file9.yml
ActionJ:
Identifier: aws/cfn-deploy@v1
Inputs:
Sources:
- WorkflowSource
Artifacts:
- ART9
Configuration:
template: /artifacts/ActionGroup1@ActionJ/ART9/build-output/file9.yml
```
# 定義輸出成品
使用下列指示來定義您希望 Amazon CodeCatalyst 動作輸出的成品。然後，此成品可供其他動作使用。
**注意**
並非所有動作都支援輸出成品。若要判斷您的動作是否支援它們，請執行以下視覺化編輯器說明，並查看動作是否包含輸出索引標籤上的**輸出****成品**按鈕。如果是，則支援輸出成品。
------
#### [ Visual ]
**使用視覺化編輯器定義輸出成品**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇會產生成品的動作。
1. 選擇 **Output (輸出)** 索引標籤。
1. 在**成品**下，選擇**新增成品**。
1. 選擇**新增成品**，然後在欄位中輸入資訊，如下所示。
**組建成品名稱**
指定 動作產生的成品名稱。成品名稱在工作流程中必須是唯一的，且僅限於英數字元 (a-z、A-Z、0-9) 和底線 (\$1)。不允許使用空格、連字號 (-) 和其他特殊字元。您無法使用引號在輸出成品名稱中啟用空格、連字號和其他特殊字元。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**組建產生的檔案**
指定 CodeCatalyst 在由 動作輸出的成品中包含的檔案。這些檔案在執行時由工作流程動作產生，也可在您的來源儲存庫中使用。檔案路徑可以位於來源儲存庫或先前動作的成品中，並與來源儲存庫或成品根相關。您可以使用 glob 模式來指定路徑。範例：
+ 若要指定位於建置位置根目錄或來源儲存庫位置的單一檔案，請使用 `my-file.jar`。
+ 若要在子目錄中指定單一檔案，請使用 `directory/my-file.jar`或 `directory/subdirectory/my-file.jar`。
+ 若要指定所有檔案，請使用 `"**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要在名為 的目錄中指定所有檔案和目錄`directory`，請使用 `"directory/**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要指定目錄中名為 的所有檔案`directory`，但不是其任何子目錄，請使用 `"directory/*"`。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
您可能需要在檔案路徑中新增字首，以指出要找到它的成品或來源。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)及[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器定義輸出成品**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在工作流程動作中，新增類似下列的程式碼：
```
action-name:
Outputs:
Artifacts:
- Name: artifact-name
Files:
- file-path-1
- file-path-2
```
如需更多範例，請參閱[成品範例](workflows-working-artifacts-ex.md)。如需詳細資訊，請參閱您動作[工作流程 YAML 定義](workflow-reference.md)的 。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 定義輸入成品
如果您想要使用另一個 Amazon CodeCatalyst 動作產生的成品，您必須將其指定為目前動作的輸入。您可以指定多個成品做為輸入，這取決於 動作。如需詳細資訊，請參閱您動作[工作流程 YAML 定義](workflow-reference.md)的 。
**注意**
您無法參考來自其他工作流程的成品。
使用下列指示來指定另一個動作的成品，做為目前動作的輸入。
**先決條件**
開始之前，請確定您已從其他動作輸出成品。如需詳細資訊，請參閱[定義輸出成品](workflows-working-artifacts-output.md)。輸出成品可讓其他動作使用。
------
#### [ Visual ]
**將成品指定為動作的輸入 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要指定成品做為輸入的動作。
1. 選擇**輸入**。
1. 在**成品 - 選用**中，執行下列動作：
指定您要提供作為此動作輸入之先前動作的成品。這些成品必須已定義為先前動作中的輸出成品。
如果您未指定任何輸入成品，則必須在 下指定至少一個來源儲存庫`action-name/Inputs/Sources`。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
如果**成品 - 選用**下拉式清單無法使用 （視覺化編輯器），或者您在驗證 YAML (YAML 編輯器） 時在 中發生錯誤，可能是因為動作僅支援一個輸入。在此情況下，請嘗試移除來源輸入。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**將成品指定為動作的輸入 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在您要指定成品做為輸入的 動作中，新增類似下列的程式碼：
```
action-name:
Inputs:
Artifacts:
- artifact-name
```
如需更多範例，請參閱[成品範例](workflows-working-artifacts-ex.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 參考成品中的檔案
如果您的檔案位於成品中，而且您需要在其中一個 Amazon CodeCatalyst 工作流程動作中參考此檔案，請完成下列程序。
**注意**
另請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**參考成品中的檔案 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在您要參考檔案的動作中，新增類似下列的程式碼：
```
Actions:
My-action:
Inputs:
Sources:
- WorkflowSource
Artifacts:
- artifact-name
Configuration:
template: artifact-path/path/to/file.yml
```
在先前的程式碼中，取代：
+ *artifact-name* 與成品的名稱。
+ *artifact-path*，具有下表中的值。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/workflows-working-artifacts-refer-files.html)
如需範例，請參閱 [成品範例](workflows-working-artifacts-ex.md)。
**注意**
如果符合下列條件，您可以省略*成品路徑*，並僅指定相對於成品根目錄的檔案路徑：
您包含參考的動作只會在 下包含一個項目 `Inputs`（例如，它包含一個輸入成品且無來源）。
您要參考的檔案位於主要輸入中。如果沒有 `WorkflowSource`，*則主要輸入*為 或列出的第一個輸入成品`WorkflowSource`。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 下載成品
您可以下載並檢查 Amazon CodeCatalyst 工作流程動作所產生的成品，以進行故障診斷。您可以下載兩種類型的成品：
+ **來源成品** – 包含來源儲存庫內容快照的成品，當執行開始時已存在。
+ **工作流程成品** – 在工作流程組態檔案的 `Outputs` 屬性中定義的成品。
**下載工作流程輸出的成品**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 在工作流程的名稱下，選擇**執行**。
1. 在**執行歷史記錄**的**執行 ID** 欄中，選擇執行。例如：`Run-95a4d`。
1. 在執行的名稱下，選擇**成品**。
1. 在成品旁，選擇**下載**。封存檔案下載。其檔案名稱由七個隨機字元組成。
1. 使用您選擇的封存擷取公用程式來擷取封存。
# 指定要使用的動作版本
根據預設，當您將動作新增至工作流程時，Amazon CodeCatalyst 會使用 格式，將完整版本新增至工作流程定義檔案：
`vmajor.minor.patch`
例如：
```
My-Build-Action:
Identifier: aws/build@v1.0.0
```
您可以在 `Identifier` 屬性中縮短完整版本，讓工作流程一律使用最新的 動作次要或修補程式版本。
例如，如果您指定：
```
My-CloudFormation-Action:
Identifier: aws/cfn-deploy@v1.0
```
...且最新的修補程式版本為 `1.0.4`，則動作將使用 `1.0.4`。如果發行更新版本，請說 `1.0.5`，動作將使用 `1.0.5`。如果發行次要版本，請說 `1.1.0`，則動作將繼續使用 `1.0.5`。
如需指定版本的詳細說明，請參閱下列其中一個主題。
使用下列指示來指出您希望工作流程使用的動作版本。您可以指定最新的主要或次要版本，或特定的修補程式版本。
我們建議您使用最新的 動作次要或修補程式版本。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**設定工作流程以使用動作的最新版本或特定修補程式版本**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 尋找您要編輯其版本的動作。
1. 尋找動作的 `Identifier` 屬性，並將版本設定為下列其中一項：
+ action-identifier@v*major* – 使用此語法讓工作流程使用特定的主要版本，並允許自動選擇最新的次要和修補程式版本。
+ action-identifier@v*major*.*minor* – 使用此語法讓工作流程使用特定的次要版本，並允許自動選擇最新的修補程式版本。
+ action-identifier@v*major*.*minor*.*patch* – 使用此語法讓工作流程使用特定的修補程式版本。
**注意**
如果您不確定哪些版本可用，請參閱 [列出可用的動作版本](workflows-action-versions-determine.md)。
**注意**
您無法省略主要版本。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 列出可用的動作版本
使用下列指示來判斷您可以在工作流程中使用的動作版本。
------
#### [ Visual ]
**判斷可用的動作版本**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 尋找您要檢視其版本的動作：
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇任何工作流程的名稱，或建立一個。如需建立工作流程的詳細資訊，請參閱 [建立工作流程](workflows-create-workflow.md)。
1. 選擇**編輯**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 在下拉式清單中，選擇 **Amazon CodeCatalyst** 以檢視 CodeCatalyst、CodeCatalyst 實驗室和第三方動作，或選擇 **GitHub** 以檢視策劃的 GitHub 動作。
1. 搜尋動作，然後選擇其名稱。請勿選擇加號 (**\$1**)。
動作的詳細資訊隨即出現。
1. 在動作詳細資訊對話方塊中，靠近右上角，選擇**版本**下拉式清單以查看動作的可用版本清單。
------
#### [ YAML ]
*無法使用。選擇「視覺效果」以檢視視覺效果編輯器指示。*
------
# 檢視動作的原始程式碼
您可以檢視動作的原始程式碼，以確保它不包含有風險的程式碼、安全漏洞或其他瑕疵。
使用下列指示來檢視 [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc)、[CodeCatalyst 實驗室](workflows-actions.md#workflows-actions-types-cc-labs)[或第三方](workflows-actions.md#workflows-actions-types-3p)動作的原始程式碼。
**注意**
若要檢視 [GitHub 動作](workflows-actions.md#workflows-actions-types-github)的原始碼，請前往 [GitHub Marketplace](https://github.com/marketplace/actions) 中的動作頁面。此頁面包含動作儲存庫的連結，您可以在其中找到動作的原始程式碼。
**注意**
您無法檢視下列 CodeCatalyst 動作的原始碼：[建置](build-workflow-actions.md)、[測試](test-workflow-actions.md)、[GitHub 動作](integrations-github-action-add.md)。
**注意**
AWS 不支援或保證 GitHub 動作或第三方動作的動作程式碼。
**檢視動作的原始程式碼**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 尋找您要檢視其程式碼的動作：
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇任何工作流程的名稱，或建立一個。如需建立工作流程的詳細資訊，請參閱 [建立工作流程](workflows-create-workflow.md)。
1. 選擇**編輯**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 在下拉式清單中，選擇 **Amazon CodeCatalyst** 以檢視 CodeCatalyst、CodeCatalyst 實驗室和第三方動作。
1. 搜尋動作，然後選擇其名稱。請勿選擇加號 (**\$1**)。
動作的詳細資訊隨即出現。
1. 在動作詳細資訊對話方塊中，靠近底部，選擇**下載**。
隨即出現頁面，顯示動作原始碼所在的 Amazon S3 儲存貯體。如需 Amazon S3 的詳細資訊，請參閱[什麼是 Amazon S3？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) *Amazon Simple Storage Service 使用者指南*中的 。
1. 檢查程式碼，確保其符合您對品質和安全性的期望。
# 與 GitHub 動作整合
*GitHub 動作*非常類似 [CodeCatalyst 動作](workflows-actions.md#workflows-actions-types-cc)，但其開發用於 GitHub 工作流程。如需 GitHub 動作的詳細資訊，請參閱 [GitHub 動作](https://docs.github.com/en/actions)文件。
您可以在 CodeCatalyst 工作流程中使用 GitHub 動作與原生 CodeCatalyst 動作。
有兩種方式可將 GitHub 動作新增至 CodeCatalyst 工作流程：
+ 您可以從 CodeCatalyst 主控台的策劃清單中選取 GitHub 動作。有數個熱門的 GitHub 動作可供使用。如需詳細資訊，請參閱[新增精選的 GitHub 動作](integrations-github-action-add-curated.md)。
+ 如果您想要使用的 GitHub 動作無法在 CodeCatalyst 主控台中使用，您可以使用 **GitHub 動作**新增它。
***GitHub Actions*** 動作是 *CodeCatalyst 動作*，可包裝 GitHub 動作，使其與 CodeCatalyst 工作流程相容。
以下是包裝 [Super-Linter](https://github.com/marketplace/actions/super-linter) **GitHub 動作**的 GitHub 動作動作範例：
```
Actions:
GitHubAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: "true"
DEFAULT_BRANCH: main
```
在先前的程式碼中，CodeCatalyst **GitHub Actions** 動作 （由 識別`aws/github-actions-runner@v1`) 會包裝 Super-Linter 動作 （由 識別`github/super-linter@v4`)，使其可在 CodeCatalyst 工作流程中運作。
如需詳細資訊，請參閱[新增「GitHub 動作」動作](integrations-github-action-add.md)。
所有 GitHub 動作 - 無論是否經過策劃，都必須包裝在 **GitHub 動作**動作 (`aws/github-actions-runner@v1`) 內，如上一個範例所示。動作需要包裝函式才能正常運作。
**Topics**
+ [GitHub 動作與 CodeCatalyst 動作有何不同？](#integrations-github-actions-how-different)
+ [GitHub 動作是否可以與工作流程中的其他 CodeCatalyst 動作互動？](#integrations-github-actions-interactions.title)
+ [我可以使用哪些 GitHub 動作？](#integrations-github-actions-supported)
+ [CodeCatalyst 中 GitHub 動作的限制](#integrations-github-actions-limitations)
+ [如何新增 GitHub 動作 （高階步驟）？](#integrations-github-actions-how-to)
+ [GitHub 動作是否在 GitHub 中執行？](#integrations-github-actions-where-it-runs)
+ [也可以使用 GitHub 工作流程嗎？](#integrations-github-actions-workflows-support.title)
+ [「GitHub 動作」動作所使用的執行期映像](#integrations-github-actions-runtime)
+ [教學課程：使用 GitHub 動作的 Lint 程式碼](integrations-github-action-tutorial.md)
+ [新增「GitHub 動作」動作](integrations-github-action-add.md)
+ [新增精選的 GitHub 動作](integrations-github-action-add-curated.md)
+ [匯出 GitHub 輸出參數](integrations-github-action-export.md)
+ [參考 GitHub 輸出參數](integrations-github-action-referencing.md)
+ [「GitHub 動作」動作 YAML](github-action-ref.md)
## GitHub 動作與 CodeCatalyst 動作有何不同？
在 CodeCatalyst 工作流程中使用的 GitHub 動作與 CodeCatalyst 動作的存取和整合層級不同 AWS 和 CodeCatalyst 功能 （例如[環境](deploy-environments.md)和[問題](issues.md))。
## GitHub 動作是否可以與工作流程中的其他 CodeCatalyst 動作互動？
是。例如，GitHub Actions 可以使用其他 CodeCatalyst 動作產生的變數做為輸入，也可以與 CodeCatalyst 動作共用輸出參數和成品。如需詳細資訊，請參閱[匯出 GitHub 輸出參數](integrations-github-action-export.md)及[參考 GitHub 輸出參數](integrations-github-action-referencing.md)。
## 我可以使用哪些 GitHub 動作？
您可以使用 CodeCatalyst 主控台提供的任何 GitHub 動作，以及 GitHub [Marketplace 中提供的任何 GitHub ](https://github.com/marketplace/actions)動作。如果您決定從 Marketplace 使用 GitHub 動作，請記住下列[限制](#integrations-github-actions-limitations)。
## CodeCatalyst 中 GitHub 動作的限制
+ GitHub 動作無法與 CodeCatalyst [Lambda 運算類型](workflows-working-compute.md#compute.types)搭配使用。
+ GitHub 動作會在 [2022 年 11 月](build-images.md#build.previous-image)執行時間環境 Docker 映像上執行，其中包含較舊的工具。如需映像和工具的詳細資訊，請參閱 [指定執行時間環境映像](build-images.md)。
+ 內部依賴[`github`內容](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context)或參考 GitHub 特定資源的 GitHub 動作無法在 CodeCatalyst 中運作。例如，下列動作無法在 CodeCatalyst 中運作：
+ 嘗試新增、變更或更新 GitHub 資源的動作。範例包括更新提取請求的動作，或在 GitHub 中建立問題。
+ 幾乎所有列於 https：//[https://github.com/actions](https://github.com/actions) 的動作。
+ 屬於 Docker 容器動作的 GitHub 動作將可運作，但必須由預設的 Docker 使用者 （根） 執行。 [https://docs.github.com/en/actions/creating-actions/about-custom-actions#docker-container-actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#docker-container-actions)請勿以使用者 1001 身分執行動作。（撰寫時，使用者 1001 可在 GitHub 中運作，但無法在 CodeCatalyst.) 如需詳細資訊，請參閱 [Dockerfile 支援 GitHub 動作](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions)中的 [USER](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions#user) 主題。
如需透過 CodeCatalyst 主控台提供的 GitHub 動作清單，請參閱 [新增精選的 GitHub 動作](integrations-github-action-add-curated.md)。
## 如何新增 GitHub 動作 （高階步驟）？
將 GitHub 動作新增至 CodeCatalyst 工作流程的高階步驟如下所示：
1. 在 CodeCatalyst 專案中，您可以**建立工作流程**。工作流程是您定義如何建置、測試和部署應用程式的地方。如需詳細資訊，請參閱[工作流程入門](workflows-getting-started.md)。
1. 在工作流程中，您可以**新增策劃的 GitHub 動作**，或**新增 GitHub 動作**動作。
1. 您執行下列其中一項操作：
+ 如果您選擇新增策劃的動作，請進行設定。如需詳細資訊，請參閱[新增精選的 GitHub 動作](integrations-github-action-add-curated.md)。
+ 如果您選擇新增非策劃的動作，請在 **GitHub 動作**動作中**貼上 GitHub 動作的 YAML 程式碼**。您可以在 GitHub [GitHub Marketplace](https://github.com/marketplace/actions) 中所選 GitHub 動作的詳細資訊頁面上找到此程式碼。您可能需要稍微修改程式碼，才能在 CodeCatalyst 中運作。如需詳細資訊，請參閱[新增「GitHub 動作」動作](integrations-github-action-add.md)。
1. （選用） 在工作流程中，**您可以新增其他動作**，例如建置和測試動作。如需詳細資訊，請參閱[使用工作流程建置、測試和部署使用工作流程建置、測試和部署](workflow.md)。
1. 您可以透過觸發手動或自動**啟動工作流程**。工作流程會執行 GitHub 動作和工作流程中的任何其他動作。如需詳細資訊，請參閱[手動啟動工作流程執行](workflows-manually-start.md)。
如需詳細步驟，請參閱：
+ [新增精選的 GitHub 動作](integrations-github-action-add-curated.md).
+ [新增「GitHub 動作」動作](integrations-github-action-add.md).
## GitHub 動作是否在 GitHub 中執行？
否。GitHub 動作會使用 CodeCatalyst 的[執行期環境映像](workflows-working-compute.md)，在 CodeCatalyst 中執行。
## 也可以使用 GitHub 工作流程嗎？
否。
## 「GitHub 動作」動作所使用的執行期映像
CodeCatalyst **GitHub 動作**會在 [2022 年 11 月映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 教學課程：使用 GitHub 動作的 Lint 程式碼
在本教學課程中，您將[超級層 GitHub 動作](https://github.com/marketplace/actions/super-linter)新增至 Amazon CodeCatalyst 工作流程。Super-Linter 動作會檢查程式碼、尋找程式碼發生錯誤、格式化問題和可疑建構的區域，然後將結果輸出到 CodeCatalyst 主控台）。將 linter 新增至工作流程後，您會執行工作流程，將範例 Node.js 應用程式 (`app.js`) 內嵌。然後，您可以修正報告的問題，並再次執行工作流程，以查看修正是否有效。
**提示**
考慮使用 Super-Linter 來內嵌 YAML 檔案，例如 [CloudFormation 範本](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)。
**Topics**
+ [先決條件](#integrations-github-action-tutorial-prereqs)
+ [步驟 1：建立來源儲存庫](#integrations-github-action-tutorial-create-source-repo)
+ [步驟 2：新增 app.js 檔案](#integrations-github-action-tutorial-add-appjs)
+ [步驟 3：建立執行 Super-Linter 動作的工作流程](#integrations-github-action-tutorial-create-workflow)
+ [步驟 4：修正 Super-Linter 發現的問題](#integrations-github-action-tutorial-fix-probs)
+ [清除](#integrations-github-action-tutorial-cleanup)
## 先決條件
開始之前，您將需要：
+ 已連線的 CodeCatalyst **空間** AWS 帳戶。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ CodeCatalyst 空間中的空專案，稱為 `codecatalyst-linter-project`。選擇**從頭開始**選項以建立此專案。
```
```
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
## 步驟 1：建立來源儲存庫
在此步驟中，您會在 CodeCatalyst 中建立來源儲存庫。您將使用此儲存庫來存放`app.js`本教學課程的範例應用程式來源檔案 。
如需來源儲存庫的詳細資訊，請參閱 [建立來源儲存庫](source-repositories-create.md)。
**建立來源儲存庫**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 導覽至您的專案 `codecatalyst-linter-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇**新增儲存庫**，然後選擇**建立儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
codecatalyst-linter-source-repository
```
1. 選擇**建立**。
## 步驟 2：新增 app.js 檔案
在此步驟中，您會將 `app.js` 檔案新增至來源儲存庫。`app.js` 包含函數程式碼，其中有一些 linter 會發現的錯誤。
**新增 app.js 檔案**
1. 在 CodeCatalyst 主控台中，選擇您的專案 `codecatalyst-linter-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 從來源儲存庫清單中，選擇您的儲存庫 `codecatalyst-linter-source-repository`。
1. 在**檔案中**，選擇**建立檔案**。
1. 在文字方塊中，輸入下列程式碼：
```
// const axios = require('axios')
// const url = 'http://checkip.amazonaws.com/';
let response;
/**
*
* Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
* @param {Object} event - API Gateway Lambda Proxy Input Format
*
* Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html
* @param {Object} context
*
* Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
* @returns {Object} object - API Gateway Lambda Proxy Output Format
*
*/
exports.lambdaHandler = async (event, context) => {
try {
// const ret = await axios(url);
response = {
statusCode: 200,
'body': JSON.stringify({
message: 'hello world'
// location: ret.data.trim()
})
}
} catch (err) {
console.log(err)
return err
}
return response
}
```
1. 針對**檔案名稱**，輸入 `app.js`。保留其他預設選項。
1. 選擇 **Commit** (遞交)。
您現在已建立名為 的檔案`app.js`。
## 步驟 3：建立執行 Super-Linter 動作的工作流程
在此步驟中，您會建立工作流程，在將程式碼推送至來源儲存庫時執行 Super-Linter 動作。工作流程包含下列建置區塊，您在 YAML 檔案中定義：
+ **觸發**條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **「GitHub 動作」動作** – 在觸發時，**GitHub 動作**動作會執行超級互動動作，進而檢查來源儲存庫中的所有檔案。如果 linter 發現問題，工作流程動作會失敗。
**建立執行 Super-Linter 動作的工作流程**
1. 在 CodeCatalyst 主控台中，選擇您的專案 `codecatalyst-linter-project`。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 針對**來源儲存庫**，選擇 `codecatalyst-linter-source-repository`。
1. 針對**分支**，選擇 `main`。
1. 選擇**建立**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML：
```
Name: codecatalyst-linter-workflow
SchemaVersion: "1.0"
Triggers:
- Type: PUSH
Branches:
- main
Actions:
SuperLinterAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
github-action-code
```
在上述程式碼中，將 *github-action-code* 取代為 Super-Linter 動作程式碼，如此程序的下列步驟所述。
1. 前往 GitHub Marketplace 中的 [Super-Linter 頁面](https://github.com/marketplace/actions/super-linter)。
1. 在 `steps:`（小寫） 下，尋找程式碼並將其貼到 `Steps:`（大寫） 下的 CodeCatalyst 工作流程中。
調整 GitHub 動作程式碼以符合 CodeCatalyst 標準，如下列程式碼所示。
您的 CodeCatalyst 工作流程現在如下所示：
```
Name: codecatalyst-linter-workflow
SchemaVersion: "1.0"
Triggers:
- Type: PUSH
Branches:
- main
Actions:
SuperLinterAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: "true"
DEFAULT_BRANCH: main
```
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇**遞交**，輸入**遞交訊息**，選擇您的`codecatalyst-linter-source-repository`**儲存庫**，然後再次選擇**遞交**。
您現在已建立工作流程。由於工作流程頂端定義的觸發條件，工作流程執行會自動啟動。
**檢視進行中工作流程執行**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇您剛建立的工作流程：`codecatalyst-linter-workflow`。
1. 在工作流程圖表中，選擇 **SuperLinterAction**。
1. 等待動作失敗。預期會發生此失敗，因為 linter 在程式碼中發現問題。
1. 保持 CodeCatalyst 主控台開啟，並前往 [步驟 4：修正 Super-Linter 發現的問題](#integrations-github-action-tutorial-fix-probs)。
## 步驟 4：修正 Super-Linter 發現的問題
Super-Linter 應該在`app.js`程式碼以及來源儲存庫中包含`README.md`的檔案中找到問題。
**修正 linter 找到的問題**
1. 在 CodeCatalyst 主控台中，選擇 **Logs** 索引標籤，然後選擇 **Lint Code Base**。
隨即顯示超級燒錄動作產生的日誌。
1. 在 Super-Linter 日誌中，向下捲動到行 90 周圍，您可以在其中找到問題的起點。它們看起來類似以下內容：
```
/github/workspace/hello-world/app.js:3:13: Extra semicolon.
/github/workspace/hello-world/app.js:9:92: Trailing spaces not allowed.
/github/workspace/hello-world/app.js:21:7: Unnecessarily quoted property 'body' found.
/github/workspace/hello-world/app.js:31:1: Expected indentation of 2 spaces but found 4.
/github/workspace/hello-world/app.js:32:2: Newline required at end of file but not found.
```
1. 修正來源儲存庫`README.md`中的 `app.js` 和 ，並遞交您的變更。
**提示**
若要修正 `README.md`，請將 `markdown`新增至程式碼區塊，如下所示：
```
```markdown
Setup examples:
...
```
```
您的變更會自動開始另一個工作流程執行。等待工作流程完成。如果您修正所有問題，工作流程應該會成功。
## 清除
在 CodeCatalyst 中清除 ，以從環境中移除此教學課程的追蹤。
**在 CodeCatalyst 中清除**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 刪除 `codecatalyst-linter-source-repository`。
1. 刪除 `codecatalyst-linter-workflow`。
在本教學課程中，您已了解如何將超級層 GitHub 動作新增至 CodeCatalyst 工作流程，以便內嵌一些程式碼。
# 新增「GitHub 動作」動作
***GitHub 動作***動作是 *CodeCatalyst 動作*，可包裝 GitHub 動作，使其與 CodeCatalyst 工作流程相容。
如需詳細資訊，請參閱[與 GitHub 動作整合](integrations-github-actions.md)。
若要將 **GitHub 動作**動作新增至工作流程，請遵循下列步驟。
**提示**
如需說明如何使用 **GitHub 動作**動作的教學課程，請參閱 [教學課程：使用 GitHub 動作的 Lint 程式碼](integrations-github-action-tutorial.md)。
------
#### [ Visual ]
**使用視覺化編輯器新增「GitHub 動作」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **GitHub**。
1. 搜尋 **GitHub 動作**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 **GitHub 動作**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「GitHub 動作」動作 YAML](github-action-ref.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增「GitHub 動作」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中選擇 **GitHub**。
1. 搜尋 **GitHub 動作**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 **GitHub 動作**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「GitHub 動作」動作 YAML](github-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 「GitHub 動作」動作定義
**GitHub 動作**定義為工作流程定義檔案內的一組 YAML 屬性。如需這些屬性的詳細資訊，請參閱 [「GitHub 動作」動作 YAML](github-action-ref.md) 中的 [工作流程 YAML 定義](workflow-reference.md)。
# 新增精選的 GitHub 動作
*策劃的 GitHub 動作*是在 CodeCatalyst 主控台中提供的 GitHub 動作，做為如何在 CodeCatalyst 工作流程中使用 GitHub 動作的範例。
統籌 GitHub 動作包裝在 CodeCatalyst 撰寫的 [**GitHub 動作**](integrations-github-action-add.md)中，以識別`aws/github-actions-runner@v1`符識別。例如，以下是精選 GitHub 動作 [TruffleHog OSS](https://github.com/marketplace/actions/trufflehog-oss) 的外觀：
```
Actions:
TruffleHogOSS_e8:
Identifier: aws/github-actions-runner@v1
Inputs:
Sources:
- WorkflowSource # This specifies that the action requires this Workflow as a source
Configuration:
Steps:
- uses: trufflesecurity/trufflehog@v3.16.0
with:
path: ' ' # Required; description: Repository path
base: ' ' # Required; description: Start scanning from here (usually main branch).
head: ' ' # Optional; description: Scan commits until here (usually dev branch).
extra_args: ' ' # Optional; description: Extra args to be passed to the trufflehog cli.
```
在先前的程式碼中，CodeCatalyst **GitHub Actions** 動作 （由 識別`aws/github-actions-runner@v1`) 會包裝 TruffleHog OSS 動作 （由 識別`trufflesecurity/trufflehog@v3.16.0`)，使其可在 CodeCatalyst 工作流程中運作。
若要設定此動作，您可以將 下的空字串取代`with:`為您自己的值。例如：
```
Actions:
TruffleHogOSS_e8:
Identifier: aws/github-actions-runner@v1
Inputs:
Sources:
- WorkflowSource # This specifies that the action requires this Workflow as a source
Configuration:
Steps:
- uses: trufflesecurity/trufflehog@v3.16.0
with:
path: ./
base: main # Required; description: Start scanning from here (usually main branch).
head: HEAD # Optional; description: Scan commits until here (usually dev branch).
extra_args: '‐‐debug ‐‐only-verified' # Optional; description: Extra args to be passed to the trufflehog cli.
```
若要將精選的 GitHub 動作新增至工作流程，請使用下列程序。如需在 CodeCatalyst 工作流程中使用 GitHub 動作的一般資訊，請參閱 [與 GitHub 動作整合](integrations-github-actions.md)。
**注意**
如果您在策劃的動作清單中看不到 GitHub 動作，您仍然可以使用 **GitHub 動作**將其新增至工作流程。如需詳細資訊，請參閱[新增「GitHub 動作」動作](integrations-github-action-add.md)。
------
#### [ Visual ]
**使用視覺化編輯器新增策劃的 GitHub 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **GitHub**。
1. 瀏覽或搜尋 GitHub 動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 GitHub 動作的名稱。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**、**組態**和**輸出**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「GitHub 動作」動作 YAML](github-action-ref.md)。此參考提供有關 **GitHub 動作**動作可用的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊，因為它會顯示在 YAML 和視覺化編輯器中。
如需適用於精選 GitHub 動作之組態選項的相關資訊，請參閱其文件。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增策劃的 GitHub 動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **GitHub**。
1. 瀏覽或搜尋 GitHub 動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇 GitHub 動作的名稱。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。有關 **GitHub 動作**動作可用的每個屬性的說明，請參閱 [「GitHub 動作」動作 YAML](github-action-ref.md)。
如需適用於精選 GitHub 動作之組態選項的相關資訊，請參閱其文件。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 匯出 GitHub 輸出參數
您可以在 CodeCatalyst 工作流程中使用 [GitHub 輸出參數](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter)。
**注意**
*輸出參數*的另一個單字是*可變*的。由於 GitHub 在其文件中使用 術語*輸出參數*，因此我們也會使用此術語。
使用下列指示從 GitHub 動作匯出 GitHub 輸出參數，以便供其他 CodeCatalyst 工作流程動作使用。
**匯出 GitHub 輸出參數**
1. 開啟工作流程，然後選擇**編輯**。如需詳細資訊，請參閱[建立工作流程](workflows-create-workflow.md)。
1. 在產生您要匯出的輸出參數的 **GitHub 動作**動作中，新增具有如下所示之基礎`Variables`屬性的 `Outputs`區段：
```
Actions:
MyGitHubAction:
Identifier: aws/github-actions-runner@v1
Outputs:
Variables:
- 'step-id_output-name'
```
取代：
+ *step-id*，其值為 GitHub 動作`steps`區段中的 `id:` 屬性。
+ *output-name* 與 GitHub 輸出參數的名稱。
**範例**
下列範例說明如何匯出名為 的 GitHub 輸出參數`SELECTEDCOLOR`。
```
Actions:
MyGitHubAction:
Identifier: aws/github-actions-runner@v1
Outputs:
Variables:
- 'random-color-generator_SELECTEDCOLOR'
Configuration:
Steps:
- name: Set selected color
run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
id: random-color-generator
```
# 參考 GitHub 輸出參數
使用下列指示來參考 GitHub 輸出參數。
**參考 GitHub 輸出參數**
1. 完成「[匯出 GitHub 輸出參數](integrations-github-action-export.md)」中的步驟。
GitHub 輸出參數現在可用於其他動作。
1. 請記下輸出參數`Variables`的值。它包含底線 (\$1)。
1. 使用下列語法參考輸出參數：
```
${action-name.output-name}
```
取代：
+ *action-name* 與產生輸出參數的 CodeCatalyst **GitHub 動作**名稱 （請勿使用 GitHub 動作的 `name`或 `id`)。
+ *output-name* 以及您稍早記下的輸出參數`Variables`值。
**範例**
```
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: echo ${MyGitHubAction.random-color-generator_SELECTEDCOLOR}
```
**具有內容的範例**
下列範例示範如何在 中設定`SELECTEDCOLOR`變數`GitHubActionA`、輸出變數，然後在 中參考變數`BuildActionB`。
```
Actions:
GitHubActionA:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Set selected color
run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
id: random-color-generator
Outputs:
Variables:
- 'random-color-generator_SELECTEDCOLOR'
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: echo ${GitHubActionA.random-color-generator_SELECTEDCOLOR}
```
# 「GitHub 動作」動作 YAML
以下是 **GitHub 動作**的 YAML 定義。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
在下列程式碼中選擇 YAML 屬性，以查看描述。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
action-name:
Identifier: aws/github-actions-runner@v1
DependsOn:
- dependent-action-name-1
Compute:
Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Inputs:
Sources:
- source-name-1
- source-name-2
Artifacts:
- artifact-name
Variables:
- Name: variable-name-1
Value: variable-value-1
- Name: variable-name-2
Value: variable-value-2
Outputs:
Artifacts:
- Name: output-artifact-1
Files:
- github-output/artifact-1.jar
- "github-output/build*"
- Name: output-artifact-2
Files:
- github-output/artifact-2.1.jar
- github-output/artifact-2.2.jar
Variables:
- variable-name-1
- variable-name-2
AutoDiscoverReports:
Enabled: true | false
ReportNamePrefix: AutoDiscovered
IncludePaths:
- "**/*"
ExcludePaths:
- node_modules/cdk/junit.xml
SuccessCriteria:
PassRate: percent
LineCoverage: percent
BranchCoverage: percent
Vulnerabilities:
Severity: CRITICAL|HIGH|MEDIUM|LOW|INFORMATIONAL
Number: whole-number
Reports:
report-name-1:
Format: format
IncludePaths:
- "*.xml"
ExcludePaths:
- report2.xml
- report3.xml
SuccessCriteria:
PassRate: percent
LineCoverage: percent
BranchCoverage: percent
Vulnerabilities:
Severity: CRITICAL|HIGH|MEDIUM|LOW|INFORMATIONAL
Number: whole-number
Configuration
Steps:
- github-actions-code
```
## action-name
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
對應的 UI：組態索引標籤/*action-name*
## Identifier
(*action-name*/**Identifier**)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
將 `aws/github-actions-runner@v1`用於 **GitHub 動作**。
對應的 UI：工作流程圖表/*action-name*/**aws/github-actions-runner@v1** 標籤
## DependsOn
(*action-name*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*action-name*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在相同的執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Fleet
(*action-name*/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`。
對應的 UI：組態索引標籤/**運算機群 - 選用**
## Timeout
(*action-name*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Environment
(*action-name*/**Environment**)
(選用)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*action-name*/Environment/**Name**)
（如果[Environment](#github.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*action-name*/Environment/**Connections**)
(選用)
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
## Name
(*action-name*/Environment/Connections/**Name**)
（如果[Connections](#github.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：組態tab/Environment/What*我的環境*是什麼？/三個點功能表/**切換角色**
## Role
(*action-name*/Environment/Connections/**Role**)
（如果[Connections](#github.environment.connections)包含 則為必要）
指定此動作用於在 Amazon S3 和 Amazon ECR 等 AWS 服務中存取和操作的 IAM 角色名稱。請確定此角色已新增至您 AWS 帳戶 空間中的連線。若要將 IAM 角色新增至帳戶連線，請參閱 [新增 IAM 角色至帳戶連線](ipa-connect-account-addroles.md)。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
**注意**
您可以搭配此動作使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
**警告**
將許可限制為 **GitHub 動作**所需的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
對應的 UI：組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
## Inputs
(*action-name*/**Inputs**)
(選用)
`Inputs` 區段定義 動作在工作流程執行期間所需的資料。
**注意**
每個 **GitHub 動作**最多允許四個輸入 （一個來源和三個成品）。變數不會計入此總計。
如果您需要參考位於不同輸入中的檔案 （例如來源和成品），則來源輸入是主要輸入，而成品是次要輸入。對次要輸入中檔案的參考需要特殊的字首，才能將其從主要輸入中消除。如需詳細資訊，請參閱[範例：參考多個成品中的檔案](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file)。
對應的 UI：**輸入**索引標籤
## Sources
(*action-name*/Inputs/**Sources**)
(選用)
指定代表 動作所需來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`，代表儲存工作流程定義檔案的來源儲存庫。
如果您省略來源，則必須在 下指定至少一個輸入成品`action-name/Inputs/Artifacts`。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*action-name*/Inputs/**Artifacts**)
(選用)
指定您要提供作為此動作輸入之先前動作的成品。這些成品必須已定義為先前動作中的輸出成品。
如果您未指定任何輸入成品，則必須在 下指定至少一個來源儲存庫`action-name/Inputs/Sources`。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
如果**成品 - 選用**下拉式清單無法使用 （視覺化編輯器），或者您在驗證 YAML (YAML 編輯器） 時在 中發生錯誤，可能是因為動作僅支援一個輸入。在此情況下，請嘗試移除來源輸入。
對應的 UI：輸入索引標籤/**成品 - 選用**
## Variables - input
(*action-name*/Inputs/**Variables**)
(選用)
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸入索引標籤/**變數 - 選用**
## Outputs
(*action-name*/**Outputs**)
(選用)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts - output
(*action-name*/Outputs/**Artifacts**)
(選用)
指定 動作產生的成品名稱。成品名稱在工作流程中必須是唯一的，且僅限於英數字元 (a-z、A-Z、0-9) 和底線 (\$1)。不允許使用空格、連字號 (-) 和其他特殊字元。您無法使用引號在輸出成品名稱中啟用空格、連字號和其他特殊字元。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/**成品**
## Name
(*action-name*/Outputs/Artifacts/**Name**)
（如果[Artifacts - output](#github.outputs.artifacts)包含 則為必要）
指定 動作產生的成品名稱。成品名稱在工作流程中必須是唯一的，且僅限於英數字元 (a-z、A-Z、0-9) 和底線 (\$1)。不允許使用空格、連字號 (-) 和其他特殊字元。您無法使用引號在輸出成品名稱中啟用空格、連字號和其他特殊字元。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出tab/Artifacts/Add成品/**建置成品名稱**
## Files
(*action-name*/Outputs/Artifacts/**Files**)
（如果[Artifacts - output](#github.outputs.artifacts)包含 則為必要）
指定 CodeCatalyst 在由 動作輸出的成品中包含的檔案。這些檔案在執行時由工作流程動作產生，也可在您的來源儲存庫中使用。檔案路徑可以位於來源儲存庫或先前動作的成品中，並與來源儲存庫或成品根相關。您可以使用 glob 模式來指定路徑。範例：
+ 若要指定位於建置位置根目錄或來源儲存庫位置的單一檔案，請使用 `my-file.jar`。
+ 若要在子目錄中指定單一檔案，請使用 `directory/my-file.jar`或 `directory/subdirectory/my-file.jar`。
+ 若要指定所有檔案，請使用 `"**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要在名為 的目錄中指定所有檔案和目錄`directory`，請使用 `"directory/**/*"`。`**` 全域模式表示 符合任意數量的子目錄。
+ 若要指定目錄中名為 的所有檔案`directory`，但不是其任何子目錄，請使用 `"directory/*"`。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
**注意**
您可能需要在檔案路徑中新增字首，以指出要找到它的成品或來源。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)及[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：輸出tab/Artifacts/Add**建置產生的成品/檔案**
## Variables - output
(*action-name*/Outputs/**Variables**)
(選用)
指定您希望動作匯出的變數，以便可供後續動作使用。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸出索引標籤/變數/**新增變數**
## variable-name-1
(*action-name*/Outputs/Variables**variable-name-1**)
(選用)
指定您要動作匯出的變數名稱。此變數必須已在相同動作的 `Inputs`或 `Steps`區段中定義。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸出tab/Variables/Add變數/**名稱**
## AutoDiscoverReports
(*action-name*/Outputs/**AutoDiscoverReports**)
(選用)
定義自動探索功能的組態。
當您啟用自動探索時，CodeCatalyst 會搜尋所有`Inputs`傳遞至動作的所有檔案，以及動作本身所產生的所有檔案，尋找測試、程式碼涵蓋範圍和軟體合成分析 (SCA) 報告。對於找到的每個報告，CodeCatalyst 會將其轉換為 CodeCatalyst 報告。*CodeCatalyst 報告*是完全整合到 CodeCatalyst 服務的報告，可以透過 CodeCatalyst 主控台檢視和操作。
**注意**
根據預設，自動探索功能會檢查所有檔案。您可以使用 [IncludePaths](#github.reports.includepaths)或 [ExcludePaths](#github.reports.excludepaths) 屬性來限制要檢查哪些檔案。
對應的 UI：*無*
## Enabled
(*action-name*/Outputs/AutoDiscoverReports/**Enabled**)
(選用)
啟用或停用自動探索功能。
有效值為 `true` 或 `false`。
如果省略 `Enabled` ，則預設值為 `true`。
對應的 UI：輸出索引標籤/報告/**自動探索報告**
## ReportNamePrefix
(*action-name*/Outputs/AutoDiscoverReports/**ReportNamePrefix**)
（如果 [AutoDiscoverReports](#github.outputs.autodiscover) 已包含並啟用，則為必要項目）
指定 CodeCatalyst 在找到的所有報告前面加上的字首，以命名其相關聯的 CodeCatalyst 報告。例如，如果您指定字首 `AutoDiscovered`，而 CodeCatalyst 會自動探索兩個測試報告 `TestSuiteOne.xml`和 `TestSuiteTwo.xml`，則相關聯的 CodeCatalyst 報告將命名為 `AutoDiscoveredTestSuiteOne`和 `AutoDiscoveredTestSuiteTwo`。
對應的 UI：輸出tab/Reports/Automatically探索報告/**報告字首**
## IncludePaths
(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)
（如果 [AutoDiscoverReports](#github.outputs.autodiscover)包含並啟用，或如果 [Reports](#github.configuration.reports) 包含，則為必要）
指定 CodeCatalyst 在搜尋原始報告時包含的檔案和檔案路徑。例如，如果您指定 `"/test/report/*"`，CodeCatalyst 會搜尋尋找`/test/report/*`目錄的動作所使用的整個[建置映像](build-images.md)。找到該目錄時，CodeCatalyst 接著會尋找該目錄中的報告。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
如果省略此屬性，預設值為 `"**/*"`，表示搜尋包含所有路徑的所有檔案。
**注意**
對於手動設定的報告， `IncludePaths` 必須是符合單一檔案的 glob 模式。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/'包含/排除路徑'/**包含路徑**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/'Include/excde paths'/**Include paths**
## ExcludePaths
(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**ExcludePaths**)
(選用)
指定 CodeCatalyst 在搜尋原始報告時排除的檔案和檔案路徑。例如，如果您指定 `"/test/my-reports/**/*"`，CodeCatalyst 不會搜尋 `/test/my-reports/`目錄中的檔案。若要忽略目錄中的所有檔案，請使用 `**/*` glob 模式。
**注意**
如果您的檔案路徑包含一或多個星號 (`*`) 或其他特殊字元，請以雙引號 () 括住路徑`""`。如需特殊字元的詳細資訊，請參閱 [語法準則和慣例](workflow-reference.md#workflow.terms.syntax.conv)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/'包含/排除路徑'/**排除路徑**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/'Include/exclude paths'/**Exclude paths**
## SuccessCriteria
(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)
或
(*action-name*/Outputs/Reports/*report-name-1*/**SuccessCriteria**)
(選用)
指定測試、程式碼涵蓋範圍、軟體合成分析 (SCA) 和靜態分析 (SA) 報告的成功條件。
如需詳細資訊，請參閱[設定報告的成功條件](test-config-action.md#test.success-criteria)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/**成功條件**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/**成功條件**
## PassRate
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**PassRate**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)
(選用)
指定測試報告中必須傳遞的測試百分比，相關 CodeCatalyst 報告才能標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。通過率條件僅適用於測試報告。如需測試報告的詳細資訊，請參閱 [測試報告](test-workflow-actions.md#test-reports)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/成功條件/**通過率**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/成功條件/**通過率**
## LineCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**LineCoverage**)
(選用)
指定程式碼涵蓋範圍報告中必須涵蓋的行數百分比，以便將相關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。明細涵蓋範圍條件只會套用至程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/成功條件/**行涵蓋範圍**
+ Outputs tab/Reports/Manually configure report/*report-name-1*/Success criteria/**Line coverage**
## BranchCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**BranchCoverage**)
(選用)
指定程式碼涵蓋範圍報告中必須涵蓋的分支百分比，以便將關聯的 CodeCatalyst 報告標示為已傳遞。有效值包括小數位數。例如：`50`、`60.5`。分支涵蓋範圍條件僅適用於程式碼涵蓋範圍報告。如需程式碼涵蓋範圍報告的詳細資訊，請參閱 [程式碼涵蓋範圍報告](test-workflow-actions.md#test-code-coverage-reports)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/成功條件/**分支涵蓋範圍**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/成功條件/**分支涵蓋範圍**
## Vulnerabilities
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**)
或
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)
(選用)
針對要標示為已傳遞的相關聯 CodeCatalyst 報告，指定 SCA 報告中允許的漏洞數量和嚴重性上限。若要指定漏洞，您必須指定：
+ 您要包含在計數中的漏洞最低嚴重性。從最嚴重到最不嚴重的有效值為：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL`。
例如，如果您選擇 `HIGH`，則 `HIGH`和 `CRITICAL` 漏洞將會很高。
+ 您想要允許之指定嚴重性的漏洞數量上限。超過此數字會導致 CodeCatalyst 報告標示為失敗。有效值為整數。
漏洞條件只會套用至 SCA 報告。如需 SCA 報告的詳細資訊，請參閱 [軟體合成分析報告](test-workflow-actions.md#test-sca-reports)。
若要指定最低嚴重性，請使用 `Severity` 屬性。若要指定漏洞數量上限，請使用 `Number` 屬性。
如需 SCA 報告的詳細資訊，請參閱 [品質報告類型](test-workflow-actions.md#test-reporting)。
對應的 UI：
+ 輸出tab/Reports/Automatically探索報告/成功條件/**漏洞**
+ 輸出tab/Reports/Manually設定報告/*report-name-1*/成功條件/**漏洞**
## Reports
(*action-name*/Outputs/**Reports**)
(選用)
指定測試報告組態的區段。
對應的 UI：輸出索引標籤/**報告**
## report-name-1
(*action-name*/Outputs/Reports/**report-name-1**)
（如果[Reports](#github.configuration.reports)包含 則為必要）
您要提供給 CodeCatalyst 報告的名稱，該報告將從原始報告產生。
對應的 UI：輸出tab/Reports/Manually設定報告/**報告名稱**
## Format
(*action-name*/Outputs/Reports/*report-name-1*/**Format**)
（如果[Reports](#github.configuration.reports)包含 則為必要）
指定您用於報告的檔案格式。可能的值如下。
+ 對於測試報告：
+ 針對 Cucumber JSON，指定 **Cucumber** （視覺化編輯器） 或 `CUCUMBERJSON`(YAML 編輯器）。
+ 針對 JUnit XML，指定 **JUnit** （視覺化編輯器） 或 `JUNITXML`(YAML 編輯器）。
+ 對於 NUnit XML，指定 **NUnit** （視覺化編輯器） 或 `NUNITXML`(YAML 編輯器）。
+ 對於 NUnit 3 XML，指定 **NUnit3** （視覺化編輯器） 或 `NUNIT3XML`(YAML 編輯器）。
+ 針對 Visual Studio TRX，指定 **Visual Studio TRX** （視覺化編輯器） 或 `VISUALSTUDIOTRX`(YAML 編輯器）。
+ 針對 TestNG XML，指定 **TestNG** （視覺化編輯器） 或 `TESTNGXML`(YAML 編輯器）。
+ 對於程式碼涵蓋範圍報告：
+ 對於 Clover XML，指定 **Clover** （視覺化編輯器） 或 `CLOVERXML`(YAML 編輯器）。
+ 對於 Cobertura XML，指定 **Cobertura** （視覺編輯器） 或 `COBERTURAXML`(YAML 編輯器）。
+ 對於 JaCoCo XML，指定 **JaCoCo** （視覺編輯器） 或 `JACOCOXML`(YAML 編輯器）。
+ 對於 Simplecov 產生的 SimpleCov JSON，而非 [simplecov-json](https://github.com/vicentllongo/simplecov-json)，請指定 **Simplecov** （視覺化編輯器） 或 `SIMPLECOV`(YAML 編輯器）。 [https://github.com/simplecov-ruby/simplecov](https://github.com/simplecov-ruby/simplecov)
+ 對於軟體合成分析 (SCA) 報告：
+ 對於 SARIF，指定 **SARIF** （視覺化編輯器） 或 `SARIFSCA`(YAML 編輯器）。
對應的 UI：輸出tab/Reports/Manually設定報告/新增報告/*report-name-1*/**報告類型**和**報告格式**
## Configuration
(*action-name*/**Configuration**)
（必要） 您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## Steps
(*action-name*/Configuration/**Steps**)
(必要)
指定 GitHub Marketplace 中動作詳細資訊頁面上顯示的 [GitHub ](https://github.com/marketplace)動作程式碼。請依照下列準則新增程式碼：
1. 將 GitHub 動作`steps:`區段中的程式碼貼到 CodeCatalyst 工作流程的 `Steps:`區段。程式碼以破折號 (-) 開頭，如下所示。
要貼上的 GitHub 程式碼：
```
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: master
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
1. 檢閱您剛貼上的程式碼，並視需要修改，使其符合 CodeCatalyst 標準。例如，使用上述程式碼區塊，您可以移除*紅色斜體*的程式碼，並以**粗體**新增程式碼。
CodeCatalyst 工作流程 yaml：
```
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: mastermain
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
1. 如需 GitHub 動作中包含但`steps:`區段內不存在的其他程式碼，請使用 CodeCatalyst 同等程式碼將其新增至 CodeCatalyst 工作流程。您可以檢閱 [工作流程 YAML 定義](workflow-reference.md)，深入了解如何將 GitHub 程式碼移植到 CodeCatalyst。詳細的遷移步驟不在本指南的範圍內。
以下是如何在 **GitHub 動作**中指定檔案路徑的範例：
```
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
...
- run: cd /sources/WorkflowSource/MyFolder/ && cat file.txt
- run: cd /artifacts/MyGitHubAction/MyArtifact/MyFolder/ && cat file2.txt
```
如需指定檔案路徑的詳細資訊，請參閱 [參考來源儲存庫檔案](workflows-sources-reference-files.md)和 [參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
對應的 UI：組態索引標籤/**GitHub 動作 YAML**
# 設定運算和執行時間映像
在 CodeCatalyst 工作流程中，您可以指定 CodeCatalyst 用來執行工作流程動作的運算和執行時間環境映像。
*運算*是指由 CodeCatalyst 管理和維護以執行工作流程動作的運算引擎 (CPU、記憶體和作業系統）。
**注意**
如果運算定義為工作流程的屬性，則無法定義為該工作流程中任何動作的屬性。同樣地，如果運算定義為任何動作的屬性，則無法在工作流程中定義。
*執行時間環境映像*是 CodeCatalyst 在其中執行工作流程動作的 Docker 容器。Docker 容器會在您選擇的運算平台上執行，並包含工作流程動作可能需要的作業系統和額外工具，例如 AWS CLI、Node.js 和 .tar。
**Topics**
+ [運算類型](#compute.types)
+ [運算機群](#compute.fleets)
+ [隨需機群屬性](#compute.on-demand)
+ [佈建的機群屬性](#compute.provisioned-fleets)
+ [建立佈建機群](projects-create-compute-resource.md)
+ [編輯佈建的機群](edit-compute-resource.md)
+ [刪除佈建的機群](delete-compute-resource.md)
+ [將機群或運算指派給動作](workflows-assign-compute-resource.md)
+ [跨動作共用運算](compute-sharing.md)
+ [指定執行時間環境映像](build-images.md)
## 運算類型
CodeCatalyst 提供下列運算類型：
+ Amazon EC2
+ AWS Lambda
Amazon EC2 在動作執行期間提供最佳化的彈性，Lambda 則提供最佳化的動作啟動速度。Lambda 支援更快速的工作流程動作執行，因為啟動延遲較低。Lambda 可讓您執行基本工作流程，以建置、測試和部署具有常見執行時間的無伺服器應用程式。這些執行時間包括 Node.js、Python、Java、.NET 和 Go。不過，Lambda 不支援某些使用案例，如果它們影響到您，請使用 Amazon EC2 運算類型：
+ Lambda 不支援來自指定登錄檔的執行期環境映像。
+ Lambda 不支援需要根許可的工具。對於 `yum`或 等工具`rpm`，請使用 Amazon EC2 運算類型或其他不需要根許可的工具。
+ Lambda 不支援 Docker 組建或執行。不支援下列使用 Docker 映像的動作：部署 AWS CloudFormation 堆疊、部署至 Amazon ECS、Amazon S3 發佈、 AWS CDK 引導、 AWS CDK 部署、 AWS Lambda 叫用 和 GitHub 動作。Lambda 運算也不支援在 CodeCatalyst GitHub 動作中執行的 Docker 型 GitHub 動作。您可以使用不需要根許可的替代方案，例如 Podman。
+ Lambda 不支援寫入 外部的檔案`/tmp`。設定工作流程動作時，您可以重新設定工具以安裝或寫入 `/tmp`。如果您有安裝 的建置動作`npm`，請務必將其設定為安裝到 `/tmp`。
+ Lambda 不支援超過 15 分鐘的執行時間。
## 運算機群
CodeCatalyst 提供下列運算機群：
+ 隨需機群
+ 佈建的機群
透過隨需機群，當工作流程動作開始時，工作流程會佈建所需的資源。這些機器會在動作完成時銷毀。您只需支付執行動作的分鐘數。隨需機群受到完全管理，並包含自動擴展功能來處理需求激增。
CodeCatalyst 也提供佈建機群，其中包含由 CodeCatalyst 維護、採用 Amazon EC2 技術的機器。使用佈建機群，您可以設定一組專用機器來執行工作流程動作。這些機器保持閒置狀態，準備好立即處理動作。使用佈建機群時，您的機器一律在執行中，只要佈建，就會產生成本。
若要建立、更新或刪除機群，您必須擁有**空間管理員**角色或**專案管理員**角色。
## 隨需機群屬性
CodeCatalyst 提供下列隨需機群：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/workflows-working-compute.html)
**注意**
隨需機群的規格會根據您的帳單方案而有所不同。如需詳細資訊，請參閱[ 定價](https://codecatalyst.aws/explore/pricing)。
如果未選取機群，CodeCatalyst 會使用 `Linux.x86-64.Large`。
## 佈建的機群屬性
佈建的機群包含下列屬性：
**作業系統**
作業系統。下列作業系統可供使用：
+ Amazon Linux 2
+ Windows Server 2022
**注意**
只有建置動作支援 Windows 機群。其他動作目前不支援 Windows。
**Architecture**
處理器架構。下列架構可供使用：
+ x86\$164
+ Arm64
**機器類型**
每個執行個體的機器類型。下列機器類型可供使用：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codecatalyst/latest/userguide/workflows-working-compute.html)
**Capacity**
配置給機群的機器初始數量，定義可平行執行的動作數量。
**擴展模式**
定義動作數量超過機群容量時的行為。
**隨需佈建額外容量**
其他機器會隨需設定，自動擴展以回應執行中的新動作，然後在動作完成時縮減至基本容量。這可能會產生額外的成本，因為您按分鐘為執行中的每部機器付費。
**等待直到有額外的機群容量可用**
動作執行會放置在佇列中，直到機器可用為止。這可限制額外的成本，因為沒有配置額外的機器。
# 建立佈建機群
使用以下指示來建立佈建機群。
**注意**
佈建的機群將在閒置 2 週後停用。如果再次使用，它們將自動重新啟用，但此重新啟用可能會導致延遲發生。
**建立佈建機群**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**運算**。
1. 選擇**建立佈建機群**。
1. 在**佈建機群名稱**文字欄位中，輸入機群的名稱。
1. 從**作業系統**下拉式功能表中，選擇作業系統。
1. 從**機器類型**下拉式選單中，選擇機器的機器類型。
1. 在**容量**文字欄位中，輸入機群中的機器數量上限。
1. 從**擴展模式**下拉式功能表中，選擇所需的溢位行為。如需有關這些欄位的詳細資訊，請參閱 [佈建的機群屬性](workflows-working-compute.md#compute.provisioned-fleets)。
1. 選擇**建立**。
建立佈建機群之後，您就可以將其指派給 動作。如需詳細資訊，請參閱[將機群或運算指派給動作](workflows-assign-compute-resource.md)。
# 編輯佈建的機群
使用下列指示來編輯佈建機群。
**注意**
佈建的機群將在閒置 2 週後停用。如果再次使用，它們將自動重新啟用，但此重新啟用可能會導致延遲發生。
**編輯佈建機群**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**運算**。
1. 在**佈建機群**清單中，選擇您要編輯的機群。
1. 選擇**編輯**。
1. 在**容量**文字欄位中，輸入機群中的機器數量上限。
1. 從**擴展模式**下拉式功能表中，選擇所需的溢位行為。如需有關這些欄位的詳細資訊，請參閱 [佈建的機群屬性](workflows-working-compute.md#compute.provisioned-fleets)。
1. 選擇**儲存**。
# 刪除佈建的機群
使用下列指示來刪除佈建的機群。
**刪除佈建的機群**
**警告**
刪除佈建機群之前，請先從動作的 YAML 程式碼中刪除 `Fleet` 屬性，將其從所有動作中移除。刪除佈建機群之後繼續參考的任何動作，都會在下次動作執行時失敗。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**運算**。
1. 在**佈建機群**清單中，選擇您要刪除的機群。
1. 選擇 **刪除**。
1. 輸入 **delete** 以確認刪除。
1. 選擇**刪除**。
# 將機群或運算指派給動作
根據預設，工作流程動作會使用`Linux.x86-64.Large`隨需機群搭配 Amazon EC2 運算類型。若要改用佈建機群，或使用不同的隨需機群，例如 `Linux.x86-64.2XLarge`，請使用下列指示。
------
#### [ Visual ]
**開始之前**
+ 如果您想要指派佈建機群，您必須先建立佈建機群。如需詳細資訊，請參閱[建立佈建機群](projects-create-compute-resource.md)。
**將佈建的機群或不同的機群類型指派給動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要指派佈建機群或新機群類型的動作。
1. 選擇 **Configuration** (組態) 索引標籤。
1. 在**運算機群**中，執行下列動作：
指定將執行工作流程或工作流程動作的機器或機群。使用隨需機群時，當動作開始時，工作流程會佈建所需的資源，並在動作完成時銷毀機器。隨需機群的範例：`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`。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**開始之前**
+ 如果您想要指派佈建機群，您必須先建立佈建機群。如需詳細資訊，請參閱[建立佈建機群](projects-create-compute-resource.md)。
**將佈建的機群或不同的機群類型指派給動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 尋找您要指派佈建機群或新機群類型的動作。
1. 在 動作中，新增 `Compute` 屬性，並將 `Fleet` 設定為機群名稱或隨需機群類型。如需詳細資訊，請參閱 中 動作`Fleet`屬性[建置和測試動作 YAML](build-action-ref.md)的描述。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 跨動作共用運算
根據預設，工作流程中的動作會在[機群](workflows-working-compute.md#compute.fleets)中的不同執行個體上執行。此行為為動作提供輸入狀態的隔離和可預測性。預設行為需要明確組態，才能在動作之間共用內容，例如檔案和變數。
運算共用是一項功能，可讓您在相同執行個體上執行工作流程中的所有動作。使用運算共用可以提供更快的工作流程執行時間，因為佈建執行個體所花費的時間較少。您也可以在動作之間共用檔案 （成品），而無需額外的工作流程組態。
使用運算共用執行工作流程時，預設或指定機群中的執行個體會保留在該工作流程中所有動作的期間。當工作流程執行完成時，會釋出執行個體保留。
**Topics**
+ [在共用運算上執行多個動作](#how-to-compute-share)
+ [運算共用的考量](#compare-compute-sharing)
+ [開啟運算共用](#compute-sharing-steps)
+ [範例](#compute-sharing-examples)
## 在共用運算上執行多個動作
您可以在工作流程層級使用定義 YAML 中的 `Compute` 屬性，指定 動作的機群和運算共用屬性。您也可以使用 CodeCatalyst 中的視覺化編輯器來設定運算屬性。若要指定機群，請設定現有機群的名稱、將運算類型設定為 **EC2**，然後開啟運算共用。
**注意**
運算共用只有在運算類型設定為 **EC2** 且 Windows Server 2022 作業系統不支援時才支援。如需運算機群、運算類型和屬性的詳細資訊，請參閱 [設定運算和執行時間映像](workflows-working-compute.md)。
**注意**
如果您位於免費方案，而且在工作流程定義 YAML 中手動指定 `Linux.x86-64.XLarge`或 機`Linux.x86-64.2XLarge`群，則動作仍會在預設機群 () 上執行`Linux.x86-64.Large`。如需運算可用性和定價的詳細資訊，請參閱 [方案選項的表格](https://codecatalyst.aws/explore/pricing)。
開啟運算共用時，包含工作流程來源的資料夾會自動跨動作複製。您不需要設定輸出成品，並在整個工作流程定義 (YAML 檔案） 中將其參考為輸入成品。身為工作流程作者，您需要使用輸入和輸出來連接環境變數，就像不使用運算共用一樣。如果您想要在工作流程來源以外的動作之間共用資料夾，請考慮檔案快取。如需詳細資訊，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md) 和 [在工作流程執行之間快取檔案](workflows-caching.md)。
工作流程定義檔案所在的來源儲存庫由標籤 識別`WorkflowSource`。使用運算共用時，工作流程來源會下載在參考的第一個動作中，並自動供工作流程執行中的後續動作使用。透過新增、修改或移除檔案等動作對包含工作流程來源的資料夾所做的任何變更，也會在工作流程的後續動作中顯示。您可以在任何工作流程動作中參考位於工作流程來源資料夾中的檔案，就像不使用運算共用一樣。如需詳細資訊，請參閱[參考來源儲存庫檔案](workflows-sources-reference-files.md)。
**注意**
運算共用工作流程需要指定嚴格的動作序列，因此無法設定平行動作。雖然可以在序列中的任何動作設定輸出成品，但不支援輸入成品。
## 運算共用的考量
您可以使用運算共用來執行工作流程，以加速工作流程執行，並在使用相同執行個體的工作流程中共用動作之間的內容。請考慮下列事項，以判斷使用運算共用是否適合您的案例：
| | 運算共用 | 不使用運算共用 |
| --- | --- | --- |
| 運算類型 | Amazon EC2 | Amazon EC2、AWS Lambda |
| 執行個體佈建 | 在相同執行個體上執行的動作 | 在個別執行個體上執行的動作 |
| 作業系統 | Amazon Linux 2 | Amazon Linux 2、Windows Server 2022 （僅限建置動作） |
| 參考檔案 | `$CATALYST_SOURCE_DIR_WorkflowSource`, `/sources/WorkflowSource/` | `$CATALYST_SOURCE_DIR_WorkflowSource`, `/sources/WorkflowSource/` |
| Workflow 結構 | 動作只能循序執行 | 動作可以平行執行 |
| 跨工作流程動作存取資料 | 存取快取工作流程來源 (`WorkflowSource`) | 存取共用成品的輸出 （需要額外組態） |
## 開啟運算共用
使用下列指示來開啟工作流程的運算共用。
------
#### [ Visual ]
**使用視覺化編輯器開啟運算共用**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 選擇**工作流程屬性**。
1. 從**運算類型**下拉式選單中，選擇 **EC2**。
1. （選用） 從**運算機群 - 選用**下拉式功能表中，選擇您要用來執行工作流程動作的機群。您可以選擇隨需機群，或建立和選擇佈建機群。如需詳細資訊，請參閱 [建立佈建機群](projects-create-compute-resource.md) 和 [將機群或運算指派給動作](workflows-assign-compute-resource.md)
1. 切換切換以開啟運算共用，並在相同機群上執行工作流程中的動作。
1. （選用） 選擇工作流程的執行模式。如需詳細資訊，請參閱[設定執行的佇列行為](workflows-configure-runs.md)。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器開啟運算共用**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 開啟運算共用，將 `SharedInstance` 欄位設定為 `TRUE`，並將 欄位`Type`設定為 `EC2`。將 `Fleet`設定為您想要用來執行工作流程動作的運算機群。您可以選擇隨需機群，或建立和選擇佈建機群。如需詳細資訊，請參閱 [建立佈建機群](projects-create-compute-resource.md) 和 [將機群或運算指派給動作](workflows-assign-compute-resource.md)
在工作流程 YAML 中，新增類似下列的程式碼：
```
Name: MyWorkflow
SchemaVersion: "1.0"
Compute: # Define compute configuration.
Type: EC2
Fleet: MyFleet # Optionally, choose an on-demand or provisioned fleet.
SharedInstance: true # Turn on compute sharing. Default is False.
Actions:
BuildFirst:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: ...
...
```
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 範例
**Topics**
+ [範例：Amazon S3 Publish](#compute-share-s3)
### 範例：Amazon S3 Publish
下列工作流程範例示範如何以兩種方式執行 Amazon S3 Publish 動作：先使用輸入成品，再使用運算共用。使用運算共用時，不需要輸入成品，因為您可以存取快取的 `WorkflowSource`。此外，不再需要建置動作中的輸出成品。S3 Publish 動作設定為使用明確`DependsOn`屬性來維護循序動作；建置動作必須成功執行，S3 Publish 動作才能執行。
+ 如果沒有運算共用，您需要使用輸入成品，並與後續動作共用輸出：
```
Name: S3PublishUsingInputArtifact
SchemaVersion: "1.0"
Actions:
Build:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ArtifactToPublish
Files: [output.zip]
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: ./build.sh # Build script that generates output.zip
PublishToS3:
Identifier: aws/s3-publish@v1
Inputs:
Artifacts:
- ArtifactToPublish
Environment:
Connections:
- Role: codecatalyst-deployment-role
Name: dev-deployment-role
Name: dev-connection
Configuration:
SourcePath: output.zip
DestinationBucketName: amzn-s3-demo-bucket
```
+ 將 `SharedInstance`設定為 以使用運算共用時`TRUE`，您可以在相同執行個體上執行多個動作，並透過指定單一工作流程來源來共用成品。輸入成品並非必要項目，也無法指定：
```
Name: S3PublishUsingComputeSharing
SchemaVersion: "1.0"
Compute:
Type: EC2
Fleet: dev-fleet
SharedInstance: TRUE
Actions:
Build:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- Run: ./build.sh # Build script that generates output.zip
PublishToS3:
Identifier: aws/s3-publish@v1
DependsOn:
- Build
Environment:
Connections:
- Role: codecatalyst-deployment-role
Name: dev-deployment-role
Name: dev-connection
Configuration:
SourcePath: output.zip
DestinationBucketName: amzn-s3-demo-bucket
```
# 指定執行時間環境映像
*執行時間環境映像*是 CodeCatalyst 在其中執行工作流程動作的 Docker 容器。Docker 容器會在您選擇的運算平台上執行，並包含工作流程動作可能需要的作業系統和額外工具，例如 AWS CLI、Node.js 和 .tar。
根據預設，工作流程動作會在 CodeCatalyst 提供和維護的其中一個[作用中映像](#build-curated-images)上執行。只有建置和測試動作支援自訂映像。如需詳細資訊，請參閱[將自訂執行期環境 Docker 映像指派給 動作](#build-images-specify)。
**Topics**
+ [作用中映像](#build-curated-images)
+ [如果作用中映像不包含我需要的工具，該怎麼辦？](#build-images-more-tools)
+ [將自訂執行期環境 Docker 映像指派給 動作](#build-images-specify)
+ [範例](#workflows-working-custom-image-ex)
## 作用中映像
*作用中映像*是 CodeCatalyst 完全支援的執行期環境映像，並包含預先安裝的工具。目前有兩組作用中映像：一組在 2024 年 3 月發行，另一組在 2022 年 11 月發行。
動作是否使用 2024 年 3 月或 2022 年 11 月映像取決於動作：
+ 在 2024 年 3 月 26 日或之後新增至工作流程的建置和測試動作，將在其 YAML 定義中包含明確指定 [2024 年 3 月映像](#build.default-image)的`Container`區段。您可以選擇性地移除 `Container`區段，以還原至 [2022 年 11 月的映像](#build.previous-image)。
+ 在 2024 年 3 月 26 日之前新增至工作流程的建置和測試動作，*將不會*在其 YAML 定義中包含 `Container`區段，因此將使用 [2022 年 11 月的映像](#build.previous-image)。您可以保留 2022 年 11 月的映像，也可以進行升級。若要升級映像，請在視覺化編輯器中開啟動作，選擇**組態**索引標籤，然後從**執行期環境Docker 映像下拉式清單中選取 2024 年 3 月映像**。此選擇會將`Container`區段新增至動作的 YAML 定義，該定義會填入適當的 2024 年 3 月映像。
+ 所有其他動作將使用 [2022 年 11 月的映像](#build.previous-image)或 [2024 年 3 月的映像](#build.default-image)。如需詳細資訊，請參閱 動作的文件。
**Topics**
+ [2024 年 3 月影像](#build.default-image)
+ [2022 年 11 月影像](#build.previous-image)
### 2024 年 3 月影像
2024 年 3 月的映像是 CodeCatalyst 提供的最新映像。每個運算類型/機群組合都有一個 2024 年 3 月的映像。
下表顯示每個 2024 年 3 月映像上安裝的工具。
**2024 年 3 月映像工具**
| 工具 | CodeCatalyst Amazon EC2 for Linux x86\$164 - `CodeCatalystLinux_x86_64:2024_03` | CodeCatalyst Lambda for Linux x86\$164 - `CodeCatalystLinuxLambda_x86_64:2024_03` | CodeCatalyst Amazon EC2 for Linux Arm64 - `CodeCatalystLinux_Arm64:2024_03` | 適用於 Linux Arm64 的 CodeCatalyst Lambda - `CodeCatalystLinuxLambda_Arm64:2024_03` |
| --- | --- | --- | --- | --- |
| AWS CLI | 2.15.17 | 2.15.17 | 2.15.17 | 2.15.17 |
| AWS Copilot CLI | 1.32.1 | 1.32.1 | 1.32.1 | 1.32.1 |
| Docker | 24.0.9 | N/A | 24.0.9 | N/A |
| Docker Compose | 2.23.3 | N/A | 2.23.3 | N/A |
| Git | 2.43.0 | 2.43.0 | 2.43.0 | 2.43.0 |
| Go | 1.21.5 | 1.21.5 | 1.21.5 | 1.21.5 |
| Gradle | 8.5 | 8.5 | 8.5 | 8.5 |
| Java | Corretto17 | Corretto17 | Corretto17 | Corretto17 |
| Maven | 3.9.6 | 3.9.6 | 3.9.6 | 3.9.6 |
| Node.js | 18.19.0 | 18.19.0 | 18.19.0 | 18.19.0 |
| npm | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.3 |
| Python | 3.9.18 | 3.9.18 | 3.9.18 | 3.9.18 |
| Python3 | 3.11.6 | 3.11.6 | 3.11.6 | 3.11.6 |
| pip | 22.3.1 | 22.3.1 | 22.3.1 | 22.3.1 |
| .NET | 8.0.100 | 8.0.100 | 8.0.100 | 8.0.100 |
### 2022 年 11 月影像
每個運算類型/機群組合都有一個 2022 年 11 月的映像。如果您已設定[佈建機群](workflows-working-compute.md#compute.fleets)，建置動作也會提供 2022 年 11 月 Windows 映像。
下表顯示每個 2022 年 11 月映像上安裝的工具。
**2022 年 11 月映像工具**
| 工具 | CodeCatalyst Amazon EC2 for Linux x86\$164 - `CodeCatalystLinux_x86_64:2022_11` | 適用於 Linux x86\$164 的 CodeCatalyst Lambda - `CodeCatalystLinuxLambda_x86_64:2022_11` | CodeCatalyst Amazon EC2 for Linux Arm64 - `CodeCatalystLinux_Arm64:2022_11` | 適用於 Linux Arm64 的 CodeCatalyst Lambda - `CodeCatalystLinuxLambda_Arm64:2022_11` | CodeCatalyst Amazon EC2 for Windows x86\$164 - `CodeCatalystWindows_x86_64:2022_11` |
| --- | --- | --- | --- | --- | --- |
| AWS CLI | 2.15.17 | 2.15.17 | 2.15.17 | 2.15.17 | 2.13.19 |
| AWS Copilot CLI | 0.6.0 | 0.6.0 | N/A | N/A | 1.30.1 |
| Docker | 23.01 | N/A | 23.0.1 | N/A | N/A |
| Docker Compose | 2.16.0 | N/A | 2.16.0 | N/A | N/A |
| Git | 2.40.0 | 2.40.0 | 2.39.2 | 2.39.2 | 2.42.0 |
| Go | 1.20.2 | 1.20.2 | 1.20.1 | 1.20.1 | 1.19 |
| Gradle | 8.0.2 | 8.0.2 | 8.0.1 | 8.0.1 | 8.3 |
| Java | Corretto17 | Corretto17 | Corretto17 | Corretto17 | Corretto17 |
| Maven | 3.9.4 | 3.9.4 | 3.9.0 | 3.9.0 | 3.9.4 |
| Node.js | 16.20.2 | 16.20.2 | 16.19.1 | 16.14.2 | 16.20.0 |
| npm | 8.19.4 | 8.19.4 | 8.19.3 | 8.5.0 | 8.19.4 |
| Python | 3.9.15 | 2.7.18 | 3.11.2 | 2.7.18 | 3.9.13 |
| Python3 | N/A | 3.9.15 | N/A | 3.11.2 | N/A |
| pip | 22.2.2 | 22.2.2 | 23.0.1 | 23.0.1 | 22.0.4 |
| .NET | 6.0.407 | 6.0.407 | 6.0.406 | 6.0.406 | 6.0.414 |
## 如果作用中映像不包含我需要的工具，該怎麼辦？
如果 CodeCatalyst 提供的任何[作用中映像](#build-curated-images)都未包含您需要的工具，您有幾個選項：
+ 您可以提供包含必要工具的自訂執行期環境 Docker 映像。如需詳細資訊，請參閱[將自訂執行期環境 Docker 映像指派給 動作](#build-images-specify)。
**注意**
如果您想要提供自訂執行期環境 Docker 映像，請確定您的自訂映像中已安裝 Git。
+ 您可以讓工作流程的建置或測試動作安裝所需的工具。
例如，您可以在組建或測試動作 YAML 程式碼的 `Steps`區段中包含下列指示：
```
Configuration:
Steps:
- Run: ./setup-script
```
*setup-script* 指令接著會執行下列指令碼來安裝 Node 套件管理員 (npm)：
```
#!/usr/bin/env bash
echo "Setting up environment"
touch ~/.bashrc
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm install v16.1.0
source ~/.bashrc
```
如需建置動作 YAML 的詳細資訊，請參閱 [建置和測試動作 YAML](build-action-ref.md)。
## 將自訂執行期環境 Docker 映像指派給 動作
如果您不想使用 CodeCatalyst 提供的[作用中映像](#build-curated-images)，您可以提供自訂執行期環境 Docker 映像。如果您想要提供自訂映像，請確定其中已安裝 Git。映像可以位於 Docker Hub、Amazon Elastic Container Registry 或任何公有儲存庫中。
若要了解如何建立自訂 Docker 映像，請參閱 Docker 文件中的[容器化應用程式](https://docs.docker.com/get-started/02_our_app/)。
使用下列指示將自訂執行期環境 Docker 映像指派給 動作。指定映像之後，CodeCatalyst 會在動作開始時將其部署到您的運算平台。
**注意**
下列動作不支援自訂執行期環境 Docker 映像：**部署 CloudFormation 堆疊**、**部署至 ECS** 和 **GitHub 動作**。自訂執行期環境 Docker 映像也不支援 **Lambda** 運算類型。
------
#### [ Visual ]
**使用視覺化編輯器指派自訂執行期環境 Docker 映像**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇將使用您的自訂執行期環境 Docker 映像的動作。
1. 選擇 **Configuration** (組態) 索引標籤。
1. 在底部附近，填寫下列欄位。
**執行期環境 Docker 映像 - 選用**
指定儲存映像的登錄檔。有效值包含：
+ `CODECATALYST` (YAML 編輯器）
映像會存放在 CodeCatalyst 登錄檔中。
+ **Docker Hub** （視覺化編輯器） 或 `DockerHub`(YAML 編輯器）
映像會存放在 Docker Hub 映像登錄檔中。
+ **其他登錄**檔 （視覺化編輯器） 或 `Other`(YAML 編輯器）
映像會存放在自訂映像登錄檔中。您可以使用任何公開可用的登錄檔。
+ **Amazon Elastic Container Registry** （視覺化編輯器） 或 `ECR`(YAML 編輯器）
映像會存放在 Amazon Elastic Container Registry 映像儲存庫中。若要在 Amazon ECR 儲存庫中使用映像，此動作需要存取 Amazon ECR。若要啟用此存取權，您必須建立包含下列許可和自訂信任政策的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。（如果需要，您可以修改現有角色以包含許可和政策。)
IAM 角色必須在其角色政策中包含下列許可：
+ `ecr:BatchCheckLayerAvailability`
+ `ecr:BatchGetImage`
+ `ecr:GetAuthorizationToken`
+ `ecr:GetDownloadUrlForLayer`
IAM 角色必須包含下列自訂信任政策：
如需建立 IAM 角色的詳細資訊，請參閱《*IAM 使用者指南*》中的[使用自訂信任政策 （主控台） 建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)。
建立角色之後，您必須透過 環境將其指派給 動作。如需詳細資訊，請參閱[將環境與 動作建立關聯](deploy-environments-add-app-to-environment.md)。
**ECR 映像 URL**、**Docker Hub 映像**或**映像 URL**
請指定下列其中一項：
+ 如果您使用的是`CODECATALYST`登錄檔，請將映像設定為下列其中一個[作用中映像](#build-curated-images)：
+ `CodeCatalystLinux_x86_64:2024_03`
+ `CodeCatalystLinux_x86_64:2022_11`
+ `CodeCatalystLinux_Arm64:2024_03`
+ `CodeCatalystLinux_Arm64:2022_11`
+ `CodeCatalystLinuxLambda_x86_64:2024_03`
+ `CodeCatalystLinuxLambda_x86_64:2022_11`
+ `CodeCatalystLinuxLambda_Arm64:2024_03`
+ `CodeCatalystLinuxLambda_Arm64:2022_11`
+ `CodeCatalystWindows_x86_64:2022_11`
+ 如果您使用的是 Docker Hub 登錄檔，請將映像設定為 Docker Hub 映像名稱和選用標籤。
範例：`postgres:latest`
+ 如果您使用的是 Amazon ECR 登錄檔，請將映像設定為 Amazon ECR 登錄檔 URI。
範例：`111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`
+ 如果您使用的是自訂登錄檔，請將映像設定為自訂登錄檔預期的值。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器指派自訂執行期環境 Docker 映像**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 尋找您要指派執行時間環境 Docker 映像的動作。
1. 在 動作中，新增`Container`區段和基礎 `Registry`和 `Image` 屬性。如需詳細資訊，請參閱 中 [動作](workflow-reference.md#actions-reference) 動作的 `Container``Registry`和 `Image` 屬性說明。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
## 範例
下列範例示範如何將自訂執行期環境 Docker 映像指派給工作流程定義檔案中的動作。
**Topics**
+ [範例：使用自訂執行期環境 Docker 映像新增對 Node.js 18 與 Amazon ECR 的支援](#workflows-working-custom-image-ex-ecr-node18)
+ [範例：使用自訂執行期環境 Docker 映像新增對 Node.js 18 與 Docker Hub 的支援](#workflows-working-custom-image-ex-docker-node18)
### 範例：使用自訂執行期環境 Docker 映像新增對 Node.js 18 與 Amazon ECR 的支援
下列範例顯示如何使用自訂執行期環境 Docker 映像來新增對 Node.js 18 搭配 [Amazon ECR](https://gallery.ecr.aws/amazonlinux/amazonlinux) 的支援。
```
Configuration:
Container:
Registry: ECR
Image: public.ecr.aws/amazonlinux/amazonlinux:2023
```
### 範例：使用自訂執行期環境 Docker 映像新增對 Node.js 18 與 Docker Hub 的支援
下列範例顯示如何使用自訂執行期環境 Docker 映像來新增對 Node.js 18 與 [Docker Hub](https://hub.docker.com/_/node) 的支援。
```
Configuration:
Container:
Registry: DockerHub
Image: node:18.18.2
```
# 將來源儲存庫連線至工作流程
*來源*也稱為*輸入來源*，是[工作流程動作](workflows-actions.md)所連接的來源儲存庫，以取得執行其操作所需的檔案。例如，工作流程動作可能會連線到來源儲存庫，以取得應用程式來源檔案，以建置應用程式。
CodeCatalyst 工作流程支援下列來源：
+ CodeCatalyst 來源儲存庫 – 如需詳細資訊，請參閱 [將程式碼與 CodeCatalyst 中的來源儲存庫一起存放和協作儲存程式碼並與來源儲存庫協作](source.md)。
+ GitHub 儲存庫、Bitbucket 儲存庫和 GitLab 專案儲存庫 – 如需詳細資訊，請參閱[在 CodeCatalyst 中將功能新增至具有擴充功能的專案將功能新增至具有擴充功能的專案](extensions.md)。
**Topics**
+ [指定工作流程檔案的來源儲存庫](workflows-sources-specify-workflow-def.md)
+ [指定工作流程動作的來源儲存庫](workflows-sources-specify-action.md)
+ [參考來源儲存庫檔案](workflows-sources-reference-files.md)
+ ['BranchName' 和 'CommitId' 變數](workflows-sources-variables.md)
# 指定工作流程檔案的來源儲存庫
使用下列指示來指定您要存放工作流程定義檔案的 CodeCatalyst 來源儲存庫。如果您想要指定 GitHub 儲存庫、Bitbucket 儲存庫或 GitLab 專案儲存庫，請改為參閱 [在 CodeCatalyst 中將功能新增至具有擴充功能的專案將功能新增至具有擴充功能的專案](extensions.md)。
工作流程定義檔案所在的來源儲存庫由標籤 識別`WorkflowSource`。
**注意**
您可以在第一次遞交工作流程定義檔案時，指定工作流程定義檔案所在的來源儲存庫。在此遞交之後，儲存庫和工作流程定義檔案會永久連結在一起。在初始遞交之後變更儲存庫的唯一方法是在不同的儲存庫中重新建立工作流程。
**指定將存放工作流程定義檔案的來源儲存庫**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**並建立工作流程。如需詳細資訊，請參閱[建立工作流程](workflows-create-workflow.md)。
在工作流程建立過程中，您可以指定要存放工作流程定義檔案的 CodeCatalyst 儲存庫、分支和資料夾。
# 指定工作流程動作的來源儲存庫
使用下列指示來指定要與工作流程動作搭配使用的來源儲存庫。啟動時，動作會將已設定來源儲存庫中的檔案封裝成成品、將成品下載至執行動作的[執行時間環境 Docker 映像](build-images.md)，然後使用下載的檔案完成其處理。
**注意**
目前，在工作流程動作中，您只能指定一個來源儲存庫，也就是工作流程定義檔案所在的來源儲存庫 （在 `.codecatalyst/workflows/`目錄中或其子目錄中）。此來源儲存庫由標籤 表示`WorkflowSource`。
------
#### [ Visual ]
**指定動作將使用的來源儲存庫 （視覺化編輯器）**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要指定來源的動作。
1. 選擇**輸入**。
1. 在**來源 - 選用**中執行下列動作：
指定代表 動作所需來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`，代表儲存工作流程定義檔案的來源儲存庫。
如果您省略來源，則必須在 下指定至少一個輸入成品`action-name/Inputs/Artifacts`。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**指定動作將使用的來源儲存庫 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 動作中，新增類似下列的程式碼：
```
action-name:
Inputs:
Sources:
- WorkflowSource
```
如需詳細資訊，請參閱 中 [工作流程 YAML 定義](workflow-reference.md) 動作的 `Sources` 屬性描述。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 參考來源儲存庫檔案
如果您的檔案位於來源儲存庫中，而且您需要在其中一個工作流程動作中參考這些檔案，請完成下列程序。
**注意**
另請參閱[參考成品中的檔案](workflows-working-artifacts-refer-files.md)。
**參考存放在來源儲存庫中的檔案**
+ 在您要參考檔案的動作中，新增類似下列的程式碼：
```
Actions:
My-action:
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
- run: cd my-app && cat file1.jar
```
在先前的程式碼中， 動作會在`WorkflowSource`來源儲存庫根`my-app`目錄中尋找並顯示 `file1.jar` 檔案。
# 'BranchName' 和 'CommitId' 變數
CodeCatalyst 來源會在工作流程執行時產生和設定 `BranchName`和 `CommitId`變數。這些稱為*預先定義的變數*。如需這些變數的相關資訊，請參閱下表。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| CommitId | 工作流程執行開始時代表儲存庫狀態的遞交 ID。 範例：`example3819261db00a3ab59468c8b` 另請參閱：[範例：參考「CommitId」預先定義的變數](workflows-predefined-examples.md#workflows-working-with-variables-ex-refer-action) |
| BranchName | 工作流程執行開始的分支名稱。 範例：`main`、`feature/branch`、`test-LiJuan` 另請參閱：[範例：參考「BranchName」預先定義的變數](workflows-predefined-examples.md#workflows-working-with-variables-ex-branch) |
# 將套件儲存庫連線至工作流程
*套件*是一種套件，其中包含安裝軟體和解決任何相依性所需的軟體和中繼資料。CodeCatalyst 支援 npm 套件格式。
套件包含：
+ 名稱 （例如， `webpack` 是熱門 npm 套件的名稱）
+ 選用[的命名空間](packages-concepts.md#packages-concepts-package-namespaces) （例如，在 `@types`中`@types/node`)
+ 一組[版本](packages-concepts.md#packages-concepts-package-versions) （例如 、`1.0.0``1.0.1`、`1.0.2`)
+ 套件層級中繼資料 （例如 npm dist 標籤）
在 CodeCatalyst 中，您可以將套件發佈至 ，並在工作流程中從 CodeCatalyst 套件儲存庫取用套件。您可以使用 CodeCatalyst 套件儲存庫設定建置或測試動作，以自動設定動作的 npm 用戶端，從指定的儲存庫推送和提取套件。
如需套件的詳細資訊，請參閱 [在 CodeCatalyst 中發佈和共用軟體套件](packages.md)。
**注意**
目前，建置和測試動作支援 CodeCatalyst 套件儲存庫。
**Topics**
+ [教學課程：從套件儲存庫提取](packages-tutorial.md)
+ [在工作流程中指定 CodeCatalyst 套件儲存庫](workflows-package-specify-action.md)
+ [在工作流程動作中使用授權字符](workflows-package-export-token.md)
+ [範例：工作流程中的套件儲存庫](workflows-working-packages-ex.md)
# 教學課程：從套件儲存庫提取
在本教學課程中，您將了解如何建立工作流程，以執行從 [CodeCatalyst 套件儲存庫](packages-concepts.md#packages-concepts-repository)提取相依性的應用程式。應用程式是簡單的 Node.js 應用程式，會將「Hello World」訊息列印至 CodeCatalyst 日誌。應用程式具有單一相依性：[lodash](https://www.npmjs.com/package/lodash) npm 套件。`lodash` 套件用於將`hello-world`字串轉換為 `Hello World`。您將使用此套件的 4.17.20 版。
設定應用程式和工作流程之後，您可以設定 CodeCatalyst 來封鎖其他版本的 `lodash` 從公有外部登錄檔 ([npmjs.com](https://www.npmjs.com/)：//) 匯入 CodeCatalyst 套件儲存庫。然後，您可以測試`lodash`已成功封鎖其他版本的 。
在本教學課程結束時，您應該充分了解工作流程如何與 CodeCatalyst 內部和外部的套件儲存庫互動，以擷取套件。您也應該了解 npm、套件儲存庫、工作流程和應用程式`package.json`檔案之間發生的behind-the-scenes互動。
**Topics**
+ [先決條件](#packages-tutorial-prereqs)
+ [步驟 1：建立來源儲存庫](#packages-tutorial-source-repo)
+ [步驟 2：建立 CodeCatalyst 和閘道套件儲存庫](#packages-tutorial-package-repo)
+ [步驟 3：建立「Hello World」應用程式](#packages-tutorial-create-app)
+ [步驟 4：建立執行「Hello World」的工作流程](#packages-tutorial-create-workflow)
+ [步驟 5：驗證工作流程](#packages-tutorial-verify)
+ [步驟 6：從 npmjs.com 封鎖匯入](#packages-tutorial-block)
+ [步驟 7：測試封鎖功能](#packages-tutorial-test-block)
+ [清除](#packages-tutorial-cleanup)
## 先決條件
開始之前：
+ 您需要 CodeCatalyst **Space**。如需詳細資訊，請參閱[建立空間](spaces-create.md)。
+ 在 CodeCatalyst 空間中，您需要一個名為 的空專案：
```
codecatalyst-package-project
```
使用**從頭開始**選項來建立此專案。
如需詳細資訊，請參閱[在 Amazon CodeCatalyst 中建立空專案](projects-create.md#projects-create-empty)。
## 步驟 1：建立來源儲存庫
在此步驟中，您會在 CodeCatalyst 中建立來源儲存庫。此儲存庫會存放教學課程的來源檔案，例如 `index.js`和 `package.json` 檔案。
如需來源儲存庫的詳細資訊，請參閱 [建立來源儲存庫](source-repositories-create.md)。
**建立來源儲存庫**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 導覽至您的專案 `codecatalyst-package-project`。
1. 在導覽窗格中，選擇**程式碼**，然後選擇**來源儲存庫**。
1. 選擇**新增儲存庫**，然後選擇**建立儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
hello-world-app
```
1. 選擇**建立**。
## 步驟 2：建立 CodeCatalyst 和閘道套件儲存庫
在此步驟中，您會在 CodeCatalyst 專案中建立套件儲存庫，並將其連接到閘道儲存庫，也在您的 CodeCatalyst 專案中。您稍後`lodash`會從 npmjs.com 將教學課程的相依性 匯入兩個儲存庫。
閘道儲存庫是 'glue'，可將 CodeCatalyst 中的套件儲存庫連線至公有 npmjs.com。
如需套件儲存庫的詳細資訊，請參閱 [在 CodeCatalyst 中發佈和共用軟體套件](packages.md)。
**注意**
本教學課程使用 *CodeCatalyst 套件儲存庫*和*閘道儲存庫*一詞，來參考您在下列程序中在 CodeCatalyst 中建立的兩個儲存庫。
**建立 CodeCatalyst 套件和閘道儲存庫**
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇**建立套件儲存庫**。
1. 在**儲存庫名稱**中，輸入：
```
codecatalyst-package-repository
```
1. 選擇 **\$1 選取上游儲存庫**。
1. 選擇**閘道儲存庫**。
1. 在 **npm-public-registry-gateway** 方塊中，選擇**建立**。
1. 選擇**選取**。
1. 選擇**建立**。
CodeCatalyst 會建立名為 的套件儲存庫`codecatalyst-package-repository`，其會連線至閘道儲存庫。閘道儲存庫已連線至 npmjs.com 登錄檔。
## 步驟 3：建立「Hello World」應用程式
在此步驟中，您會建立 'Hello World' Node.js 應用程式，並將其相依性 (`lodash`) 匯入閘道和 CodeCatalyst 套件儲存庫。
若要建立應用程式，您需要安裝 Node.js 和相關聯`npm`用戶端的開發機器。
本教學假設您將使用 CodeCatalyst 開發環境做為您的開發機器。雖然您不必使用 CodeCatalyst 開發環境，但建議您這麼做，因為它提供乾淨的工作環境、已`npm`預先安裝 Node.js 和 ，而且在您完成教學課程時可輕鬆刪除。如需 CodeCatalyst 開發環境的詳細資訊，請參閱 [建立開發環境](devenvironment-create.md)。
使用以下指示啟動 CodeCatalyst 開發環境，並使用它來建立 'Hello World' 應用程式。
**啟動 CodeCatalyst 開發環境**
1. 在導覽窗格中，選擇**程式碼**，然後選擇**開發環境**。
1. 在頂端附近選擇**建立開發環境**，然後選擇 **AWS Cloud9 （在瀏覽器中）**。
1. 確定**儲存庫**設定為 `hello-world-app`，而**現有分支**設定為 `main`。選擇**建立**。
您的開發環境會在新的瀏覽器索引標籤中啟動，而且您的儲存庫 (`hello-world-app`) 會複製到其中。
1. 讓兩個 CodeCatalyst 瀏覽器索引標籤保持開啟，然後前往下一個程序。
**建立 'Hello World' Node.js 應用程式**
1. 前往您的開發環境。
1. 在終端機提示中，將 變更為`hello-world-app`來源儲存庫根目錄：
```
cd hello-world-app
```
1. 初始化 Node.js 專案：
```
npm init -y
```
初始化會在 的根目錄中建立 `package.json` 檔案`hello-world-app`。
1. 將開發環境中的 npm 用戶端連接到 CodeCatalyst 套件儲存庫：
1. 切換到 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇 `codecatalyst-package-repository`。
1. 選擇**連線至儲存庫**。
1. 選擇**建立權杖**。會為您建立個人存取字符 (PAT)。
1. 選擇**複製**以複製命令。
1. 切換到開發環境。
1. 請確定您位於 `hello-world-app`目錄中。
1. 貼上命令。它們看起來類似以下內容：
```
npm set registry=https://packages.us-west-2.codecatalyst.aws/npm/ExampleCompany/codecatalyst-package-project/codecatalyst-package-repository/ --location project
npm set //packages.us-west-2.codecatalyst.aws/npm/ExampleCompany/codecatalyst-package-project/hello-world-app/:_authToken=username:token-secret
```
1. 匯入 4.17.20 `lodash`版：
```
npm install lodash@v4.17.20 --save --save-exact
```
npm 在下列位置尋找 4.17.20 `lodash`版，順序如下：
+ 在開發環境中。它在這裡找不到它。
+ 在 CodeCatalyst 套件儲存庫中。它在這裡找不到它。
+ 在閘道儲存庫中。它在這裡找不到它。
+ 在 https：//npmjs.com。它會在這裡找到它。
npm 匯入`lodash`至閘道儲存庫、CodeCatalyst 套件儲存庫和開發環境。
**注意**
如果您在步驟 4 中尚未將 npm 用戶端連線至 CodeCatalyst 套件儲存庫，則 npm 會`lodash`直接從 npmjs.com 提取，而且不會將套件匯入任一儲存庫。
npm 也會使用`lodash`相依性更新您的`package.json`檔案，並建立包含 `lodash`及其所有相依性的`node_modules`目錄。
1. `lodash` 已成功匯入開發環境的測試。輸入：
```
npm list
```
出現下列訊息，指出成功匯入：
```
`-- lodash@4.17.20
```
1. （選用） 開啟`hello-world-app/package.json`並確認已新增***紅色粗體***的行：
```
{
"name": "hello-world-app",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
dependencies": {
"lodash": "4.17.20"
}
}
```
1. 在 中`/hello-world-app`，建立名為 的檔案`index.js`，其中包含下列內容：
**提示**
您可以使用開發環境中的側邊導覽來建立此檔案。
```
// Importing lodash library
const _ = require('lodash');
// Input string
const inputString = 'hello-world';
// Transforming the string using lodash
const transformedString = _.startCase(inputString.replace('-', ' '));
// Outputting the transformed string to the console
console.log(transformedString);
```
**測試「lodash」是否已匯入您的閘道和 CodeCatalyst 套件儲存庫**
1. 切換到 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇 **npm-public-registry-gateway**。
1. 確定`lodash`已顯示 。**最新版本**欄指出 `4.17.20`。
1. 針對 重複此程序`codecatalyst-package-repository`。您可能需要重新整理瀏覽器視窗，以查看匯入的套件。
**在開發環境中測試「Hello World」**
1. 切換到開發環境。
1. 請確定您仍在 `hello-world-app`目錄中，然後執行應用程式：
```
node index.js
```
訊息`Hello World`隨即出現。Node.js 使用您在上一個步驟中下載到開發環境的`lodash`套件執行應用程式。
**忽略 'node\$1modules' 目錄並遞交 'Hello World'**
1. 忽略 `node_modules`目錄。輸入：
```
echo "node_modules/" >> .gitignore
```
最佳實務是避免遞交此目錄。此外，遞交此目錄將干擾本教學課程的後續步驟。
1. 新增、遞交和推送：
```
git add .
git commit -m "add the Hello World application"
git push
```
'Hello World' 應用程式和專案檔案會新增至您的來源儲存庫。
## 步驟 4：建立執行「Hello World」的工作流程
在此步驟中，您會建立使用`lodash`相依性執行 'Hello World' 應用程式的工作流程。工作流程包含稱為 的單一*動作*或任務`RunHelloWorldApp`。`RunHelloWorldApp` 動作包含下列值得注意的命令和區段：
+ **`Packages`**
本節指出執行 時動作必須連線的 CodeCatalyst 套件儲存庫名稱`npm install`。
+ **`- Run: npm install`**
此命令會通知 npm 安裝 `package.json` 檔案中指定的相依性。`package.json` 檔案中指定的唯一相依性是 `lodash`。npm `lodash`會在下列位置尋找 ：
+ 在執行 動作的 Docker 影像中。它在這裡找不到它。
+ 在 CodeCatalyst 套件儲存庫中。它會在這裡找到它。
在 npm 找到 之後`lodash`，它會將其匯入執行 動作的 Docker 映像。
+ **`- Run: npm list`**
此命令會列印`lodash`下載至執行 動作之 Docker 映像的 版本。
+ **`- Run: node index.js`**
此命令會使用 `package.json` 檔案中指定的相依性來執行 'Hello World' 應用程式。
請注意， `RunHelloWorldApp`動作是建置動作，如工作流程頂端附近的`aws/build@v1`識別符所示。如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
使用以下指示建立工作流程，從 CodeCatalyst 套件儲存庫提取`lodash`相依性，然後執行您的「Hello World」應用程式。
**建立工作流程**
1. 切換到 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇**建立工作流程**。
1. 針對**來源儲存庫**，選擇 `hello-world-app`。
1. 針對**分支**，選擇 `main`。
工作流程定義檔案將在選擇的來源儲存庫和分支中建立。
1. 選擇**建立**。
1. 選擇靠近頂端的 **YAML**。
1. 刪除 YAML 範例程式碼。
1. 新增下列 YAML 程式碼：
```
Name: codecatalyst-package-workflow
SchemaVersion: "1.0"
# Required - Define action configurations.
Actions:
RunHelloWorldApp:
# Identifies the action. Do not modify this value.
Identifier: aws/build@v1
Compute:
Type: Lambda
Inputs:
Sources:
- WorkflowSource # This specifies your source repository.
Configuration:
Steps:
- Run: npm install
- Run: npm list
- Run: node index.js
Container: # This specifies the Docker image that runs the action.
Registry: CODECATALYST
Image: CodeCatalystLinuxLambda_x86_64:2024_03
Packages:
NpmConfiguration:
PackageRegistries:
- PackagesRepository: codecatalyst-package-repository
```
在上述程式碼中，以您在 中建立的 CodeCatalyst 套件儲存庫名稱取代 *codecatalyst-package-repository*[步驟 2：建立 CodeCatalyst 和閘道套件儲存庫](#packages-tutorial-package-repo)。
如需此檔案中屬性的相關資訊，請參閱 [建置和測試動作 YAML](build-action-ref.md)。
1. （選用） 選擇**驗證**，以確保 YAML 程式碼在遞交之前有效。
1. 選擇 **Commit** (遞交)。
1. 在**遞交工作流程**對話方塊中，輸入下列內容：
1. 對於**工作流程檔案名稱**，請保留預設值 `codecatalyst-package-workflow`。
1. 針對**遞交訊息**，輸入：
```
add initial workflow file
```
1. 針對**儲存庫**，選擇 **hello-world-app**。
1. 針對**分支名稱**，選擇**主要**。
1. 選擇 **Commit** (遞交)。
您現在已建立工作流程。
**執行工作流程**
1. 在您剛建立的工作流程旁邊 (`codecatalyst-package-workflow`)，選擇**動作**，然後選擇**執行**。
工作流程執行開始。
1. 在右上角的綠色通知中，選擇執行的連結。連結看起來類似於 `View Run-1234`。
工作流程圖表隨即出現，顯示誰開始執行和 **RunHelloWorldApp** 動作。
1. 選擇 **RunHelloWorldApp** 動作方塊，以監看動作的進度。
1. 當執行完成時，請前往 [步驟 5：驗證工作流程](#packages-tutorial-verify)。
## 步驟 5：驗證工作流程
在此步驟中，您會驗證工作流程是否成功執行具有`lodash`相依性的 'Hello World' 應用程式。
**驗證「Hello World」應用程式是否使用其相依性執行**
1. 在工作流程圖表中，選擇 **RunHelloWorldApp** 方塊。
日誌訊息清單隨即出現。
1. 展開`node index.js`日誌訊息。
出現下列訊息：
```
[Container] 2024/04/24 21:15:41.545650 Running command node index.js
Hello World
```
`Hello Word` （而非 `hello-world`) 的外觀表示已成功使用`lodash`相依性。
1. 展開`npm list`日誌。
出現類似下列的訊息：
```
└── lodash@4.17.20
```
此訊息指出 4.17.20 `lodash`版已下載至執行工作流程動作的 Docker 映像。
## 步驟 6：從 npmjs.com 封鎖匯入
現在，閘道和 CodeCatalyst 套件儲存庫中有 4.17.20 `lodash`版，您可以封鎖其他版本的匯入。封鎖可防止您不小心匯入稍後 （或更早版本） 的 版本`lodash`，其中可能包含惡意程式碼。如需詳細資訊，請參閱[編輯套件原始伺服器控制項](package-origin-controls.md)及[相依性替代攻擊](package-origin-controls.md#dependency-substitution-attacks)。
使用下列指示來封鎖 匯入`lodash`您的閘道儲存庫。當您在閘道封鎖套件時，它們也會在下游位置遭到封鎖。
**封鎖匯入至閘道儲存庫**
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇 **npm-publish-registry-gateway**。
1. 選擇 `lodash`。
1. 在頂端附近，選擇**原始伺服器控制項**。
1. 在**上游**下，選擇**封鎖**。
1. 選擇**儲存**。
您現在已封鎖從 npmjs.com 匯入至閘道儲存庫 （以及下游儲存庫和電腦）。
## 步驟 7：測試封鎖功能
在本節中，您要驗證您在 中設定的封鎖[步驟 6：從 npmjs.com 封鎖匯入](#packages-tutorial-block)是否正常運作。首先，您將 'Hello World' 設定為請求 4.17.2**1** 版，`lodash`而不是閘道儲存庫中可用的版本，即 4.17.2**0**。然後，檢查應用程式是否無法從 nmpjs.com 提取 4.17.21 版，表示封鎖成功。作為最終測試，您可以取消封鎖匯入至閘道儲存庫，並檢查應用程式是否可以成功提取 4.17.21 版`lodash`。
使用下列一組程序來測試封鎖功能。
**開始之前**
1. 切換到開發環境。
1. 提取您先前使用 CodeCatalyst 主控台建立`codecatalyst-package-workflow.yaml`的檔案：
```
git pull
```
**設定「Hello World」以請求 4.17.21 版的「lodash」**
1. 打開 `/hello-world-app/package.json`。
1. 將`lodash`版本變更為 4.17.21，如***紅色粗體***所示：
```
{
"name": "hello-world-app",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"lodash": "4.17.21"
}
}
```
檔案中的版本 `package.json`(4.17.21) 與閘道中的版本和 CodeCatalyst 套件儲存庫 (4.17.20) 現在不相符。
1. 新增、遞交和推送：
```
git add .
git commit -m "update package.json to use lodash 4.17.21"
git push
```
**測試「Hello World」無法提取 4.17.21 版的「lodash」**
1. 執行版本不相符的工作流程：
1. 切換到 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 在 旁`codecatalyst-package-workflow`，選擇**動作**，然後選擇**執行。**
npm `package.json` 會尋找相依性，並看到 'Hello World' `lodash`需要 4.17.21 版。npm 會依下列順序尋找下列位置的相依性：
+ 在執行 動作的 Docker 映像中。它在這裡找不到它。
+ 在 CodeCatalyst 套件儲存庫中。它在這裡找不到它。
+ 在閘道儲存庫中。它在這裡找不到它。
+ 在 https：//npmjs.com。它會在這裡找到它。
在 npm 在 npmjs.com：// 中找到 4.17.21 版後，它會嘗試將其匯入閘道儲存庫，但因為您設定閘道來封鎖 的匯入`lodash`，所以不會發生匯入。
由於不會發生匯入，工作流程會失敗。
1. 確認工作流程失敗：
1. 在右上角的綠色通知中，選擇執行的連結。連結看起來類似於 `View Run-2345`。
1. 在工作流程圖表中，選擇 **RunHelloWorldApp** 方塊。
1. 展開`npm install`日誌訊息。
出現下列訊息：
```
[Container] 2024/04/25 17:20:34.995591 Running command npm install
npm ERR! code ETARGET
npm ERR! notarget No matching version found for lodash@4.17.21.
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.
npm ERR! A complete log of this run can be found in: /tmp/.npm/_logs/2024-05-08T22_03_26_493Z-debug-0.log
```
錯誤表示找不到 4.17.21 版。這是預期的，因為您將其封鎖。
**從 npmjs.com 取消封鎖匯入**
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇 **npm-publish-registry-gateway**。
1. 選擇 `lodash`。
1. 在頂端附近，選擇**原始伺服器控制項**。
1. 在**上游**下，選擇**允許**。
1. 選擇**儲存**。
您現在已解除封鎖 的匯入`lodash`。
您的工作流程現在可以匯入 4.17.21 版`lodash`。
**測試從 npmjs.com 匯入是否已解除封鎖**
1. 再次執行您的工作流程。這次工作流程應該會成功，因為 4.17.21 的匯入現在應該可以運作。若要再次執行工作流程：
1. 選擇 **CI/CD**，然後選擇**工作流程**。
1. 在 旁`codecatalyst-package-workflow`，選擇**動作**，然後選擇**執行**。
1. 在右上角的綠色通知中，選擇執行的連結。連結看起來類似於 `View Run-3456`。
工作流程圖表隨即出現，顯示誰開始執行和 **RunHelloWorldApp** 動作。
1. 選擇 **RunHelloWorldApp** 動作方塊，以監看動作的進度。
1. 展開`npm list`日誌訊息，並確認出現類似下列的訊息：
```
└── lodash@4.17.21
```
此訊息表示已下載 4.17.21 `lodash`版。
1. 確認 4.17.21 版已匯入您的 CodeCatalyst 和閘道儲存庫：
1. 在導覽窗格中，選擇 **Packages (套件)**。
1. 選擇 **npm-public-registry-gateway**。
1. 尋找`lodash`並確認版本為 `4.17.21`。
**注意**
雖然此頁面未列出 4.17.20 版，但您可以透過選擇頂端附近的**版本**`lodash`來尋找它。
1. 重複這些步驟，檢查 4.17.21 版是否已匯入 `codecatalyst-package-repository`。
## 清除
清除本教學課程中使用的檔案和服務，以避免收取這些檔案和服務的費用。
**清除套件教學課程**
1. 刪除 `codecatalyst-package-project`：
1. 在 CodeCatalyst 主控台中，如果您還沒有專案，請將其命名為`codecatalyst-package-project`專案。
1. 在導覽窗格中，選擇**專案設定**。
1. 選擇**刪除專案**，輸入 **delete**，然後選擇**刪除專案**。
CodeCatalyst 會刪除所有專案資源，包括來源、閘道和 CodeCatalyst 套件儲存庫。開發環境也會遭到刪除。
1. 刪除 PAT 字符：
1. 選擇右側的使用者名稱，然後選擇**我的設定**。
1. 在**個人存取字符**下，選擇您在本教學課程中建立的字符，然後選擇**刪除**。
在本教學課程中，您已了解如何建立工作流程，以執行從 CodeCatalyst 套件儲存庫提取其相依性的應用程式。您也了解如何封鎖和解除封鎖套件，使其無法進入您的閘道和 CodeCatalyst 套件儲存庫。
# 在工作流程中指定 CodeCatalyst 套件儲存庫
在 CodeCatalyst 中，您可以將 CodeCatalyst 套件儲存庫新增至工作流程中的建置和測試動作。您的套件儲存庫必須使用套件格式設定，例如 npm。您也可以選擇包含所選套件儲存庫的範圍序列。
使用下列指示來指定要與工作流程動作搭配使用的套件組態。
------
#### [ Visual ]
**指定動作將使用的套件組態 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要使用套件儲存庫設定的**建置**或**測試**動作。
1. 選擇**套件**。
1. 從**新增組態**下拉式功能表中，選擇您要搭配工作流程動作使用的套件組態。
1. 選擇**新增套件儲存庫**。
1. 在**套件儲存庫**下拉式功能表中，指定您要動作使用的 CodeCatalyst *套件儲存庫*名稱。
如需套件儲存庫的詳細資訊，請參閱 [套件儲存庫](packages-concepts.md#packages-concepts-repository)。
1. （選用） 在**範圍 - 選用**中，指定您要**在套件登錄檔中定義的範圍序列。
定義範圍時，指定的套件儲存庫會設定為所有列出範圍的登錄檔。如果透過 npm 用戶端請求具有 範圍的套件，則會使用該儲存庫，而不是預設值。每個範圍名稱都必須加上 "@" 字首。
如果省略 `Scopes` ，則指定的套件儲存庫會設定為動作使用之所有套件的預設登錄檔。
如需範圍的詳細資訊，請參閱 [套件命名空間](packages-concepts.md#packages-concepts-package-namespaces)和[範圍套件](https://docs.npmjs.com/cli/v10/using-npm/scope)。
1. 選擇**新增**。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**指定 動作將使用的套件組態 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在**建置**或**測試**動作中，新增類似下列的程式碼：
```
action-name:
Configuration:
Packages:
NpmConfiguration:
PackageRegistries:
- PackagesRepository: package-repository
Scopes:
- "@scope"
```
如需詳細資訊，請參閱 中 [建置和測試動作 YAML](build-action-ref.md) 動作的 `Packages` 屬性描述。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 在工作流程動作中使用授權字符
您可以使用工作流程動作提供的權杖，手動設定套件管理員來驗證 CodeCatalyst 套件儲存庫。CodeCatalyst 將此字符做為環境變數提供，供您在 動作中參考。
| 環境變數 | Value |
| --- | --- |
| 代理程式\$1MACHINE\$1RESOURCE\$1NAME | 授權字符的使用者身分。 |
| ACCELERATOR\$1PACKAGES\$1AUTHORIZATION\$1TOKEN | 授權字符的值。 |
**注意**
請注意，只有在您已設定動作匯出授權字符時，才會填入這些環境變數。
使用以下指示，將授權字符與工作流程動作搭配使用。
------
#### [ Visual ]
**使用匯出的授權字符搭配 動作 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要使用套件儲存庫設定的**建置**或**測試**動作。
1. 選擇**套件**。
1. 開啟**匯出授權字符**。
------
#### [ YAML ]
**若要搭配 動作使用匯出的授權字符 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在**建置**或**測試**動作中，新增類似下列的程式碼：
```
Actions:
action-name:
Packages:
ExportAuthorizationToken: true
```
您可以在 YAML 的 `Steps`區段中參考 `$CATALYST_MACHINE_RESOURCE_NAME`和 `$CATALYST_PACKAGES_AUTHORIZATION_TOKEN`環境變數。如需詳細資訊，請參閱 [範例：手動設定 `pip`以使用 CodeCatalyst 驗證](workflows-working-packages-ex.md#workflows-working-packages-pypi-token)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 範例：工作流程中的套件儲存庫
下列範例示範如何參考工作流程定義檔案中的套件。
**Topics**
+ [範例：使用 定義套件 `NpmConfiguration`](#workflows-working-packages-ex-basic)
+ [範例：覆寫預設登錄檔](#workflows-working-packages-ex-overriding-registry)
+ [範例：覆寫套件登錄檔中的範圍](#workflows-working-packages-ex-overriding-scopes)
+ [範例：手動設定 `pip`以使用 CodeCatalyst 驗證](#workflows-working-packages-pypi-token)
## 範例：使用 定義套件 `NpmConfiguration`
下列範例顯示如何在`NpmConfiguration`工作流程定義檔案中使用 定義套件。
```
Actions:
Build:
Identifier: aws/build-beta@v1
Configuration:
Packages:
NpmConfiguration:
PackageRegistries:
- PackagesRepository: main-repo
- PackagesRepository: scoped-repo
Scopes:
- "@scope1"
```
此範例會設定 npm 用戶端，如下所示：
```
default: main-repo
@scope1: scoped-repo
```
在此範例中，已定義兩個儲存庫。預設登錄檔會設定為沒有範圍`main-repo`的定義。範圍`@scope1`是在 中`PackageRegistries`為 設定`scoped-repo`。
## 範例：覆寫預設登錄檔
下列範例說明如何覆寫預設登錄檔。
```
NpmConfiguration:
PackageRegistries:
- PackagesRepository: my-repo-1
- PackagesRepository: my-repo-2
- PackagesRepository: my-repo-3
```
此範例會設定 npm 用戶端，如下所示：
```
default: my-repo-3
```
如果您指定多個預設儲存庫，最後一個儲存庫將優先處理。在此範例中，列出的最後一個儲存庫是 `my-repo-3`，這表示 npm 會連線至 `my-repo-3`。這會覆寫儲存庫 `my-repo-1`和 `my-repo-2`。
## 範例：覆寫套件登錄檔中的範圍
下列範例說明如何覆寫套件登錄檔中的範圍。
```
NpmConfiguration:
PackageRegistries:
- PackagesRepository: my-default-repo
- PackagesRepository: my-repo-1
Scopes:
- "@scope1"
- "@scope2"
- PackagesRepository: my-repo-2
Scopes:
- "@scope2"
```
此範例會設定 npm 用戶端，如下所示：
```
default: my-default-repo
@scope1: my-repo-1
@scope2: my-repo-2
```
如果您包含覆寫範圍，最後一個儲存庫將優先處理。在此範例中，上次在 中設定範圍`@scope2`的時間`PackageRegistries`是 `my-repo-2`。這會覆寫為 `@scope2`設定的範圍`my-repo-1`。
## 範例：手動設定 `pip`以使用 CodeCatalyst 驗證
下列範例示範如何在建置動作中參考 CodeCatalyst 授權環境變數。
```
Actions:
Build:
Identifier: aws/build@v1.0.0
Configuration:
Steps:
- Run: pip config set global.index-url https://$CATALYST_MACHINE_RESOURCE_NAME:$CATALYST_PACKAGES_AUTHORIZATION_TOKEN@codecatalyst.aws/pypi/my-space/my-project/my-repo/simple/
Packages:
ExportAuthorizationToken: true
```
# 使用工作流程叫用 Lambda 函數
本節說明如何使用 CodeCatalyst 工作流程叫用 AWS Lambda 函數。若要達成此目的，您必須將**AWS Lambda 調用**動作新增至工作流程。**AWS Lambda 叫用**動作會叫用您指定的 Lambda 函數。
除了叫用函數之外，**AWS Lambda 叫用**動作也會將從 Lambda 函數收到的回應承載中的每個最上層金鑰轉換為[工作流程輸出變數](workflows-working-with-variables.md)。然後，您可以在後續工作流程動作中參考這些變數。如果您不希望將所有最上層金鑰轉換為變數，您可以使用篩選條件來指定確切的金鑰。如需詳細資訊，請參閱 中的[ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters)屬性描述[「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)。
**Topics**
+ [何時使用此動作](#lam-invoke-action-when-to-use)
+ [「AWS Lambda 調用」動作使用的執行期映像](#lam-invoke-action-runtime)
+ [範例：叫用 Lambda 函數](lam-invoke-action-example-workflow.md)
+ [新增「AWS Lambda 調用」動作](lam-invoke-action-add.md)
+ [「AWS Lambda 叫用」變數](lam-invoke-action-variables.md)
+ [「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)
## 何時使用此動作
如果您想要在 Lambda 函數中封裝和執行的工作流程中新增功能，請使用此動作。
例如，您可能希望工作流程先將`Build started`通知傳送至 Slack 頻道，再開始建置您的應用程式。在這種情況下，您的工作流程將包含**AWS Lambda 調用** Lambda 以傳送 Slack 通知的調用動作，以及建置您應用程式的[建置動作](build-add-action.md)。
另一個範例是，您可能希望工作流程在部署之前對您的應用程式執行漏洞掃描。在這種情況下，您會使用建置動作來建置應用程式、**AWS Lambda 叫用**動作來叫用 Lambda 來掃描漏洞，以及使用部署動作來部署掃描的應用程式。
## 「AWS Lambda 調用」動作使用的執行期映像
**AWS Lambda 調用**動作會在 [2022 年 11 月的映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 範例：叫用 Lambda 函數
下列範例工作流程包含**AWS Lambda 調用**動作，以及部署動作。工作流程會傳送 Slack 通知，指出部署已開始，然後使用 AWS CloudFormation 範本將應用程式部署至 。工作流程包含下列依順序執行的建置區塊：
+ **觸發**條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **AWS Lambda 叫用**動作 (`LambdaNotify`) – 在觸發時，此動作會在指定的 AWS 帳戶和區域 ( `my-aws-account`和 ) 中叫用 `Notify-Start` Lambda 函數`us-west-2`。叫用時，Lambda 函數會傳送 Slack 通知，指出已開始部署。
+ **部署 CloudFormation 堆疊**動作 (`Deploy`) – 完成**AWS Lambda 調用**動作時，**部署 CloudFormation 堆疊**動作會執行範本 (`cfn-template.yml`) 來部署應用程式堆疊。如需**部署 CloudFormation 堆疊**動作的詳細資訊，請參閱 [部署 CloudFormation 堆疊](deploy-action-cfn.md)。
**注意**
下列工作流程範例僅供說明之用，如果沒有其他組態，將無法運作。
**注意**
在接下來的 YAML 程式碼中，您可以視需要省略這些`Connections:`區段。如果您省略這些區段，您必須確保環境中**預設 IAM 角色**欄位中指定的角色包含**AWS Lambda 叫用**和**部署 CloudFormation 堆疊**動作所需的許可和信任政策。如需使用預設 IAM 角色設定環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。如需**AWS Lambda 叫用**和**部署 CloudFormation 堆疊**動作所需的許可和信任政策的詳細資訊，請參閱 [「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)和 中的 `Role` 屬性描述[「部署 CloudFormation 堆疊」動作 YAML](deploy-action-ref-cfn.md)。
```
Name: codecatalyst-lamda-invoke-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
LambdaNotify:
Identifier: aws/lambda-invoke@v1
Environment:
Name: my-production-environment
Connections:
- Name: my-aws-account
Role: codecatalyst-lambda-invoke-role
Inputs:
Sources:
- WorkflowSource
Configuration:
Function: Notify-Start
AWSRegion: us-west-2
Deploy:
Identifier: aws/cfn-deploy@v1
Environment:
Name: my-production-environment
Connections:
- Name: my-aws-account
Role: codecatalyst-deploy-role
Inputs:
Sources:
- WorkflowSource
Configuration:
name: my-application-stack
region: us-west-2
role-arn: arn:aws:iam::111122223333:role/StackRole
template: ./cfn-template.yml
capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
```
# 新增「AWS Lambda 調用」動作
使用下列指示將**AWS Lambda 調用**動作新增至您的工作流程。
**先決條件**
開始之前，請確定您的 AWS Lambda 函數和相關聯的 Lambda 執行角色已準備就緒且可供使用 AWS。如需詳細資訊，請參閱《 *AWS Lambda 開發人員指南*》中的 [Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)主題。
------
#### [ Visual ]
**使用視覺化編輯器新增「AWS Lambda 調用」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS Lambda 叫用**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**AWS Lambda 叫用**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**、**組態**和**輸出**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增「AWS Lambda 調用」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**AWS Lambda 叫用**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**AWS Lambda 叫用**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 「AWS Lambda 叫用」變數
根據預設，**AWS Lambda 叫用**動作會在 Lambda 回應承載中的每個頂層金鑰產生一個變數。
例如，如果回應承載如下所示：
```
responsePayload = {
"name": "Saanvi",
"location": "Seattle",
"department": {
"company": "Amazon",
"team": "AWS"
}
}
```
...然後，動作會產生下列變數。
| 金鑰 | 值 |
| --- | --- |
| name | Saanvi |
| location | 西雅圖 |
| department | \$1"company"： "Amazon"、"team"： "AWS"\$1 |
**注意**
您可以使用 `ResponseFilters` YAML 屬性變更產生的變數。如需詳細資訊，請參閱《[ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters)》中的 [「AWS Lambda 叫用」動作 YAML](lam-invoke-action-ref.md)。
「AWS Lambda 叫用」動作在執行時間產生和設定的變數稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
# 「AWS Lambda 叫用」動作 YAML
以下是**AWS Lambda 叫用**動作的 YAML 定義。若要了解如何使用此動作，請參閱 [使用工作流程叫用 Lambda 函數](lam-invoke-action.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素會與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
LambdaInvoke\$1nn:
Identifier: aws/lambda-invoke@v1
DependsOn:
- dependent-action
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- request-payload
Variables:
- Name: variable-name-1
Value: variable-value-1
- Name: variable-name-2
Value: variable-value-2
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
Configuration:
Function: my-function|function-arn
AWSRegion: us-west-2
# Specify RequestPayload or RequestPayloadFile, but not both.
RequestPayload: '{"firstname": "Li", lastname: "Jean", "company": "ExampleCo", "team": "Development"}'
RequestPayloadFile: my/request-payload.json
ContinueOnError: true|false
LogType: Tail|None
ResponseFilters: '{"name": ".name", "company": ".department.company"}'
Outputs:
Artifacts:
- Name: lambda_artifacts
Files:
- "lambda-response.json"
```
## LambdaInvoke
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在動作名稱中啟用特殊字元和空格。
預設：`Lambda_Invoke_Action_Workflow_nn`。
對應的 UI：組態索引標籤/**動作名稱**
## Identifier
(*LambdaInvoke*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/lambda-invoke@v1`。
對應的 UI：工作流程圖表/LambdaInvoke\$1nn/**aws/lambda-invoke@v1** 標籤
## DependsOn
(*LambdaInvoke*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*LambdaInvoke*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*LambdaInvoke*/Compute/**Type**)
（如果[Compute](#lam.invoke.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
最佳化動作執行期間的彈性。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化的動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/**運算類型**
## Fleet
(*LambdaInvoke*/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`。
對應的 UI：組態索引標籤/**運算機群**
## Timeout
(*LambdaInvoke*/**Timeout**)
(必要)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Inputs
(*LambdaInvoke*/**Inputs**)
(必要)
`Inputs` 區段定義在工作流程執行期間**AWS Lambda 叫用**動作所需的資料。
**注意**
每個**AWS Lambda 叫用**動作只允許一個輸入 （來源或成品）。變數不會計入此總計。
對應的 UI：**輸入**索引標籤
## Sources
(*LambdaInvoke*/Inputs/**Sources**)
（如果提供 [RequestPayloadFile](#lam.invoke.request.payload.file) 則為必要）
如果您想要將請求承載 JSON 檔案傳遞至**AWS Lambda 叫用**動作，且此承載檔案存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的請求承載檔案不包含在來源儲存庫中，它必須位於另一個動作所產生的成品中。
如需承載檔案的詳細資訊，請參閱 [RequestPayloadFile](#lam.invoke.request.payload.file)。
**注意**
您可以直接使用 `RequestPayload` 屬性將承載的 JSON 程式碼新增至動作，而不是指定承載檔案。如需詳細資訊，請參閱[RequestPayload](#lam.invoke.request.payload)。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*LambdaInvoke*/Inputs/**Artifacts**)
（如果提供 [RequestPayloadFile](#lam.invoke.request.payload.file) 則為必要）
如果您想要將請求承載 JSON 檔案傳遞至**AWS Lambda 叫用**動作，且此承載檔案包含在先前動作的[輸出成品](build-action-ref.md#build.outputs.artifacts)中，請在此處指定該成品。
如需承載檔案的詳細資訊，請參閱 [RequestPayloadFile](#lam.invoke.request.payload.file)。
**注意**
您可以直接使用 `RequestPayload` 屬性將承載的 JSON 程式碼新增至動作，而不是指定承載檔案。如需詳細資訊，請參閱[RequestPayload](#lam.invoke.request.payload)。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**成品 - 選用**
## Variables - input
(*LambdaInvoke*/Inputs/**Variables**)
(選用)
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸入索引標籤/**變數 - 選用**
## Environment
(*LambdaInvoke*/**Environment**)
(必要)
指定要與 動作搭配使用的 CodeCatalyst 環境。動作會連線至所選環境中指定的 AWS 帳戶 和選用 Amazon VPC。動作會使用環境中指定的預設 IAM 角色來連線至 AWS 帳戶，並使用 [Amazon VPC 連線](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色來連線至 Amazon VPC。
**注意**
如果預設 IAM 角色沒有 動作所需的許可，您可以將 動作設定為使用不同的角色。如需詳細資訊，請參閱[變更 動作的 IAM 角色](deploy-environments-switch-role.md)。
如需環境的詳細資訊，請參閱 [部署至 AWS 帳戶 和 VPCs](deploy-environments.md)和 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：組態索引標籤/**環境**
## Name
(*LambdaInvoke*/Environment/**Name**)
（如果[Environment](#lam.invoke.environment)包含 則為必要）
指定您要與動作建立關聯的現有環境名稱。
對應的 UI：組態索引標籤/**環境**
## Connections
(*LambdaInvoke*/Environment/**Connections**)
（在較新版本的動作中為選用；在較舊版本中為必要）
指定要與動作建立關聯的帳戶連線。您可以在 下指定最多一個帳戶連線`Environment`。
如果您未指定帳戶連線：
+ 動作會使用 CodeCatalyst 主控台中環境指定的 AWS 帳戶 連線和預設 IAM 角色。如需將帳戶連線和預設 IAM 角色新增至環境的相關資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
+ 預設 IAM 角色必須包含 動作所需的政策和許可。若要判斷這些政策和許可是什麼，請參閱動作 YAML 定義文件中**角色**屬性的描述。
如需帳戶連線的詳細資訊，請參閱 [允許存取已連線 AWS 的資源 AWS 帳戶](ipa-connect-account.md)。如需將帳戶連線新增至環境的詳細資訊，請參閱 [建立環境](deploy-environments-creating-environment.md)。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Name
(*LambdaInvoke*/Environment/Connections/**Name**)
（如果[Connections](#lam.invoke.environment.connections)包含 則為必要）
指定帳戶連線的名稱。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**AWS account connection**
## Role
(*LambdaInvoke*/Environment/Connections/**Role**)
（如果[Connections](#lam.invoke.environment.connections)包含 則為必要）
指定**AWS Lambda 叫用**動作用來存取 AWS 和叫用 Lambda 函數的 IAM 角色名稱。請確定您已[將角色新增至 CodeCatalyst 空間](ipa-connect-account-addroles.md)，且該角色包含下列政策。
如果您未指定 IAM 角色，則動作會使用 CodeCatalyst 主控台中[環境中](deploy-environments.md)列出的預設 IAM 角色。如果您在環境中使用預設角色，請確定其具有下列政策。
+ 下列許可政策：
**警告**
將許可限制為下列政策中顯示的許可。使用具有更廣泛許可的角色可能會帶來安全風險。
+ 下列自訂信任政策：
**注意**
如有需要，您可以使用 `CodeCatalystWorkflowDevelopmentRole-spaceName`角色搭配此動作。如需有關此角色的詳細資訊，請參閱 [為您的帳戶和空間建立 **CodeCatalystWorkflowDevelopmentRole-*spaceName***角色](ipa-iam-roles.md#ipa-iam-roles-service-create)。了解該`CodeCatalystWorkflowDevelopmentRole-spaceName`角色具有可能造成安全風險的完整存取許可。我們建議您只在安全性較少的教學課程和案例中使用此角色。
對應的 UI：取決於動作版本，下列其中一項：
+ （較新版本） 組態tab/Environment/What是 *my-environment*？/三個點功能表/**切換角色**
+ （舊版本） 組態索引標籤/'Environment/account/role'/**Role**
## Configuration
(*LambdaInvoke*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## Function
(*LambdaInvoke*/Configuration/**Function**)
(必要)
指定此動作將叫用的 AWS Lambda 函數。您可以指定函數的名稱，或其 Amazon Resource Name (ARN)。您可以在 Lambda 主控台中找到名稱或 ARN。
**注意**
Lambda 函數所在的 AWS 帳戶可能與 下指定的帳戶不同`Connections:`。
對應的 UI：組態索引標籤/**函數**
## AWSRegion
(*LambdaInvoke*/Configuration/**AWSRegion**)
(必要)
指定 AWS Lambda 函數所在的 AWS 區域。如需區域代碼清單，請參閱《》中的[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)*AWS 一般參考*。
對應的 UI：組態索引標籤/**目的地儲存貯體 - 選用**
## RequestPayload
(*LambdaInvoke*/Configuration/**RequestPayload**)
(選用)
如果您想要將請求承載傳遞給**AWS Lambda 叫用**動作，請在此處以 JSON 格式指定請求承載。
請求承載範例：
```
'{ "key": "value" }'
```
如果您不想將請求承載傳遞至 Lambda 函數，請省略此屬性。
**注意**
您可以指定 `RequestPayload` 或 `RequestPayloadFile`，但不能同時指定兩者。
如需請求承載的詳細資訊，請參閱 *AWS Lambda API 參考*中的[叫用](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)主題。
對應的 UI：組態索引標籤/**請求承載 - 選用**
## RequestPayloadFile
(*LambdaInvoke*/Configuration/**RequestPayloadFile**)
(選用)
如果您想要將請求承載傳遞至**AWS Lambda 叫用**動作，請在此處指定此請求承載檔案的路徑。檔案必須是 JSON 格式。
請求承載檔案可以位於來源儲存庫或先前動作的成品中。檔案路徑是相對於來源儲存庫或成品根目錄。
如果您不想將請求承載傳遞至 Lambda 函數，請省略此屬性。
**注意**
您可以指定 `RequestPayload` 或 `RequestPayloadFile`，但不能同時指定兩者。
如需請求承載檔案的詳細資訊，請參閱 *AWS Lambda API 參考*中的[叫用](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)主題。
對應的 UI：組態索引標籤/**請求承載檔案 - 選用**
## ContinueOnError
(*LambdaInvoke*/Configuration/**RequestPayloadFile**)
(選用)
指定您是否想要將**AWS Lambda 調用**動作標記為成功，即使調用的 AWS Lambda 函數失敗。考慮將此屬性設定為 `true` ，以允許工作流程中的後續動作在 Lambda 失敗時啟動。
預設值是，如果 Lambda 函數失敗 （視覺化編輯器或 YAML 編輯器中的 "off")`false`，則動作會失敗。
對應的 UI：組態索引標籤/**發生錯誤時繼續**
## LogType
(*LambdaInvoke*/Configuration/**LogType**)
(選用)
指定是否要在叫用 Lambda 函數後的回應中包含錯誤日誌。您可以在 CodeCatalyst 主控台的 **Lambda 調用**動作的日誌索引標籤中檢視這些**日誌**。可能值為：
+ `Tail` – 傳回日誌
+ `None` – 不傳回日誌
預設值為 **Tail**。
如需日誌類型的詳細資訊，請參閱 *AWS Lambda API 參考*中的[叫用](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)主題。
如需檢視日誌檔案的詳細資訊，請參閱[檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
對應的 UI：組態索引標籤/**日誌類型**
## ResponseFilters
(*LambdaInvoke*/Configuration/**ResponseFilters**)
(選用)
指定您要轉換為輸出變數的 Lambda 回應承載中的哪些索引鍵。然後，您可以在工作流程的後續動作中參考輸出變數。如需 CodeCatalyst 中變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
例如，如果您的回應承載如下所示：
```
responsePayload = {
"name": "Saanvi",
"location": "Seattle",
"department": {
"company": "Amazon",
"team": "AWS"
}
}
```
...您的回應篩選條件如下所示：
```
Configuration:
...
ResponseFilters: '{"name": ".name", "company": ".department.company"}'
```
...然後動作會產生下列輸出變數：
| 金鑰 | 值 |
| --- | --- |
| name | Saanvi |
| company | Amazon |
然後，您可以在後續動作中參考 `name`和 `company`變數。
如果您未在 中指定任何金鑰`ResponseFilters`，則動作會將 Lambda 回應中的每個最上層金鑰轉換為輸出變數。如需詳細資訊，請參閱[「AWS Lambda 叫用」變數](lam-invoke-action-variables.md)。
考慮使用回應篩選條件，將產生的輸出變數限制為您實際要使用的變數。
對應的 UI：組態索引標籤/**回應篩選條件 - 選用**
## Outputs
(*LambdaInvoke*/**Outputs**)
(選用)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts
(*LambdaInvoke*/Outputs/**Artifacts**)
(選用)
指定 動作產生的成品。您可以在其他動作中參考這些成品做為輸入。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/成品/**建置成品名稱**
## Name
(*LambdaInvoke*/Outputs/Artifacts/**Name**)
(選用)
指定將包含 Lambda 函數傳回之 Lambda 回應承載的成品名稱。預設值為 `lambda_artifacts`。如果您未指定成品，則可以在動作的日誌中檢視 Lambda 回應承載，這可在 CodeCatalyst 主控台中動作**的日誌**索引標籤上取得。如需檢視日誌檔案的詳細資訊，請參閱[檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
對應的 UI：輸出索引標籤/成品/**組建成品名稱**
## Files
(*LambdaInvoke*/Outputs/Artifacts/**Files**)
(選用)
指定要包含在成品中的檔案。您必須指定 ，`lambda-response.json`以便包含 Lambda 回應承載檔案。
對應的 UI：輸出索引標籤/成品/**組建產生的檔案**
# 修改 Amazon ECS 任務定義
本節說明如何使用 CodeCatalyst 工作流程更新 Amazon Elastic Container Service (Amazon ECS) [任務定義檔案中](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)`image`的欄位。若要達成此目的，您必須將**轉譯 Amazon ECS 任務定義**動作新增至工作流程。此動作會使用工作流程在執行時間提供的 Docker 映像名稱，更新任務定義檔案中的映像欄位。
**注意**
您也可以使用此動作，以環境變數更新任務定義的`environment`欄位。
**Topics**
+ [何時使用此動作](#render-ecs-action-when-to-use)
+ [「轉譯 Amazon ECS 任務定義」動作的運作方式](#render-ecs-action-how-it-works)
+ [「轉譯 Amazon ECS 任務定義」動作所使用的執行期映像](#render-ecs-action-runtime)
+ [範例：修改 Amazon ECS taskdef](render-ecs-action-example-workflow.md)
+ [新增「轉譯 Amazon ECS 任務定義」動作](render-ecs-action-add.md)
+ [檢視更新的任務定義檔案](render-ecs-action-view.md)
+ [「轉譯 Amazon ECS 任務定義」變數](render-ecs-action-variables.md)
+ [「轉譯 Amazon ECS 任務定義」動作 YAML](render-ecs-action-ref.md)
## 何時使用此動作
如果您有使用動態內容建置和標記 Docker 映像的工作流程，例如遞交 ID 或時間戳記，請使用此選項。
如果您的任務定義檔案包含一律保持不變的影像值，請勿使用此動作。在這種情況下，您可以將映像的名稱手動輸入任務定義檔案中。
## 「轉譯 Amazon ECS 任務定義」動作的運作方式
您必須在工作流程中使用**轉譯 Amazon ECS 任務定義**動作搭配**建置**和**部署至 Amazon ECS** 動作。這些動作一起運作的方式如下：
1. **建置**動作會建置您的 Docker 映像，並使用名稱、遞交 ID、時間戳記或其他動態內容加以標記。例如，您的建置動作可能如下所示：
```
MyECSWorkflow
Actions:
BuildAction:
Identifier: aws/build@v1
...
Configuration:
Steps:
# Build, tag, and push the Docker image...
- Run: docker build -t MyDockerImage:${WorkflowSource.CommitId} .
...
```
在上述程式碼中， `docker build -t`指令指示 建置 Docker 映像，並在動作執行時間使用遞交 ID 標記映像。產生的映像名稱可能如下所示：
`MyDockerImage:a37bd7e`
1. **轉譯 Amazon ECS 任務定義**動作會將動態產生的映像名稱 `MyDockerImage:a37bd7e`新增至您的任務定義檔案，如下所示：
```
{
"executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
"containerDefinitions": [
{
"name": "codecatalyst-ecs-container",
"image": MyDockerImage:a37bd7e,
"essential": true,
...
"portMappings": [
{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
}
]
}
],
...
}
```
您也可以選擇讓**轉譯 Amazon ECS 任務定義**動作將環境變數新增至任務定義，如下所示：
```
{
"executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
"containerDefinitions": [
{
"name": "codecatalyst-ecs-container",
"image": MyDockerImage:a37bd7e,
...
"environment": [
{
name": "ECS_LOGLEVEL",
value": "info"
}
]
}
],
...
}
```
如需環境變數的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[指定環境變數](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html)。
1. **部署至 Amazon ECS** 動作會向 Amazon ECS 註冊更新的任務定義檔案。註冊更新的任務定義檔案會將新映像部署`MyDockerImage:a37bd7e`到 Amazon ECS。
## 「轉譯 Amazon ECS 任務定義」動作所使用的執行期映像
**轉譯 Amazon ECS 任務定義**動作會在 [2022 年 11 月映像](build-images.md#build.previous-image)上執行。如需詳細資訊，請參閱[作用中映像](build-images.md#build-curated-images)。
# 範例：修改 Amazon ECS taskdef
以下是包含**轉譯 Amazon ECS 任務定義**動作，以及建置和部署動作的完整工作流程範例。工作流程的目的是在 Amazon ECS 叢集中建置和部署 Docker 映像。工作流程包含下列依順序執行的建置區塊：
+ **觸發**條件 – 當您將變更推送至來源儲存庫時，此觸發條件會自動啟動工作流程執行。關於觸發條件的詳細資訊，請參閱 [使用觸發程序自動啟動工作流程執行](workflows-add-trigger.md)。
+ **建置**動作 (`BuildDocker`) – 觸發時，動作會使用 Dockerfile 建置 Docker 映像、使用遞交 ID 標記映像，並將映像推送至 Amazon ECR。如需建置動作的詳細資訊，請參閱 [使用工作流程建置](build-workflow-actions.md)。
+ **轉譯 Amazon ECS 任務定義**動作 (`RenderTaskDef`) – 建置動作完成後，此動作會使用包含正確遞交 ID `image`的欄位值，來更新`taskdef.json`位於來源儲存庫根中的現有 。它會使用新的檔案名稱 (`task-definition-random-string.json`) 儲存更新的檔案，然後建立包含此檔案的輸出成品。轉譯動作也會產生名為 的變數，`task-definition`並將其設定為新任務定義檔案的名稱。成品和變數將用於部署動作，接下來是 。
+ 部署**至 Amazon ECS** 動作 (`DeployToECS`) – **轉譯 Amazon ECS 任務定義**動作完成後，**部署至 Amazon ECS** 動作會尋找轉譯動作 (`TaskDefArtifact`) 產生的輸出成品、尋找其中`task-definition-random-string.json`的檔案，並將其註冊至 Amazon ECS 服務。然後，Amazon ECS 服務會遵循 `task-definition-random-string.json` 檔案中的指示，在您的 Amazon ECS 叢集內執行 Amazon ECS 任務以及相關聯的 Docker 映像容器。
```
Name: codecatalyst-ecs-workflow
SchemaVersion: 1.0
Triggers:
- Type: PUSH
Branches:
- main
Actions:
BuildDocker:
Identifier: aws/build@v1
Environment:
Name: codecatalyst-ecs-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-ecs-build-role
Inputs:
Variables:
- Name: REPOSITORY_URI
Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
- Name: IMAGE_TAG
Value: ${WorkflowSource.CommitId}
Configuration:
Steps:
#pre_build:
- Run: echo Logging in to Amazon ECR...
- Run: aws --version
- Run: aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-2.amazonaws.com
#build:
- Run: echo Build started on `date`
- Run: echo Building the Docker image...
- Run: docker build -t $REPOSITORY_URI:latest .
- Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
#post_build:
- Run: echo Build completed on `date`
- Run: echo Pushing the Docker images...
- Run: docker push $REPOSITORY_URI:latest
- Run: docker push $REPOSITORY_URI:$IMAGE_TAG
RenderTaskDef:
DependsOn:
- BuildDocker
Identifier: aws/ecs-render-task-definition@v1
Inputs:
Variables:
- Name: REPOSITORY_URI
Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
- Name: IMAGE_TAG
Value: ${WorkflowSource.CommitId}
Configuration:
task-definition: taskdef.json
container-definition-name: codecatalyst-ecs-container
image: $REPOSITORY_URI:$IMAGE_TAG
# The output artifact contains the updated task definition file.
# The new file is prefixed with 'task-definition'.
# The output variable is set to the name of the updated task definition file.
Outputs:
Artifacts:
- Name: TaskDefArtifact
Files:
- "task-definition*"
Variables:
- task-definition
DeployToECS:
Identifier: aws/ecs-deploy@v1
Environment:
Name: codecatalyst-ecs-environment
Connections:
- Name: codecatalyst-account-connection
Role: codecatalyst-ecs-deploy-role
#Input artifact contains the updated task definition file.
Inputs:
Sources: []
Artifacts:
- TaskDefArtifact
Configuration:
region: us-east-2
cluster: codecatalyst-ecs-cluster
service: codecatalyst-ecs-service
task-definition: ${RenderTaskDef.task-definition}
```
# 新增「轉譯 Amazon ECS 任務定義」動作
使用下列指示，將**轉譯 Amazon ECS 任務定義**動作新增至您的工作流程。
**先決條件**
開始之前，請確定您有一個工作流程，其中包含可動態產生 Docker 映像的建置動作。如需詳細資訊，請參閱上述[範例工作流程](render-ecs-action-example-workflow.md)。
------
#### [ Visual ]
**使用視覺化編輯器新增「轉譯 Amazon ECS 任務定義」動作**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**轉譯 Amazon ECS 任務定義**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**轉譯 Amazon ECS 任務定義**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 在**輸入**和**組態**索引標籤中，根據您的需求完成欄位。如需每個欄位的說明，請參閱 [「轉譯 Amazon ECS 任務定義」動作 YAML](render-ecs-action-ref.md)。此參考提供在 YAML 和視覺化編輯器中顯示的每個欄位 （和對應的 YAML 屬性值） 的詳細資訊。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**使用 YAML 編輯器新增「轉譯 Amazon ECS 任務定義」動作**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在左上角，選擇 **\$1 動作**以開啟動作目錄。
1. 從下拉式清單中，選擇 **Amazon CodeCatalyst**。
1. 搜尋**轉譯 Amazon ECS 任務定義**動作，並執行下列其中一項操作：
+ 選擇加號 (**\$1**) 將動作新增至工作流程圖表，並開啟其組態窗格。
或
+ 選擇**轉譯 Amazon ECS 任務定義**。動作詳細資訊對話方塊隨即出現。在此對話方塊中：
+ （選用） 選擇**檢視來源**[以檢視動作的原始程式碼](workflows-view-source.md#workflows-view-source.title)。
+ 選擇**新增至工作流程**，將動作新增至工作流程圖表，然後開啟其組態窗格。
1. 根據您的需求修改 YAML 程式碼中的屬性。中提供了每個可用屬性的說明[「轉譯 Amazon ECS 任務定義」動作 YAML](render-ecs-action-ref.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
**後續步驟**
新增轉譯動作之後，請依照 中的指示，將**部署至 Amazon ECS** 動作新增至您的工作流程[使用工作流程部署至 Amazon ECS](deploy-action-ecs.md)。在新增部署動作時，請執行下列動作：
1. 在部署動作的**輸入**索引標籤中，在**成品 - 選用**中，選取轉譯動作產生的成品。它包含更新的任務定義檔案。
如需成品的詳細資訊，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
1. 在部署動作的**組態**索引標籤中，在**任務定義**欄位中指定下列動作變數：`${action-name.task-definition}`其中 *action-name* 是轉譯動作的名稱，例如 `RenderTaskDef`。轉譯動作會將此變數設定為任務定義檔案的新名稱。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
如需如何設定部署動作的詳細資訊，請參閱上述[工作流程範例](render-ecs-action-example-workflow.md)。
# 檢視更新的任務定義檔案
您可以檢視更新任務定義檔案的名稱和內容。
**若要檢視更新的任務定義檔案名稱，請在**轉譯 Amazon ECS 任務定義**動作處理完畢之後。**
1. 尋找包含已完成轉譯動作的執行：
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇包含已完成轉譯動作的執行。
1. 在工作流程圖表中，選擇轉譯動作。
1. 選擇**輸出**。
1. 選擇**變數**。
1. 任務定義檔案名稱隨即顯示。它看起來類似於 `task-definition--259-0a2r7gxlTF5X-.json`。
**檢視更新任務定義檔案的內容**
1. 尋找包含已完成轉譯動作的執行：
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇包含已完成轉譯動作的執行。
1. 在工作流程執行中，在頂端的**視覺化**和 **YAML** 旁，選擇**工作流程輸出**。
1. 在**成品**區段中，選擇包含更新任務定義檔案的成品旁的**下載**。此成品會將 **Produced by** column 設定為轉譯動作的名稱。
1. 開啟 .zip 檔案以檢視任務定義 .json 檔案。
# 「轉譯 Amazon ECS 任務定義」變數
**轉譯 Amazon ECS 任務定義**動作會在執行時間產生並設定下列變數。這些稱為*預先定義的變數*。
如需在工作流程中參考這些變數的資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
| 金鑰 | 值 |
| --- | --- |
| 任務定義 | 提供給由**轉譯 Amazon ECS 任務定義動作更新之任務定義**檔案的名稱。名稱會遵循格式 `task-definition-random-string.json`。 範例：`task-definition--259-0a2r7gxlTF5Xr.json` |
# 「轉譯 Amazon ECS 任務定義」動作 YAML
以下是**轉譯 Amazon ECS 任務定義動作的 YAML 定義**。若要了解如何使用此動作，請參閱 [修改 Amazon ECS 任務定義](render-ecs-action.md)。
此動作定義以區段的形式存在於更廣泛的工作流程定義檔案中。如需有關此檔案的詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。
**注意**
下列大多數 YAML 屬性在視覺化編輯器中都有對應的 UI 元素。若要查詢 UI 元素，請使用 **Ctrl\$1F**。 元素將與其相關聯的 YAML 屬性一起列出。
```
# The workflow definition starts here.
# See 最上層屬性 for details.
Name: MyWorkflow
SchemaVersion: 1.0
Actions:
# The action definition starts here.
ECSRenderTaskDefinition\$1nn:
Identifier: aws/ecs-render-task-definition@v1
DependsOn:
- build-action
Compute:
Type: EC2 | Lambda
Fleet: fleet-name
Timeout: timeout-minutes
Inputs:
# Specify a source or an artifact, but not both.
Sources:
- source-name-1
Artifacts:
- task-definition-artifact
Variables:
- Name: variable-name-1
Value: variable-value-1
- Name: variable-name-2
Value: variable-value-2
Configuration
task-definition: task-definition-path
container-definition-name: container-definition-name
image: docker-image-name
environment-variables:
- variable-name-1=variable-value-1
- variable-name-2=variable-value-2
Outputs:
Artifacts:
- Name: TaskDefArtifact
Files: "task-definition*"
Variables:
- task-definition
```
## ECSRenderTaskDefinition
(必要)
指定動作的名稱。工作流程中的所有動作名稱都必須是唯一的。動作名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您無法使用引號在動作名稱中啟用特殊字元和空格。
預設：`ECSRenderTaskDefinition_nn`。
對應的 UI：組態索引標籤/**動作名稱**
## Identifier
(*ECSRenderTaskDefinition*/**Identifier**)
(必要)
識別 動作。除非您想要變更版本，否則請勿變更此屬性。如需詳細資訊，請參閱[指定要使用的動作版本](workflows-action-versions.md)。
預設：`aws/ecs-render-task-definition@v1`。
對應的 UI：工作流程圖表/ECSRenderTaskDefinition\$1nn/**aws/ecs-render-task-definition@v1** 標籤
## DependsOn
(*ECSRenderTaskDefinition*/**DependsOn**)
(選用)
指定必須成功執行的動作、動作群組或閘道，才能執行此動作。
如需 'depends on' 功能的詳細資訊，請參閱 [定序動作](workflows-depends-on.md)。
對應的 UI：輸入索引標籤/**取決於 - 選用**
## Compute
(*ECSRenderTaskDefinition*/**Compute**)
(選用)
用來執行工作流程動作的運算引擎。您可以在工作流程層級或動作層級指定運算，但不能同時指定兩者。在工作流程層級指定時，運算組態會套用至工作流程中定義的所有動作。在工作流程層級，您也可以在同一個執行個體上執行多個動作。如需詳細資訊，請參閱[跨動作共用運算](compute-sharing.md)。
對應的 UI：*無*
## Type
(*ECSRenderTaskDefinition*/Compute/**Type**)
（如果[Compute](#render.ecs.computename)包含 則為必要）
運算引擎的類型。您可以使用下列其中一個值：
+ **EC2** （視覺化編輯器） 或 `EC2`(YAML 編輯器）
針對動作執行期間的彈性進行最佳化。
+ **Lambda** （視覺化編輯器） 或 `Lambda`(YAML 編輯器）
最佳化動作啟動速度。
如需運算類型的更多相關資訊，請參閱[運算類型](workflows-working-compute.md#compute.types)。
對應的 UI：組態索引標籤/**運算類型**
## Fleet
(*ECSRenderTaskDefinition*/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`。
對應的 UI：組態索引標籤/**運算機群**
## Timeout
(*ECSRenderTaskDefinition*/**Timeout**)
(選用)
指定動作在 CodeCatalyst 結束動作之前可執行的時間，以分鐘為單位 (YAML 編輯器） 或小時和分鐘為單位。最小值為 5 分鐘，最大值如 中所述[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。預設逾時與最大逾時相同。
對應的 UI：組態索引標籤/**逾時 - 選用 **
## Inputs
(*ECSRenderTaskDefinition*/**Inputs**)
(選用)
`Inputs` 區段定義工作流程執行期間 `ECSRenderTaskDefinition`所需的資料。
**注意**
每個**轉譯 Amazon ECS 任務定義**動作只允許一個輸入 （來源或成品）。變數不會計入此總計。
對應的 UI：**輸入**索引標籤
## Sources
(*ECSRenderTaskDefinition*/Inputs/**Sources**)
（如果您的任務定義檔案存放在來源儲存庫中，則為必要項目）
如果您的任務定義檔案存放在來源儲存庫中，請指定該來源儲存庫的標籤。目前，唯一支援的標籤是 `WorkflowSource`。
如果您的任務定義檔案不包含在來源儲存庫中，它必須位於另一個動作所產生的成品中。
如需來源的詳細資訊，請參閱 [將來源儲存庫連線至工作流程](workflows-sources.md)。
對應的 UI：輸入索引標籤/**來源 - 選用**
## Artifacts - input
(*ECSRenderTaskDefinition*/Inputs/**Artifacts**)
（如果您的任務定義檔案存放在先前動作的[輸出成品](workflows-working-artifacts-output.md)中，則為必要）
如果您想要部署的任務定義檔案包含在先前動作產生的成品中，請在此處指定該成品。如果您的任務定義檔案不包含在成品中，它必須位於您的來源儲存庫中。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：組態索引標籤/**成品 - 選用**
## Variables - input
(*ECSRenderTaskDefinition*/Inputs/**Variables**)
(必要)
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：輸入索引標籤/**變數 - 選用**
## Configuration
(*ECSRenderTaskDefinition*/**Configuration**)
(必要)
您可以在此區段定義 動作的組態屬性。
對應的 UI：**組態**索引標籤
## task-definition
(*ECSRenderTaskDefinition*/Configuration/**task-definition**)
(必要)
指定現有任務定義檔案的路徑。如果檔案位於您的來源儲存庫中，路徑會與來源儲存庫根資料夾相對。如果您的檔案位於先前工作流程動作的成品中，則路徑會與成品根資料夾相對。如需任務定義檔案的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[任務定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)。
對應的 UI：組態索引標籤/**任務定義**
## container-definition-name
(*ECSRenderTaskDefinition*/Configuration/**container-definition-name**)
(必要)
指定執行 Docker 映像的容器名稱。您可以在任務定義檔案中的 `containerDefinitions`、 `name` 欄位中找到此名稱。如需詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[名稱](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_name)。
對應的 UI：組態索引標籤/**容器名稱**
## image
(*ECSRenderTaskDefinition*/Configuration/**image**)
(必要)
指定您希望**轉譯 Amazon ECS 任務定義**動作新增至任務定義檔案的 Docker 映像名稱。動作會將此名稱新增至任務定義檔案中的 `containerDefinitions`， `image` 欄位。如果值已存在於 `image` 欄位中，則動作會覆寫該值。您可以在映像名稱中包含變數。
範例：
如果您指定 `MyDockerImage:${WorkflowSource.CommitId}`，動作會`MyDockerImage:commit-id`新增至任務定義檔案，其中 *commit-id* 是工作流程在執行時間產生的遞交 ID。
如果您指定 `my-ecr-repo/image-repo:$(date +%m-%d-%y-%H-%m-%s)`，動作會將 *my-ecr-repo*/image-repo：*date \$1%m-%d-%y-%H-%m-%s* 新增至任務定義檔案，其中 *my-ecr-repo* 是 Amazon Elastic Container Registry (ECR) 的 URI，而 *date \$1%m-%d-%y-%H-%m-%s* 是工作流程在執行時間`month-day-year-hour-minute-second`產生的格式時間戳記。
如需 `image` 欄位的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[映像](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_image)。如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
對應的 UI：組態索引標籤/**映像名稱**
## environment-variables
(*ECSRenderTaskDefinition*/Configuration/**environment-variables**)
(必要)
指定您希望**轉譯 Amazon ECS 任務定義**動作新增至任務定義檔案的環境變數。動作會將變數新增至任務定義檔案中的 `containerDefinitions`， `environment` 欄位。如果 檔案中已存在變數，動作會覆寫現有變數的值，並新增任何新變數。如需 Amazon ECS 環境變數的詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[指定環境變數](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html)。
對應的 UI：組態索引標籤/**環境變數 - 選用**
## Outputs
(*ECSRenderTaskDefinition*/**Outputs**)
(必要)
定義 動作在工作流程執行期間輸出的資料。
對應的 UI：**輸出**索引標籤
## Artifacts
(*ECSRenderTaskDefinition*/Outputs/**Artifacts**)
(必要)
指定 動作產生的成品。您可以在其他動作中參考這些成品做為輸入。
如需成品的詳細資訊，包括範例，請參閱 [在動作之間共用成品和檔案](workflows-working-artifacts.md)。
對應的 UI：輸出索引標籤/**成品**
## Name
(*ECSRenderTaskDefinition*/Outputs/Artifacts/**Name**)
(必要)
指定將包含更新任務定義檔案的成品名稱。預設值為 `MyTaskDefinitionArtifact`。然後，您必須將此成品指定為**部署至 Amazon ECS **動作的輸入。若要了解如何將此成品新增為**部署至 Amazon ECS **動作的輸入，請參閱 [範例：修改 Amazon ECS taskdef](render-ecs-action-example-workflow.md)。
對應的 UI：輸出索引標籤/成品/**名稱**
## Files
(*ECSRenderTaskDefinition*/Outputs/Artifacts/**Files**)
(必要)
指定要包含在成品中的檔案。您必須指定 ，`task-definition-*`以便`task-definition-`包含以 開頭的更新任務定義檔案。
對應的 UI：輸出索引標籤/成品/**檔案**
## Variables
(*ECSRenderTaskDefinition*/Outputs/**Variables**)
(必要)
指定要由轉譯動作設定的變數名稱。轉譯動作會將此變數的值設定為已更新任務定義檔案的名稱 （例如 `task-definition-random-string.json`)。然後，您必須在**部署至 Amazon ECS** 動作**的任務定義** （視覺化編輯器） 或 `task-definition`(yaml 編輯器） 屬性中指定此變數。若要了解如何將此變數新增至**部署至 Amazon ECS **動作，請參閱 [範例：修改 Amazon ECS taskdef](render-ecs-action-example-workflow.md) 。
預設：`task-definition`
對應的 UI：輸出索引標籤/變數/**名稱**欄位
# 在工作流程中使用變數
*變數*是金鑰值對，其中包含您可以在 Amazon CodeCatalyst 工作流程中參考的資訊。工作流程執行時，變數的值部分會取代為實際值。
您可以在工作流程中使用兩種類型的變數：
+ **使用者定義的變數** – 這些是您定義的鍵值對。
+ **預先定義的變數** – 這些是工作流程自動發出的鍵值對。您不需要定義它們。
如需工作流程的相關詳細資訊，請參閱 [使用工作流程建置、測試和部署使用工作流程建置、測試和部署](workflow.md)。
**注意**
CodeCatalyst 也支援 [GitHub 輸出參數](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter)，其行為類似於變數，並且可以在其他動作中參考。如需詳細資訊，請參閱 [匯出 GitHub 輸出參數](integrations-github-action-export.md) 和 [參考 GitHub 輸出參數](integrations-github-action-referencing.md)
**Topics**
+ [使用使用者定義的變數](workflows-using-variables.md)
+ [使用預先定義的變數](workflows-using-predefined-variables.md)
# 使用使用者定義的變數
*使用者定義的變數*是您定義的鍵值對。受管字首清單有兩種類型：
+ **純文字變數**，或只是**變數** – 這些是您在工作流程定義檔案中以純文字定義的鍵值對。
+ **秘密** – 這些是您在 Amazon CodeCatalyst 主控台的個別**秘密**頁面上定義的鍵/值對。*金鑰* （名稱） 是公有標籤，值**包含您要保持私有的資訊。您只能在工作流程定義檔案中指定 金鑰。使用秘密取代工作流程定義檔案中的密碼和其他敏感資訊。
**注意**
為了簡潔起見，本指南使用 *變數*一詞來表示*純文字變數*。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**Topics**
+ [變數的範例](workflows-working-with-variables-ex.md)
+ [定義變數](workflows-working-with-variables-define-input.md)
+ [定義秘密](workflows-working-with-variables-define-secret.md)
+ [匯出變數，讓其他動作可以使用它](workflows-working-with-variables-export-input.md)
+ [在定義變數的動作中參考變數](workflows-working-with-variables-reference-input.md)
+ [透過另一個動作參考變數輸出](workflows-working-with-variables-reference-action.md)
+ [參考秘密](workflows-working-with-variables-reference-secret.md)
# 變數的範例
下列範例示範如何在工作流程定義檔案中定義和參考變數。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**Topics**
+ [範例：使用 Inputs 屬性定義變數](#workflows-working-with-variables-ex-define-inputs)
+ [範例：使用 Steps 屬性定義變數](#workflows-working-with-variables-ex-define-steps)
+ [範例：使用 Outputs 屬性匯出變數](#workflows-working-with-variables-ex-export-outputs)
+ [範例：參考相同動作中定義的變數](#workflows-working-with-variables-ex-refer-current)
+ [範例：參考另一個動作中定義的變數](#workflows-working-with-variables-ex-refer-other)
+ [範例：參考秘密](#workflows-working-with-variables-ex-refer-secret)
## 範例：使用 Inputs 屬性定義變數
下列範例說明如何在 `Inputs`區段中定義兩個變數 `VAR2``VAR1`和 。
```
Actions:
Build:
Identifier: aws/build@v1
Inputs:
Variables:
- Name: VAR1
Value: "My variable 1"
- Name: VAR2
Value: "My variable 2"
```
## 範例：使用 Steps 屬性定義變數
下列範例示範如何在 `Steps`區段中明確定義`DATE`變數。
```
Actions:
Build:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: DATE=$(date +%m-%d-%y)
```
## 範例：使用 Outputs 屬性匯出變數
下列範例說明如何定義兩個變數 `REPOSITORY-URI`和 `TIMESTAMP`，並使用 `Outputs`區段匯出它們。
```
Actions:
Build:
Identifier: aws/build@v1
Inputs:
Variables:
- Name: REPOSITORY-URI
Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
Configuration:
Steps:
- Run: TIMESTAMP=$(date +%m-%d-%y-%H-%m-%s)
Outputs:
Variables:
- REPOSITORY-URI
- TIMESTAMP
```
## 範例：參考相同動作中定義的變數
下列範例示範如何在 中指定`VAR1`變數`MyBuildAction`，然後使用 在相同的動作中參考它`$VAR1`。
```
Actions:
MyBuildAction:
Identifier: aws/build@v1
Inputs:
Variables:
- Name: VAR1
Value: my-value
Configuration:
Steps:
- Run: $VAR1
```
## 範例：參考另一個動作中定義的變數
下列範例說明如何在 中指定`TIMESTAMP`變數`BuildActionA`、使用 `Outputs` 屬性匯出變數，然後使用 `BuildActionB` 在 中參考變數`${BuildActionA.TIMESTAMP}`。
```
Actions:
BuildActionA:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: TIMESTAMP=$(date +%m-%d-%y-%H-%m-%s)
Outputs:
Variables:
- TIMESTAMP
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: docker build -t my-ecr-repo/image-repo:latest .
- Run: docker tag my-ecr-repo/image-repo:${BuildActionA.TIMESTAMP}
# Specifying just '$TIMESTAMP' here will not work
# because TIMESTAMP is not a variable
# in the BuildActionB action.
```
## 範例：參考秘密
下列範例示範如何參考`my-password`秘密。`my-password` 是秘密的金鑰。此秘密的金鑰和對應的密碼值必須在 CodeCatalyst 主控台的**秘密**頁面上指定，才能用於工作流程定義檔案。如需詳細資訊，請參閱[使用秘密遮罩資料](workflows-secrets.md)。
```
Actions:
BuildActionA:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: curl -u LiJuan:${Secrets.my-password} https://example.com
```
# 定義變數
您可以透過兩種方式定義變數：
+ 在工作流程動作的 `Inputs`區段中 – 請參閱[「輸入」區段中的如何定義變數](#workflows-to-define-variable-input)
+ 在工作流程動作的 `Steps`區段中 – 請參閱[「步驟」區段中的如何定義變數](#workflows-to-define-variable-steps)
**注意**
`Steps` 方法僅適用於 CodeCatalyst 建置、測試和 **GitHub 動作**，因為這些是包含`Steps`區段的唯一動作。
如需範例，請參閱 [變數的範例](workflows-working-with-variables-ex.md)。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
------
#### [ Visual ]
**在「輸入」區段中定義變數 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要設定變數的動作。
1. 選擇**輸入**。
1. 在**變數 - 選用**中，選擇**新增變數**，然後執行下列動作：
指定名稱/值對的序列，以定義您要提供給動作的輸入變數。變數名稱僅限於英數字元 (a-z、A-Z、0-9)、連字號 (-) 和底線 (\$1)。不允許空格。您不能使用引號在變數名稱中啟用特殊字元和空格。
如需變數的詳細資訊，包括範例，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**在「輸入」區段中定義變數 (YAML 編輯器）**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在工作流程動作中，新增類似下列的程式碼：
```
action-name:
Inputs:
Variables:
- Name: variable-name
Value: variable-value
```
如需更多範例，請參閱[變數的範例](workflows-working-with-variables-ex.md)。如需詳細資訊，請參閱您動作[工作流程 YAML 定義](workflow-reference.md)的 。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
------
#### [ Visual ]
**在「步驟」區段中定義變數 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要設定變數的動作。
1. 選擇 **Configuration (組態)**。
1. 在 **Shell 命令**或 **GitHub 動作 YAML** 中，以可用者為準，在動作的 中`Steps`明確或隱含地定義變數。
+ 若要明確定義變數，請將其直接包含在 `Steps`區段的 bash 命令中。
+ 若要隱含定義變數，請在動作 `Steps`區段中參考的檔案中指定變數。
如需範例，請參閱 [變數的範例](workflows-working-with-variables-ex.md)。如需詳細資訊，請參閱 [工作流程 YAML 定義](workflow-reference.md) 以取得 動作。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**在「步驟」區段中定義變數 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在工作流程動作中，明確或隱含地在動作的 `Steps`區段中定義變數。
+ 若要明確定義變數，請將其直接包含在 `Steps`區段的 bash 命令中。
+ 若要隱含定義變數，請在動作 `Steps`區段中參考的檔案中指定變數。
如需範例，請參閱 [變數的範例](workflows-working-with-variables-ex.md)。如需詳細資訊，請參閱 [工作流程 YAML 定義](workflow-reference.md) 以取得 動作。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 定義秘密
您可以在 CodeCatalyst 主控台的**秘密**頁面上定義秘密。如需詳細資訊，請參閱[使用秘密遮罩資料](workflows-secrets.md)。
例如，您可以定義如下所示的秘密：
+ 名稱 （索引鍵）： **my-password**
+ 值：**^\$1H3\$1\$1b9**
定義秘密之後，您可以在工作流程定義檔案中指定秘密的金鑰 (**my-password**)。如需如何執行此作業的範例，請參閱 [範例：參考秘密](workflows-working-with-variables-ex.md#workflows-working-with-variables-ex-refer-secret)。
# 匯出變數，讓其他動作可以使用它
使用以下指示從 動作匯出變數，讓您可以在其他動作中參考該變數。
匯出變數之前，請注意下列事項：
+ 如果您只需要在定義變數的動作中參考該變數，則不需要匯出該變數。
+ 並非所有動作都支援匯出變數。若要判斷您的動作是否支援此功能，請執行以下視覺化編輯器說明，並查看動作是否包含**輸出**索引標籤上的**變數**按鈕。如果是，則支援匯出變數。
+ 若要從 GitHub 動作匯出變數，請參閱 [匯出 GitHub 輸出參數](integrations-github-action-export.md)。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**先決條件**
請確定您已定義要匯出的變數。如需詳細資訊，請參閱[定義變數](workflows-working-with-variables-define-input.md)。
------
#### [ Visual ]
**匯出變數 （視覺化編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇**視覺化**。
1. 在工作流程圖表中，選擇您要從中匯出變數的動作。
1. 選擇**輸出**。
1. 在**變數 - 選用**中，選擇**新增變數**，然後執行下列動作：
指定您要動作匯出的變數名稱。此變數必須已在相同動作的 `Inputs`或 `Steps`區段中定義。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
#### [ YAML ]
**匯出變數 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在您要從中匯出變數的動作中，新增類似下列的程式碼：
```
action-name:
Outputs:
Variables:
- Name: variable-name
```
如需更多範例，請參閱[變數的範例](workflows-working-with-variables-ex.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 在定義變數的動作中參考變數
使用下列指示，在定義變數的 動作中參考變數。
**注意**
若要參考 GitHub 動作產生的變數，請參閱 [參考 GitHub 輸出參數](integrations-github-action-referencing.md)。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**先決條件**
請確定您已定義要參考的變數。如需詳細資訊，請參閱[定義變數](workflows-working-with-variables-define-input.md)。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**在定義變數的 動作中參考變數**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在定義您要參考之變數的 CodeCatalyst 動作中，使用以下 bash 語法新增變數：
```
$variable-name
```
例如：
```
MyAction:
Configuration:
Steps:
- Run: $variable-name
```
如需更多範例，請參閱[變數的範例](workflows-working-with-variables-ex.md)。如需詳細資訊，請參閱 中 動作的參考資訊[工作流程 YAML 定義](workflow-reference.md)。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 透過另一個動作參考變數輸出
使用下列指示來參考其他動作輸出的變數。
**注意**
若要參考 GitHub 動作的變數輸出，請參閱 [參考 GitHub 輸出參數](integrations-github-action-referencing.md)。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**先決條件**
請確定您已匯出要參考的變數。如需詳細資訊，請參閱[匯出變數，讓其他動作可以使用它](workflows-working-with-variables-export-input.md)。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**由另一個動作參考變數輸出 (YAML 編輯器）**
1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 CodeCatalyst 動作中，使用下列語法將參考新增至變數：
```
${action-group-name.action-name.variable-name}
```
取代：
+ *action-group-name* 具有動作群組的名稱，其中包含輸出變數的動作。
**注意**
如果沒有動作群組，或者如果變數是由相同動作群組中的動作產生，您可以省略 *action-group-name*。
+ *action-name* 與輸出變數的動作名稱。
+ *variable-name* 與變數的名稱。
例如：
```
MySecondAction:
Configuration:
Steps:
- Run: ${MyFirstAction.TIMESTAMP}
```
如需更多範例，請參閱[變數的範例](workflows-working-with-variables-ex.md)。如需詳細資訊，請參閱您動作[工作流程 YAML 定義](workflow-reference.md)的 。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 參考秘密
如需在工作流程定義檔案中參考秘密的說明，請參閱 [利用私密](workflows-secrets.using.md)。
如需範例，請參閱[範例：參考秘密](workflows-working-with-variables-ex.md#workflows-working-with-variables-ex-refer-secret)。
# 使用預先定義的變數
*預先定義的變數*是工作流程自動發出的鍵/值對，可供您在工作流程動作中使用。
如需變數的詳細資訊，請參閱 [在工作流程中使用變數](workflows-working-with-variables.md)。
**Topics**
+ [參考預先定義變數的範例](workflows-predefined-examples.md)
+ [參考預先定義的變數](workflows-working-with-variables-reference-output-vars.md)
+ [判斷工作流程發出的預先定義變數](workflows-working-with-variables-determine-output-vars.md)
+ [預先定義的變數清單](workflow-ref-action-variables.md)
# 參考預先定義變數的範例
下列範例示範如何在工作流程定義檔案中參考預先定義的變數。
如需預先定義變數的詳細資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
**Topics**
+ [範例：參考「CommitId」預先定義的變數](#workflows-working-with-variables-ex-refer-action)
+ [範例：參考「BranchName」預先定義的變數](#workflows-working-with-variables-ex-branch)
## 範例：參考「CommitId」預先定義的變數
下列範例說明如何在 `MyBuildAction`動作中參考`CommitId`預先定義的變數。`CommitId` 變數由 CodeCatalyst 自動輸出。如需詳細資訊，請參閱[預先定義的變數清單](workflow-ref-action-variables.md)。
雖然範例顯示建置動作中使用的變數，但您可以在任何動作`CommitId`中使用 。
```
MyBuildAction:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Configuration:
Steps:
#Build Docker image and tag it with a commit ID
- Run: docker build -t image-repo/my-docker-image:latest .
- Run: docker tag image-repo/my-docker-image:${WorkflowSource.CommitId}
```
## 範例：參考「BranchName」預先定義的變數
下列範例說明如何在 `CDKDeploy`動作中參考`BranchName`預先定義的變數。`BranchName` 變數由 CodeCatalyst 自動輸出。如需詳細資訊，請參閱[預先定義的變數清單](workflow-ref-action-variables.md)。
雖然範例顯示**AWS CDK 部署**動作中使用的變數，但您可以在任何動作`BranchName`中使用 。
```
CDKDeploy:
Identifier: aws/cdk-deploy@v2
Inputs:
Sources:
- WorkflowSource
Configuration:
StackName: app-stack-${WorkflowSource.BranchName}
```
# 參考預先定義的變數
您可以在 Amazon CodeCatalyst 工作流程中的任何動作中參考預先定義的變數。
使用下列指示來參考工作流程中的預先定義變數。
如需預先定義變數的詳細資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
**先決條件**
決定您要參考的預先定義變數名稱，例如 `CommitId`。如需詳細資訊，請參閱[判斷工作流程發出的預先定義變數](workflows-working-with-variables-determine-output-vars.md)。
------
#### [ Visual ]
*無法使用。選擇 YAML 以檢視 YAML 指示。*
------
#### [ YAML ]
**參考預先定義的變數 (YAML 編輯器）**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 在 CodeCatalyst 動作中，使用下列語法新增預先定義的變數參考：
```
${action-group-name.action-name-or-WorkflowSource.variable-name}
```
取代：
+ *action-group-name* 與動作群組的名稱。
**注意**
如果沒有動作群組，或者如果變數是由相同動作群組中的動作產生，您可以省略 *action-group-name*。
+ *action-name-or-WorkflowSource* 搭配：
輸出變數的動作名稱。
或
`WorkflowSource`，如果變數是 `BranchName`或 `CommitId`變數。
+ *variable-name* 與變數的名稱。
例如：
```
MySecondAction:
Configuration:
Steps:
- Run: echo ${MyFirstECSAction.cluster}
```
另一個範例是：
```
MySecondAction:
Configuration:
Steps:
- Run: echo ${WorkflowSource.CommitId}
```
如需更多範例，請參閱[參考預先定義變數的範例](workflows-predefined-examples.md)。如需詳細資訊，請參閱您動作[工作流程 YAML 定義](workflow-reference.md)的 。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
------
# 判斷工作流程發出的預先定義變數
使用下列程序來判斷工作流程執行時發出的預先定義變數。然後，您可以在相同的工作流程中參考這些變數。
如需預先定義變數的詳細資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
**判斷工作流程發出的預先定義變數**
+ 執行以下任意一項：
+ **執行工作流程一次**。執行完成後，工作流程發出的變數會顯示在執行詳細資訊頁面的**變數**索引標籤上。如需詳細資訊，請參閱[檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
+ **請參閱 [預先定義的變數清單](workflow-ref-action-variables.md)**。此參考會列出每個預先定義變數的變數名稱 （索引鍵） 和值。
**注意**
工作流程變數的總大小上限會列在 中[CodeCatalyst 中工作流程的配額](workflows-quotas.md)。如果總大小超過上限，達到上限之後發生的動作可能會失敗。
# 預先定義的變數清單
請參閱下列各節，以檢視 CodeCatalyst 動作在工作流程執行期間自動產生的預先定義變數。
如需預先定義變數的詳細資訊，請參閱 [使用預先定義的變數](workflows-using-predefined-variables.md)。
**注意**
此清單僅包含 CodeCatalyst 來源和 [CodeCatalyst 動作](workflows-actions.md#workflows-actions-types)發出的預先定義變數。如果您使用其他類型的動作，例如 GitHub Actions 或 CodeCatalyst 實驗室動作，請改為參閱 [判斷工作流程發出的預先定義變數](workflows-working-with-variables-determine-output-vars.md)。
**清單**
**注意**
並非所有 CodeCatalyst 動作都會產生預先定義的變數。如果動作不在清單中，則不會產生變數。
+ ['BranchName' 和 'CommitId' 變數](workflows-sources-variables.md)
+ [「部署 CloudFormation 堆疊」變數](deploy-action-cfn-variables.md)
+ [「部署到 Amazon ECS」變數](deploy-action-ecs-variables.md)
+ [「部署到 Kubernetes 叢集」變數](deploy-action-eks-variables.md)
+ [「AWS CDK 部署」變數](cdk-dep-action-variables.md)
+ ['AWS CDK bootstrap' 變數](cdk-boot-action-variables.md)
+ [「AWS Lambda 叫用」變數](lam-invoke-action-variables.md)
+ [「轉譯 Amazon ECS 任務定義」變數](render-ecs-action-variables.md)
# 使用秘密遮罩資料
有時您可能需要在工作流程中使用敏感資料，例如身分驗證憑證。應該避免將這些值以純文字形式存放在儲存庫中的任何位置，因為任何有權存取包含秘密的儲存庫的人都可以看到它們。同樣地，這些值不應直接用於任何工作流程定義，因為它們將作為您儲存庫中的檔案顯示。使用 CodeCatalyst，您可以將秘密新增至專案，然後在工作流程定義檔案中參考秘密，以保護這些值。請注意，每個動作最多可以有五個秘密。
**注意**
秘密只能用來取代工作流程定義檔案中的密碼和敏感資訊。
**Topics**
+ [建立秘密](workflows-secrets.creating.md)
+ [編輯秘密](workflows-secrets.editing.md)
+ [利用私密](workflows-secrets.using.md)
+ [刪除秘密](workflows-secrets.deleting.md)
# 建立秘密
使用下列程序來建立秘密。秘密包含您要從檢視中隱藏的敏感資訊。
**注意**
動作可以看到秘密，而且寫入檔案時不會遮罩秘密。
**若要建立機密**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**秘密**。
1. 選擇**建立機密**。
1. 輸入下列資訊：
**名稱**
輸入秘密的名稱。
**Value**
輸入秘密的值。這是您要從檢視中隱藏的敏感資訊。根據預設，不會顯示 值。若要顯示值，請選擇**顯示值**。
**Description**
（選用） 輸入秘密的描述。
1. 選擇**建立**。
# 編輯秘密
使用下列程序來編輯秘密。
**編輯秘密**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**秘密**。
1. 在秘密清單中，選擇您要編輯的秘密。
1. 選擇**編輯**。
1. 編輯下列屬性：
**Value**
輸入秘密的值。這是您要從檢視中隱藏的值。根據預設，不會顯示 值。
**Description**
（選用） 輸入秘密的描述。
1. 選擇**儲存**。
# 利用私密
若要在工作流程動作中使用秘密，您必須取得秘密的參考識別碼，並在工作流程動作中使用該識別碼。
**Topics**
+ [取得秘密的識別符](#workflows-using-secrets.get-identifier)
+ [在工作流程中參考秘密](#workflows-using-secrets.using-identifier)
## 取得秘密的識別符
使用下列程序取得秘密的參考識別碼。您會將此識別符新增至工作流程。
**取得秘密的參考識別碼**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**秘密**。
1. 在秘密清單中，尋找您要使用的秘密。
1. 在**參考 ID** 欄中，複製秘密的識別符。以下是**參考 ID** 的語法：
```
${Secrets.}
```
## 在工作流程中參考秘密
使用下列程序來參考工作流程中的秘密。
**參考秘密**
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 修改 YAML 以使用秘密的識別符。例如，若要搭配 `curl`命令使用儲存為秘密的使用者名稱和密碼，您可以使用類似以下的`Run`命令：
```
- Run: curl -u : https://example.com
```
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
# 刪除秘密
使用下列程序刪除秘密和秘密參考識別符。
**注意**
刪除秘密之前，建議您從所有工作流程動作中移除秘密的參考識別碼。如果您刪除秘密但不刪除參考識別符，則下次執行動作時將會失敗。
**從工作流程中刪除秘密的參考識別碼**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
1. 選擇**編輯**。
1. 選擇 **YAML**。
1. 搜尋工作流程以取得下列字串：
```
${Secrets.
```
這會尋找所有秘密的所有參考識別碼。
1. 刪除所選秘密的參考識別符，或將其取代為純文字值。
1. （選用） 選擇**驗證**以在遞交之前驗證工作流程的 YAML 程式碼。
1. 選擇**遞交**，輸入遞交訊息，然後再次選擇**遞交**。
**刪除秘密**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**秘密**。
1. 在秘密清單中，選擇您要刪除的秘密。
1. 選擇 **刪除**。
1. 輸入 **delete** 以確認刪除。
1. 選擇**刪除**。
# 檢視工作流程的狀態
您可能想要檢視工作流程的狀態，以查看是否有任何需要解決的工作流程組態問題，或疑難排解無法啟動的執行。CodeCatalyst 會在您每次建立或更新工作流程的基礎[工作流程定義檔案](workflows-concepts.md#workflows-concepts-workflows-def)時評估工作流程狀態。
**注意**
您也可以檢視工作流程的*執行*狀態，這與工作流程狀態不同。如需詳細資訊，請參閱[檢視工作流程執行狀態和詳細資訊](workflows-view-run.md)。
如需可能的工作流程狀態清單，請參閱 [CodeCatalyst 中的工作流程狀態](workflows-workflow-status.md)。
**檢視工作流程的狀態**
1. 在 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/) 開啟 CodeCatalyst 主控台。
1. 選擇您的專案。
1. 在導覽窗格中，選擇 **CI/CD**，然後選擇**工作流程**。
1. 選擇工作流程的名稱。您可以依定義工作流程的來源儲存庫或分支名稱進行篩選，或依工作流程名稱或狀態進行篩選。
狀態會與清單中的工作流程一起顯示。
1. （選用） 選擇工作流程的名稱，然後尋找**工作流程定義**欄位。它會顯示工作流程狀態。
# CodeCatalyst 中工作流程的配額
下表說明 Amazon CodeCatalyst 中工作流程的配額和限制。
如需 Amazon CodeCatalyst 中配額的詳細資訊，請參閱 [CodeCatalyst 的配額](quotas.md)。
| | |
| --- |--- |
| 每個空間的工作流程數目上限 | 800 |
| 工作流程定義檔案大小上限 | 256 KB |
| 在單一來源事件中處理的工作流程檔案數目上限 | 50 |
| 在單一來源事件中處理的檔案數量上限 | 4,000 |
| 每個空間的作用中機群數量上限 | 10 |
| 每個機群的作用中運算執行個體數量上限 | 20 |
| 每個動作的輸入成品數量上限 | 10 |
| 每個動作的輸出成品數量上限 | 10 |
| 單一動作輸出變數的總大小上限 | 120 KB |
| 輸出變數值的長度上限 | 500 個字元或更多，取決於發出值的動作。 如果值超過動作的限制，則可能會截斷這些值。 |
| 保留工作流程執行期間產生的成品的天數上限 | 30 |
| 每個動作的報告數量上限 | 50 |
| 每個測試報告的測試案例數量上限 | 20,000 |
| 每個程式碼涵蓋範圍報告的檔案數目上限 | 20,000 |
| 每個報告的軟體合成分析問題清單數目上限 | 20,000 |
| 每個靜態分析報告的檔案數目上限 | 20,000 |
| 每個空間的並行工作流程執行數目上限 | 100 |
| 每個工作流程的動作數目上限 | 50 |
| 每個工作流程同時執行的動作數目上限 | 50 |
| 每個空間同時執行的動作數目上限 | 200 |
| 動作可執行的時間上限 | 對於建置和測試動作，逾時為 8 小時。 對於所有其他動作，逾時為 1 小時。 |
| 每個空間與 AWS 帳戶 相關聯的環境數目上限 | 5,000 |
| 每個動作的秘密數目上限 | 5 |
| 每個空間的秘密數目上限 | 500,000 |
# 工作流程執行狀態
工作流程執行可以處於下列其中一種狀態：
+ **成功** – 工作流程執行已成功處理。
+ **失敗** – 工作流程執行中的一或多個動作失敗。
+ **進行中** – 目前正在處理工作流程執行。
+ **已停止** – 某人在工作流程進行時停止工作流程執行。
+ **停止** – 目前正在停止工作流程執行。
+ **已取消** – CodeCatalyst 已取消工作流程執行，因為相關聯的工作流程已在執行進行時遭到刪除或更新。
+ **取代** – 只有在您已設定[取代的執行模式](workflows-configure-runs.md#workflows-configure-runs-superseded)時才會發生。CodeCatalyst 已取消工作流程執行，因為稍後的工作流程執行會取代它。
# CodeCatalyst 中的工作流程狀態
工作流程可以有下列其中一種狀態：
+ **有效** – 工作流程可執行，且可透過[觸發程序](workflows-add-trigger.md#workflows-add-trigger.title)啟動。
若要將工作流程標記為有效，下列兩個條件都必須為 true：
+ 工作流程定義檔案必須是有效的。
+ 工作流程必須沒有觸發條件、沒有推送觸發條件，或使用目前分支上檔案執行的推送觸發條件。如需詳細資訊，請參閱[觸發和分支的使用準則](workflows-add-trigger-considerations.md)。
+ **無效** – 工作流程的定義檔案無效。工作流程無法手動執行，也無法透過觸發程序自動執行。在 CodeCatalyst 主控台中，工作流程**定義無效的工作流程會顯示 *n* 個錯誤訊息** （或類似訊息）。
若要將工作流程標示為無效，下列條件必須為 true：
+ 工作流程定義檔案必須設定錯誤。
若要修正設定錯誤的工作流程定義檔案，請參閱 [如何修正「工作流程定義有 *n* 個錯誤」錯誤？](troubleshooting-workflows.md#troubleshooting-workflows-asterisks)。
+ **非作用中** – 工作流程定義有效，但無法手動執行，或透過觸發自動執行。
若要將工作流程標記為非作用中，下列兩個條件都必須為 true：
+ 工作流程定義檔案必須是有效的。
+ 工作流程定義檔案必須包含推送觸發條件，指定與工作流程定義檔案目前所在的分支不同的分支。如需詳細資訊，請參閱[觸發和分支的使用準則](workflows-add-trigger-considerations.md)。
若要將工作流程從**非作用中**切換到**作用中**，請參閱 [如何修正「工作流程非作用中」訊息？](troubleshooting-workflows.md#troubleshooting-workflows-inactive)。
**注意**
如果有許多工作流程處於**非作用中**狀態，您可以從檢視篩選它們。若要篩選掉非作用中的工作流程，請選擇工作流程頁面頂端的**篩選****工作流程**欄位，選擇**狀態**，選擇**狀態！= 不相等**，然後選擇**非作用中**。
**注意**
如果工作流程指定您稍後移除的資源 （例如套件儲存庫），CodeCatalyst 不會偵測到此變更，並繼續將工作流程標記為有效。工作流程執行時會發現這些類型的問題。
# 工作流程 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：*無*