亚马逊 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 .
```
| 行 | 说明 |
| --- | --- |
| 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 .
| 告诉构建操作构建名为 `MyApp` 的 Docker 映像并使用 `latest` 标记。 |
有关工作流定义文件中所有可用属性的完整列表，请参阅[工作流 YAML 定义](workflow-reference.md)。
## 使用 CodeCatalyst 控制台的视觉编辑器和 YAML 编辑器
要创建和编辑工作流程定义文件，您可以使用首选编辑器，但我们建议使用 CodeCatalyst 控制台的可视化编辑器或 YAML 编辑器。这些编辑器提供有用的文件验证功能，有助于确保 YAML 属性名称、值、嵌套、间距、大小写等正确无误。
下图显示了可视化编辑器中的工作流。可视化编辑器为您提供了一个完整的用户界面，您可以通过该界面创建和配置工作流定义文件。可视化编辑器包括一个显示工作流主要组件的工作流程图（1）和一个配置区域（2）。
![\[工作流可视化编辑器\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/workflow-visual-editor.png)
您也可以使用 YAML 编辑器，如下图所示。使用 YAML 编辑器粘贴大型代码块（例如教程中的代码块），或添加可视化编辑器不提供的高级属性。
![\[工作流 YAML 编辑器\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/workflow-yaml-editor.png)
您可以从可视化编辑器切换到 YAML 编辑器，查看您的配置对底层 YAML 代码的影响。
## 发现工作流
您可以在**工作流**摘要页面查看您的工作流，以及您在同一项目中设置的其它工作流。
下图显示了**工作流**摘要页面。它包含两个工作流程：**BuildToProd**和**UnitTests**。您可以看到两者都运行过几次。您可以选择**最近的运行**以快速查看运行历史记录，也可以选择工作流名称以查看工作流的 YAML 代码和其它详细信息。
![\[工作流日志\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/workflow-list.png)
## 查看工作流运行详细信息
您可以通过在**工作流**摘要页面中选择运行来查看工作流运行的详细信息。
下图显示了名为 **Run-cc11d** 的工作流运行的详细信息，该工作流是在提交到源时自动启动的。工作流程图表明某项操作已失败（1）。您可以导航到日志（2）以查看详细的日志消息并解决问题。有关工作流运行的更多信息，请参阅[运行工作流](workflows-working-runs.md)。
![\[工作流日志\]](http://docs.aws.amazon.com/zh_cn/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)。
## 计算
*计算*是指为运行工作流操作而管理和维护的计算引擎（CPU、内存和操作系统）。 CodeCatalyst
有关计算的更多信息，请参阅[配置计算和运行时映像](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)。
## Reports
*报告*包含有关工作流运行期间所执行测试的详细信息。您可以创建报告，例如测试报告、代码覆盖率报告、软件组成分析报告和静态分析报告。您可以使用测试报告帮助解决在工作流运行期间发生的问题。如果您有来自多个工作流的许多报告，则可以使用报告来查看趋势和故障率，以帮助您优化应用程序和部署配置。
有关报告的更多信息，请参阅[质量报告类型](test-workflow-actions.md#test-reporting)。
## 运行
*运行*是一个工作流的单次迭代。在运行期间， CodeCatalyst执行工作流配置文件中定义的操作并输出关联的日志、构件和变量。
有关运行的更多信息，请参阅[运行工作流](workflows-working-runs.md)。
## 来源
*源*也称为*输入源*，是一个源存储库，[工作流操作](workflows-actions.md)连接到该存储库以获取执行操作所需的文件。例如，工作流操作可能连接到源存储库来获取应用程序源文件，以便构建应用程序。
有关来源的更多信息，请参阅[将源存储库连接到工作流](workflows-sources.md)。
## 变量
*变量*是一个键值对，其中包含您可以在 Ama CodeCatalyst zon 工作流程中引用的信息。工作流运行时，变量的值部分将替换为实际值。
有关变量的更多信息，请参阅[在工作流中使用变量](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. 选择**提交**。
1. 在**工作流文件名**中，输入工作流配置文件的名称，例如 **my-first-workflow**。
1. 在**提交消息**中，输入消息来标识您的提交，例如 **create my-first-workflow.yaml**。
1. 在**存储库**中，选择要在其中保存工作流的存储库（`codecatalyst-repository`）。
1. 在**分支名称**中，选择要将工作流保存到的分支（`main`）。
1. 选择**提交**。
您的新工作流将显示在工作流列表中。它可能需要一点时间才能显示。
由于工作流与提交保存在一起，并且工作流配置了代码推送触发器，因此保存工作流会自动启动工作流运行。
## 步骤 3：查看运行结果
在此步骤中，您将导航到从您的提交启动的运行，并查看结果。
**查看运行结果**
1. 选择工作流的名称，例如 `Workflow_fe47`。
显示源存储库标签 (**WorkflowSource**) 和生成操作（例如 **build\$1F** 0）的工作流程图。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 选择**操作**。
1. 在**操作**中，选择**构建**。
1. 在**输入**和**配置**选项卡中，根据需要填写字段。有关每个字段的描述，请参阅[构建和测试操作 YAML](build-action-ref.md)。本参考提供了有关在 YAML 编辑器和可视化编辑器中显示的每个字段（以及对应的 YAML 属性值）的详细信息。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器添加构建操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 选择**操作**。
1. 在**操作**中，选择**构建**。
1. 根据需求修改 YAML 代码中的属性。[构建和测试操作 YAML](build-action-ref.md)中提供了每个可用属性的解释。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
## 构建操作定义
构建操作定义为工作流定义文件中的一组 YAML 属性。有关这些属性的信息，请参阅[工作流 YAML 定义](workflow-reference.md)中的[构建和测试操作 YAML](build-action-ref.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 [工作流程](workflows-concepts.md#workflows-concepts-workflows)将项目上传到 Amazon S3 存储桶。当工作流启动时，这些操作将按顺序运行。第一个构建操作生成两个文件（`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 角色
在此步骤中，您将创建一个 AWS IAM 角色，稍后将该角色分配给工作流程中的构建操作。此角色授予 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. 选择**创建策略**。
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. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在主窗格中，选择**创建存储桶**。
1. 对于**存储桶名称**，输入：
```
codecatalyst-artifact-bucket
```
1. 对于 **AWS 区域**，选择一个区域。本教程假设您选择了**美国西部（俄勒冈州）us-west-2**。有关 Amazon S3 支持的区域的信息，请参阅《AWS 一般参考》**中的 [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html)。
1. 在页面底部选择**创建存储桶**。
1. 复制您刚刚创建的存储桶的名称，例如：
```
codecatalyst-artifact-bucket
```
现在，您已经在美国西部（俄勒冈州）us-west-2 区域中创建了一个名为 **codecatalyst-artifact-bucket** 的存储桶。
## 步骤 3：创建源存储库
在此步骤中，您将在中创建源存储库 CodeCatalyst。此存储库用于存储本教程的工作流定义文件。
有关源存储库的更多信息，请参阅[创建源存储库](source-repositories-create.md)。
**创建源存储库**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 命令 `aws s3 sync`，将 `codecatalystArtifact` 和源存储库中的文件上传到您的 Amazon S3 存储桶。已在 AWS CLI CodeCatalyst计算平台上预安装和预先配置，因此您无需安装或配置它。
有关 CodeCatalyst 计算平台上预打包软件的更多信息，请参阅[指定运行时环境映像](build-images.md)。有关`aws s3 sync`命令 AWS CLI的更多信息，请参阅《*AWS CLI 命令参考*》中的 [sync](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. 选择**提交**。
1. 在**提交工作流**对话框中，输入以下内容：
1. 对于**工作流文件名**，保留默认值 `codecatalyst-artifact-workflow`。
1. 对于**提交消息**，输入：
```
add initial workflow file
```
1. 对于**存储库**，选择 **codecatalyst-artifact-source-repository**。
1. 对于**分支名称**，选择**主**。
1. 选择**提交**。
现在，您已创建工作流。由于在工作流顶部定义了触发器，因此工作流运行会自动启动。具体而言，当您将 `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/`、`.git/` 和 `README.md` 文件，因为它们位于您的源存储库中。
## 清理
清理干净 CodeCatalyst AWS ，避免为这些服务收费。
**要清理干净 CodeCatalyst**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 删除 `codecatalyst-artifact-source-repository` 源存储库。
1. 删除 `codecatalyst-artifact-workflow` 工作流。
**要清理干净 AWS**
1. 在 Amazon S3 中进行清理，如下所示：
1. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/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` 用于测试操作。
对应的用户界面：工作流程图/操作名称/标签 *aws/build@v1\$1aws/managed-test@v1*
## DependsOn
(*action-name*/**DependsOn**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](workflows-depends-on.md)。
对应的 UI：“输入”选项卡/**依赖于 – 可选**
## Compute
(*action-name*/**Compute**)
（可选）
用于运行工作流操作的计算引擎。您可以在工作流级别或操作级别指定计算，但不能同时在这两个级别指定计算。在工作流级别指定计算时，计算配置将应用于工作流中定义的所有操作。在工作流级别，您还可以在同一个实例上运行多个操作。有关更多信息，请参阅[跨操作共享计算](compute-sharing.md)。
对应的 UI：*无*
## Type
（*action-name*/Compute/**类型**）
（如果包含 [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 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的用户界面：配置在tab/Environment/What里面*my-environment*吗？ **/三点菜单/ 切换角色**
## Name
(*action-name*/Environment/Connections/**Name**)
（如果包含 [Connections](#build.environment.connections)，则为必需）
指定账户连接的名称。
对应的用户界面：配置在tab/Environment/What里面*my-environment*吗？ **/三点菜单/ 切换角色**
## Role
(*action-name*/Environment/Connections/**Role**)
（如果包含 [Connections](#build.environment.connections)，则为必需）
指定 IAM 角色的名称，该操作使用此角色来访问 Amazon S3 和 Amazon ECR 等 AWS 服务并在其中进行处理。确保将此角色添加到空间中的 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` 角色具有完全访问权限可能会带来安全风险。我们建议您仅在教程和安全要求较低的场景中使用此角色。
**警告**
仅将权限授予构建和测试操作所需的那些角色。使用具有更广泛权限的角色可能会带来安全风险。
对应的用户界面：配置在tab/Environment/What里面*my-environment*吗？ **/三点菜单/ 切换角色**
## Caching
(*action-name*/**Caching**)
（可选）
一个部分，可在其中指定缓存来保存磁盘上的文件，并在后续的工作流运行中从该缓存中恢复这些文件。
有关文件缓存的更多信息，请参阅[在工作流运行之间缓存文件](workflows-caching.md)。
对应的 UI：“配置”选项卡/**文件缓存 – 可选**
## FileCaching
(*action-name*/Caching/**FileCaching**)
（可选）
一个部分，用于指定缓存序列的配置。
**相应的 UI：配置 tab/File 缓存-可选/添加缓存**
## key-name-1
(*action-name*/Caching/FileCaching/***key-name-1***)
（可选）
指定主缓存属性的名称。缓存属性名称在您的工作流内必须是唯一的。每个操作在 `FileCaching` 中最多可以有五个条目。
**相应的 UI：配置 tab/File 缓存-可选/添加缓存/密钥**
## Path
(*action-name*/Caching/FileCaching/*key-name-1*/**Path**)
（可选）
为您的缓存指定关联路径。
**相应的 UI：配置 tab/File 缓存-可选/添加缓存/路径**
## RestoreKeys
(*action-name*/Caching/FileCaching/*key-name-1*/**RestoreKeys**)
（可选）
指定在找不到主缓存属性时用作回退手段的恢复键。恢复键名称在您的工作流内必须是唯一的。每个缓存在 `RestoreKeys` 中最多可以有五个条目。
**相应的 UI：配置 tab/File 缓存-可选/添加缓存/还原密钥-可选**
## 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**)
（可选）
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（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)。
对应的用户界面：输出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`。
+ 要指定所有文件，请使用 `"**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `directory` 的目录中的所有文件和目录，请使用 `"directory/**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `directory` 的目录中的所有文件，而非其任意子目录，请使用 `"directory/*"`。
**注意**
如果您的文件路径包含一个或多个星号（`*`）或其他特殊字符，请用双引号（`""`）将路径括起来。有关特殊字符的更多信息，请参阅[语法准则和惯例](workflow-reference.md#workflow.terms.syntax.conv)。
有关构件的更多信息（包括示例），请参阅[在操作之间共享构件和文件](workflows-working-artifacts.md)。
**注意**
您可能需要在文件路径中添加前缀，以指明要在哪个构件或源中查找它。有关更多信息，请参阅[引用源存储库文件](workflows-sources-reference-files.md)和[在构件中引用文件](workflows-working-artifacts-refer-files.md)。
对应的用户界面：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)。
**对应的用户界面：输出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自动发现两个测试报告`TestSuiteTwo.xml`，`TestSuiteOne.xml`则关联 CodeCatalyst 的报告将命名为 `AutoDiscoveredTestSuiteOne` and。`AutoDiscoveredTestSuiteTwo`
对应的 UI：“输出”选项卡/报告/**前缀名称**
## IncludePaths
(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)
（如果包含并启用 [AutoDiscoverReports](#build.outputs.autodiscover)，或者包含 [Reports](#test.configuration.reports)，则为必需）
指定搜索原始报告时 CodeCatalyst 包含的文件和文件路径。例如，如果您指定`"/test/report/*"`，则会在操作使用的整个[构建映像](build-images.md)中 CodeCatalyst 搜索该`/test/report/*`目录。当它找到该目录时， CodeCatalyst 然后在该目录中查找报告。
**注意**
如果您的文件路径包含一个或多个星号（`*`）或其他特殊字符，请用双引号（`""`）将路径括起来。有关特殊字符的更多信息，请参阅[语法准则和惯例](workflow-reference.md#workflow.terms.syntax.conv)。
如果省略此属性，则默认值为 `"**/*"`，这意味着搜索范围包括所有路径的所有文件。
**注意**
对于手动配置的报告，`IncludePaths` 必须是与单个文件匹配的 glob 模式。
对应的 UI：
+ 输出tab/Reports/Auto-discover reports/Include/exclude路径/ **包含**路径
+ **输出tab/Reports/Manually配置报告//包含/排除路*report-name-1*径/包含路径**
## ExcludePaths
(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)
Or
(*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-discover reports/Include/exclude路径/ **排除**路径
+ **输出tab/Reports/Manually配置报告 *report-name-1* //包含/排除路径/排除路径**
## SuccessCriteria
(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)
Or
(*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**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)
（可选）
指定测试报告中必须通过测试的百分比，关联 CodeCatalyst的报告才会被标记为通过。有效值包括十进制数字。例如：`50`、`60.5`。通过率标准仅适用于测试报告。有关测试报告的更多信息，请参阅[测试报告](test-workflow-actions.md#test-reports)。
**对应的用户界面：输出tab/Reports/Success标准/通过率**
## LineCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**LineCoverage**)
（可选）
指定代码覆盖率报告中必须覆盖的行数百分比，关联 CodeCatalyst 的报告才会被标记为通过。有效值包括十进制数字。例如：`50`、`60.5`。行覆盖率标准仅适用于代码覆盖率报告。有关代码覆盖率报告的更多信息，请参阅[代码覆盖率报告](test-workflow-actions.md#test-code-coverage-reports)。
**对应的用户界面：输出tab/Reports/Success标准/线路覆盖率**
## BranchCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)
Or
(*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**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)
（可选）
指定 SCA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大漏洞数量和严重性。要指定漏洞，您必须指定：
+ 要计入的漏洞的最低严重性。有效值（按严重程度从高到低）为 `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**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisBug**)
（可选）
指定 SA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大错误数量和严重性。要指定错误，您必须指定：
+ 要计入的错误的最低严重性。有效值（按严重程度从高到低）为 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW` 和 `INFORMATIONAL`。
例如，如果您选择 `HIGH`，则将计算 `HIGH` 和 `CRITICAL` 错误的总数。
+ 您希望允许的具有指定严重性的错误的最大数量。超过此数字会导致 CodeCatalyst 报告被标记为失败。有效值为整数。
错误标准仅适用于 PyLint 和 ESLint SA 报告。有关 SA 报告的更多信息，请参阅[静态分析报告](test-workflow-actions.md#test-static-analysis-reports)。
要指定最低严重性，请使用 `Severity` 属性。要指定最大漏洞数，请使用 `Number` 属性。
**对应的用户界面：输出tab/Reports/Success标准/错误**
## StaticAnalysisSecurity
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisSecurity**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisSecurity**)
（可选）
指定 SA 报告中允许将关联 CodeCatalyst 报告标记为已通过的安全漏洞的最大数量和严重性。要指定安全漏洞，您必须指定：
+ 要计入的安全漏洞的最低严重性。有效值（按严重程度从高到低）为 `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**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisQuality**)
（可选）
指定 SA 报告中允许将相关 CodeCatalyst 报告标记为已通过的最大质量问题数量和严重性。要指定质量问题，您必须指定：
+ 要计入的质量问题的最低严重性。有效值（按严重程度从高到低）为 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW` 和 `INFORMATIONAL`。
例如，如果您选择 `HIGH`，则将计算 `HIGH` 和 `CRITICAL` 质量问题的总数。
+ 您希望允许的具有指定严重性的质量问题的最大数量。超过此数字会导致 CodeCatalyst 报告被标记为失败。有效值为整数。
质量问题标准仅适用于 PyLint 和 ESLint SA 报告。有关 SA 报告的更多信息，请参阅[静态分析报告](test-workflow-actions.md#test-static-analysis-reports)。
要指定最低严重性，请使用 `Severity` 属性。要指定最大漏洞数，请使用 `Number` 属性。
**相应的用户界面：输出tab/Reports/Success标准/质量问题**
## StaticAnalysisFinding
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisFinding**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisFinding**)
（可选）
指定 SA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大结果数量和严重性。要指定调查发现，您必须指定：
+ 要计入的调查发现的最低严重性。有效值（按严重程度从高到低）为 `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/**报告名称 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 编辑器）。
+ 对于由 s [implecov](https://github.com/simplecov-ruby/simplecov) 生成的 SimpleCov JSON，而不是 s [implecov-json](https://github.com/vicentllongo/simplecov-json)，请指定 S **implecov（可视化编辑器）或**（YAML 编辑器）。`SIMPLECOV`
+ 对于软件组成分析（SCA）报告：
+ 对于 SARIF，请指定 **SARIF**（可视化编辑器）或 `SARIFSCA`（YAML 编辑器）。
对应的用户界面：输出tab/Reports/Manually configure reports/Add/configure报告*report-name-1*//**报告类型**和**报告格式**
## Configuration
(*action-name*/**Configuration**)
（必需）可在其中定义操作的配置属性的部分。
对应的 UI：**配置**选项卡
## Container
(*action-name*/Configuration/**Container**)
（可选）
指定操作用于完成其处理的 Docker 映像或*容器*。您可以指定随附的[活动图像](build-images.md#build-curated-images)之一 CodeCatalyst，也可以使用自己的图像。如果您选择使用自己的映像，则该映像可以位于 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)。
**对应的用户界面：配置tab/Packages/Add配置/ npm**
## PackageRegistries
(*action-name*/Configuration/Packages/NpmConfiguration/**PackageRegistries**)
（如果包含 [Packages](#build.configuration.packages)，则为必需）
一个部分，可在其中定义一系列程序包存储库的配置属性。
对应的 UI：配置tab/Packages/Add configuration/npm/**添加软件包存储库**
## PackagesRepository
(*action-name*/Configuration/Packages/NpmConfiguration/PackageRegistries/**PackagesRepository**)
（如果包含 [Packages](#build.configuration.packages)，则为必需）
指定您希望该操作使用的 CodeCatalyst *软件包存储库*的名称。
如果您指定多个默认存储库，则优先使用最后一个存储库。
有关程序包存储库的更多信息，请参阅[程序包存储库](packages-concepts.md#packages-concepts-repository)。
**相应的 UI：配置tab/Packages/Add configuration/npm/Add包存储库/ Package 存储库**
## 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/Add configuration/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 可以创建包含测试结果的报告。
您可以使用测试报告来帮助解决测试问题。如果您有来自多个构建的许多测试报告，您可以使用测试报告查看失败率，以帮助您优化构建。
您可以使用以下测试报告文件格式：
+ Cucumber 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（由 s [implecov 生成，而不是 simplecov](https://github.com/simplecov-ruby/simplecov)-json，[.js](https://github.com/vicentllongo/simplecov-json) on）
+ 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`、`MEDIUM`、`LOW` 和 `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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 选择**操作**。
1. 在**操作**中，选择**测试**。
1. 在**输入**和**配置**选项卡中，根据需要填写字段。有关每个字段的描述，请参阅[构建和测试操作 YAML](build-action-ref.md)。本参考提供了有关在 YAML 编辑器和可视化编辑器中显示的每个字段（以及对应的 YAML 属性值）的详细信息。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器添加构建操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 选择**操作**。
1. 在**操作**中，选择**测试**。
1. 根据需求修改 YAML 代码中的属性。[构建和测试操作 YAML](build-action-ref.md)中提供了每个可用属性的解释。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
## 测试操作定义
测试操作被定义为工作流定义文件中的一组 YAML 属性。有关这些属性的信息，请参阅[工作流 YAML 定义](workflow-reference.md)中的[构建和测试操作 YAML](build-action-ref.md)。
# 查看测试操作的结果
按照以下说明查看测试操作的结果，包括生成的日志、报告和变量。
**查看测试操作的结果**
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 在工作流程图中，选择测试操作的名称，例如**测试**。
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 或更高版本），然后使用 Shell 命令 `- Run: npm install -g @aws/universal-test-runner` 通过 `npm` 安装 `universal-test-runner`。有关通过 Shell 命令在容器中安装 Node.js 的更多信息，请参阅 [Installing and Updating 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 ]
**要 universal-test-runner在 YAML 编辑器中使用**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 选择**输出**选项卡。
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）**
指定 SCA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大漏洞数量和严重性。要指定漏洞，您必须指定：
+ 要计入的漏洞的最低严重性。有效值（按严重程度从高到低）为 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW` 和 `INFORMATIONAL`。
例如，如果您选择 `HIGH`，则将计算 `HIGH` 和 `CRITICAL` 漏洞的总数。
+ 您希望允许的具有指定严重性的漏洞的最大数量。超过此数字会导致 CodeCatalyst 报告被标记为失败。有效值为整数。
漏洞标准仅适用于 SCA 报告。有关 SCA 报告的更多信息，请参阅[软件组成分析报告](test-workflow-actions.md#test-sca-reports)。
**错误**
指定 SA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大错误数量和严重性。要指定错误，您必须指定：
+ 要计入的错误的最低严重性。有效值（按严重程度从高到低）为 `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)。
**质量问题**
指定 SA 报告中允许将相关 CodeCatalyst 报告标记为已通过的最大质量问题数量和严重性。要指定质量问题，您必须指定：
+ 要计入的质量问题的最低严重性。有效值（按严重程度从高到低）为 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW` 和 `INFORMATIONAL`。
例如，如果您选择 `HIGH`，则将计算 `HIGH` 和 `CRITICAL` 质量问题的总数。
+ 您希望允许的具有指定严重性的质量问题的最大数量。超过此数字会导致 CodeCatalyst 报告被标记为失败。有效值为整数。
质量问题标准仅适用于 PyLint 和 ESLint SA 报告。有关 SA 报告的更多信息，请参阅[静态分析报告](test-workflow-actions.md#test-static-analysis-reports)。
1. 选择**提交**。
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. 选择**提交**。
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)。
## 包含/排除路径
查看操作结果时，您可以调整 CodeCatalyst 通过配置`IncludePaths`和生成的报告列表`ExcludePaths`。
+ 用于`IncludePaths`指定搜索报告时 CodeCatalyst 要包含的文件和文件路径。例如，如果您指定`"/test/report/*"`，则会在操作使用的整个构建映像中 CodeCatalyst 搜索该`/test/report/`目录。当它找到该目录时， CodeCatalyst 然后在该目录中查找报告。
**注意**
对于手动配置的报告，`IncludePaths` 必须是与单个文件匹配的 glob 模式。
+ 用于`ExcludePaths`指定搜索报告时 CodeCatalyst 要排除的文件和文件路径。例如，如果您指定`"/test/reports/**/*"`，则 CodeCatalyst不会在`/test/reports/`目录中搜索文件。要忽略某个目录中的所有文件，请使用 `**/*` glob 模式。
以下是可能的 glob 模式示例。
| 模式 | 说明 |
| --- | --- |
| `*.*` | 匹配当前目录中所有包含点的对象名称 |
| `*.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 按如下方式解释全局模式：
+ 斜杠（`/`）字符用于分隔文件路径中的目录。
+ 星号 (`*`) 字符与不跨越文件夹边界的名称组分的零个或多个字符匹配。
+ 双星号 (`**`) 与所有目录中名称组分的零个或多个字符匹配。
**注意**
`ExcludePaths` 优先于 `IncludePaths`。如果 `IncludePaths` 和 `ExcludePaths` 都包含同一个文件夹，则不会扫描该文件夹以获取报告。
# 支持的 SARIF 属性
静态分析结果交换格式 (SARIF) 是一种输出文件格式，可用于 Amazon 的软件组成分析 (SCA) 和静态分析报告。 CodeCatalyst下面的示例显示了如何在静态分析报告中手动配置 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` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `$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` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `tool.driver` | 是 | 描述分析工具的 `toolComponent` 对象。 |
| `tool.name` | 否 | 表示用于执行分析的工具名称的属性。 |
| `results[]` | 是 | 上显示的分析工具的结果 CodeCatalyst。 |
## `toolComponent` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `name` | 是 | 分析工具的名称。 |
| `properties.artifactScanned` | 否 | 工具分析的构件总数。 |
| `rules[]` | 是 | 代表规则的 `reportingDescriptor` 对象数组。根据这些规则，分析工具会发现所分析代码中存在的问题。 |
## `reportingDescriptor` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `id` | 是 | 用于引用调查发现的规则的唯一标识符。 最大长度：1024 个字符 |
| `name` | 否 | 规则的显示名称。 最大长度：1024 个字符 |
| `shortDescription.text` | 否 | 规则的简短描述。 最大长度：3000 个字符 |
| `fullDescription.text` | 否 | 规则的完整描述。 最大长度：3000 个字符 |
| `helpUri` | 否 | 可以本地化的字符串，包含规则主要文档的绝对 URI。 最大长度：3000 个字符 |
| `properties.unscore` | 否 | 表示扫描调查发现是否已评分的标志。 |
| `properties.score.severity` | 否 | 一组固定的字符串，用于指定调查发现的严重程度。 最大长度：1024 个字符 |
| `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` | 否 | 一组固定的字符串，用于指定调查发现的严重程度。 最大长度：1024 个字符 |
| `defaultConfiguration.level` | 否 | 规则的默认严重性。 |
## `result` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `ruleId` | 是 | 用于引用调查发现的规则的唯一标识符。 最大长度：1024 个字符 |
| `ruleIndex` | 是 | 工具组件 `rules[]` 中相关规则的索引。 |
| `message.text` | 是 | 一条消息，描述结果并显示每个调查发现的消息。 最大长度：3000 个字符 |
| `rank` | 否 | 一个介于 0.0 到 100.0（含）之间的值，表示结果的优先级或重要性。0.0 表示最低优先级，100.0 表示最高优先级。 |
| `level` | 否 | 结果的严重性。 最大长度：1024 个字符 |
| `properties.unscore` | 否 | 表示扫描调查发现是否已评分的标志。 |
| `properties.score.severity` | 否 | 一组固定的字符串，用于指定调查发现的严重程度。 最大长度：1024 个字符 |
| `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` | 否 | 一组固定的字符串，用于指定调查发现的严重程度。 最大长度：1024 个字符 |
| `locations[]` | 是 | 检测到结果的位置集。除非只能通过在每个指定位置进行更改来纠正问题，否则只能包括一个位置。 CodeCatalyst 使用位置数组中的第一个值来注释结果。 `location` 对象的最大数量：10 |
| `relatedLocations[]` | 否 | 调查发现中参考的其它位置列表。 `location` 对象的最大数量：50 |
| `fixes[]` | 否 | 代表扫描工具提供的建议的`fix`对象数组。 CodeCatalyst 使用数`fixes`组中的第一个建议。 |
## `location` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `physicalLocation` | 是 | 标识构件和区域。 |
| `logicalLocations[]` | 否 | 用名称描述的一组位置，不提及构件。 |
## `physicalLocation` 对象
| Name | 必需 | 描述 |
| --- | --- | --- |
| `artifactLocation.uri` | 是 | 表示构件位置的 URI，通常是存储库中的文件或在构建过程中生成的文件。 |
| `fileLocation.uri` | 否 | 表示文件位置的回退 URI。如果 `artifactLocation.uri` 返回空，则使用此项。 |
| `region.startLine` | 是 | 区域中第一个字符的行号。 |
| `region.startColumn` | 是 | 区域中第一个字符的列号。 |
| `region.endLine` | 是 | 区域中最后一个字符的行号。 |
| `region.endColumn` | 是 | 区域中最后一个字符的列号。 |
## `logicalLocation` 对象
| Name | 必需 | 说明 |
| --- | --- | --- |
| `fullyQualifiedName` | 否 | 描述结果位置的其它信息。 最大长度：1024 个字符 |
## `fix` 对象
| Name | 必需 | 说明 |
| --- | --- | --- |
| `description.text` | 否 | 显示每个调查发现的建议的消息。 最大长度：3000 个字符 |
| `artifactChanges.[0].artifactLocation.uri` | 否 | 表示需要更新的构件位置的 URI。 |
# 使用工作流进行部署
使用[CodeCatalyst 工作流程](workflow.md)，您可以将应用程序和其他资源部署到各种目标， AWS Lambda例如 Amazon ECS 等。
## 如何部署应用程序？
要通过部署应用程序或资源 CodeCatalyst，首先要创建一个工作流，然后在其中指定部署操作。*部署操作*是一个工作流程构造块，它定义了要部署的*内容*、部署*位置*以及部署*方式*（例如，使用 blue/green 方案）。您可以使用 CodeCatalyst 控制台的可视化编辑器或 YAML 编辑器向工作流程添加部署操作。
部署应用程序或资源的步骤大致如下。
**部署应用程序（高级别任务）**
1. 在您的 CodeCatalyst 项目中，您可以为要部署的应用程序**添加源代码**。有关更多信息，请参阅 [将源代码存储在项目的存储库中 CodeCatalyst](source-repositories.md)。
1. 在您的 CodeCatalyst 项目中，您可以**添加一个环境**来定义目标 AWS 账户 和要部署到的可选亚马逊虚拟私有云 (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 模板或[AWS Serverless Application Model 模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html)在中创建 CloudFormation 堆栈。有关更多信息，请参阅 [部署 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
本节介绍如何使用工作流程将容器化应用程序部署到 Amazon 弹性容器服务集群中。 CodeCatalyst 为此，您必须将**部署到 Amazon ECS** 操作添加到工作流。此操作将注册您提供的[任务定义](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions)文件。注册后，任务定义将由在 [Amazon ECS 集群](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters)中运行的 [Amazon ECS 服务](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html)实例化。“实例化任务定义”等效于将应用程序部署到 Amazon ECS 中。
要使用此操作，您必须已拥有 Amazon ECS 集群、服务和任务定义文件。
有关 Amazon ECS 的更多信息，请参阅《Amazon Elastic Container Service 开发人员指南》**。
**提示**
有关说明如何使用**部署到 Amazon ECS** 操作的教程，请参阅[教程：将应用程序部署到 Amazon ECS](deploy-tut-ecs.md)。
**提示**
对于**部署到 Amazon ECS** 操作的工作示例，请使用**带 AWS Fargate的 Node.js API** 或**带 AWS Fargate的 Java API** 蓝图创建一个项目。有关更多信息，请参阅 [使用蓝图创建项目](projects-create.md#projects-create-console-template)。
**Topics**
+ [“部署到 Amazon ECS”操作使用的运行时映像](#deploy-action-ecs-runtime)
+ [教程：将应用程序部署到 Amazon ECS](deploy-tut-ecs.md)
+ [添加“部署到 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 和其他一些服务将无服务器应用程序部署到亚马逊弹性容器服务 (Amazon ECS) 中。 AWS 部署的应用程序是一个基于 Apache Web 服务器 Docker 映像构建的简单 Hello World 网站。本教程将引导您完成所需的准备工作（例如设置集群），然后介绍如何创建用于构建和部署应用程序的工作流。
**提示**
您可以使用蓝图来执行完整的 Amazon ECS 设置，而不是按照本教程的说明操作。您将需要使用**带 AWS Fargate的 Node.js API** 或**带 AWS Fargate的 Java API** 蓝图。有关更多信息，请参阅 [使用蓝图创建项目](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 管理控制台 并打开 AWS IAM Identity Center 控制台，网址为[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/)。
**注意**
请务必使用与您的 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. 在**查看和创建**页面上，检查相应信息，然后选择**创建**。
**将权限集分配给 CodeCatalyst ECSUser**
1. 在导航窗格中 **AWS 账户**，选择，然后选中您当前登录 AWS 账户 的旁边的复选框。
1. 选择**分配用户或组**。
1. 选择**用户**选项卡。
1. 选中 `CodeCatalystECSUser` 旁边的复选框。
1. 选择**下一步**。
1. 选中 `CodeCatalystECSPermissionSet` 旁边的复选框。
1. 选择**下一步**。
1. 检查相应信息，然后选择**提交**。
现在，你已经`CodeCatalystECSPermissionSet`将`CodeCatalystECSUser`和分配给你的 AWS 账户，将它们绑定在一起。
**要注销并重新登录，请使用以下身份登录 CodeCatalyst ECSUser**
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. 在顶部导航栏中，选择 AWS 图标 (![\[AWS icon\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/deploy/aws-logo.png))。`CodeCatalystECSUser`
的主页 AWS 管理控制台 随即出现。
1. 在顶部导航栏中，选择图 AWS CloudShell 标 (![\[CloudShell icon\]](http://docs.aws.amazon.com/zh_cn/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 服务器。
有关 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** 以保存文件并退出 cat。
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 资源名称（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 应显示在列表中，这表示创建成功。
**创建任务定义文件**
任务定义文件指示运行从中提取的 [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*
替换为您在[创建任务执行角色](#deploy-tut-ecs-create-task-execution-role)中记下的任务执行角色的 ARN。
1. 将光标置于最后一个大括号（`}`）之后。
1. 按 **Enter** 和 **Ctrl\$1d** 以保存文件并退出 cat。
**将任务定义文件注册到 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 用户指南》**中的[创建 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-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**；对于**来源**，选择**任何位置**。
1. 选择底部的**创建**。
1. 创建服务时请等待。该过程可能需要几分钟。
1. 选择**任务**选项卡，然后选择刷新按钮。确认所有三个任务的**最后状态**列都设置为**正在运行**。
**（可选）验证 Apache 占位符应用程序是否正在运行**
1. 在**任务**选项卡中，选择三个任务之一。
1. 在**公有 IP** 字段中，选择**开放地址**。
此时将显示 `It Works!` 页面。这表明 Amazon ECS 服务已成功启动一项任务，该任务会启动带 Apache 映像的 Docker 容器。
在本教程中，此时您已手动部署 Amazon ECS 集群、服务和任务定义以及 Apache 占位符应用程序。在所有这些项目准备就绪后，便可创建一个工作流以将 Apache 占位符应用程序替换为教程中的 Hello World 应用程序。
## 步骤 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. 选择**创建策略**。
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** 以保存文件并退出 cat。
**创建构建策略和构建角色**
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** 以保存文件并退出 cat。
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** 以保存文件并退出 cat。
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 accounts (账户)**。此时将显示账户连接列表。
1. 选择代表您在其中创建构建和部署角色的 AWS 账户的账户连接。
1. **从管理控制台中选择 “ AWS 管理角色**”。
此时将出现 “**将 IAM 角色添加到 Amazon CodeCatalyst 空间**” 页面。您可能需要登录才能访问该页面。
1. 选择**添加您在 IAM 中创建的现有角色**。
这将显示一个下拉列表。该列表显示所有具有包含 `codecatalyst-runner.amazonaws.com` 和 `codecatalyst.amazonaws.com` 服务主体的信任策略的 IAM 角色。
1. 在该下拉列表中，选择 `codecatalyst-ecs-build-role`，然后选择**添加角色**。
**注意**
如果您看到的是 `The security token included in the request is invalid`，则可能是因为您不具有适当的权限。要解决此问题，请使用您在创建 CodeCatalyst空间时使用的 AWS 账号退出并重新登录。 AWS
1. 选择**添加 IAM 角色**，再选择**添加您在 IAM 中创建的现有角色**，然后在下拉列表中选择 `codecatalyst-ecs-deploy-role`。选择**添加角色**。
现在，您已将构建角色和部署角色添加到您的空间。
1. 复制 A **mazon CodeCatalyst 显示名称**的值。您稍后在创建工作流时将需要此值。
## 步骤 6：创建源存储库
在此步骤中，您将在中创建源存储库 CodeCatalyst。此存储库将存储教程的源文件，例如任务定义文件。
有关源存储库的更多信息，请参阅[创建源存储库](source-repositories-create.md)。
**创建源存储库**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Reference](https://docs.docker.com/engine/reference/builder/)。
此处指定的 Dockerfile 指示使用 Apache 2.4 基本映像（`httpd`）。它还包括用于将名为 `index.html` 的源文件复制到提供网页的 Apache 服务器上的文件夹中的指令。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_TAG` 来表示映像，而不是在 `image:` 字段（`httpd:2.4`）中指定硬编码的 Docker 映像名称。当您在下一个步骤中运行工作流时，这些变量将被替换为工作流的构建操作所生成的实际值。
有关任务定义参数的详细信息，请参阅《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*
替换为您在[创建任务执行角色](#deploy-tut-ecs-create-task-execution-role)中记下的任务执行角色的 ARN。
1. 选择**提交**，然后再次选择**提交**。
这会将 `taskdef.json` 文件添加到您的存储库中。
## 步骤 8：创建并运行工作流
在此步骤中，您将创建一个工作流来提取源文件，将源文件构建到 Docker 映像中，然后将该映像部署到 Amazon ECS 集群。此部署将替换现有的 Apache 占位符应用程序。
工作流包含以下按顺序运行的构造块：
+ 触发器 – 当您将更改推送到源存储库时，此触发器会自动启动工作流运行。有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。
+ 构建操作（`BuildBackend`）– 此操作在触发后会使用 Dockerfile 构建 Docker 映像并将该映像推送到 Amazon ECR。构建操作还将使用正确的 `image` 字段值更新 `taskdef.json`，然后创建此文件的输出构件。此构件将用作接下来的部署操作的输入。
有关构建操作的更多信息，请参阅[使用工作流进行构建](build-workflow-actions.md)。
+ 部署操作（`DeployToECS`）– 构建操作完成后，部署操作将查找构建操作（`TaskDefArtifact`）所生成的输出构件，查找其中包含的 `taskdef.json` 并将它注册到您的 Amazon ECS 服务。之后，该服务按照 `taskdef.json` 文件中的说明，在您的 Amazon ECS 集群中运行三个 Amazon ECS 任务以及关联的 Hello World Docker 容器。
**创建工作流**
1. **在 CodeCatalyst 控制台的导航窗格中，选择 C **I/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)。
+ 两个实例都*us-west-2*使用您的 AWS 地区代码。有关区域代码的列表，请参阅《AWS 一般参考》**中的 [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。
**注意**
如果您决定不创建生成和部署角色，请*codecatalyst-ecs-deploy-role*使用`CodeCatalystWorkflowDevelopmentRole-spaceName`角色名称替换*codecatalyst-ecs-build-role*和。有关该角色的更多信息，请参阅[步骤 4：创建 AWS 角色](#deploy-tut-ecs-build-deploy-roles)。
**提示**
您可以使用**渲染 Amazon ECS 任务定义**操作来更新存储库和映像名称，而不是使用前面的工作流代码中显示的 `find` 和 `sed` 命令。有关更多信息，请参阅 [修改 Amazon ECS 任务定义](render-ecs-action.md)。
1. （可选）选择**验证**，确保 YAML 代码在提交之前有效。
1. 选择**提交**。
1. 在**提交工作流**对话框中，输入以下内容：
1. 对于**提交消息**，移除文本并输入：
```
Add first workflow
```
1. 对于**存储库**，选择 `codecatalyst-ecs-source-repository`。
1. 对于**分支名称**，选择“主”。
1. 选择**提交**。
现在，您已创建工作流。由于在工作流顶部定义了触发器，因此工作流运行会自动启动。具体而言，当您将 `workflow.yaml` 文件提交（并推送）到源存储库时，触发器启动了工作流运行。
**查看工作流运行进度**
1. **在 CodeCatalyst 控制台的导航窗格中，选择 C **I/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** 服务。
# 添加“部署到 Amazon ECS”操作
按照以下说明，将**部署到 Amazon ECS** 操作添加到工作流。
------
#### [ Visual ]
**使用可视化编辑器添加“部署到 Amazon ECS”操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 编辑器添加“部署到 Amazon ECS”操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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)。
| 键 | 值 |
| --- | --- |
| cluster | 在工作流运行期间部署到的 Amazon ECS 集群的名称。 示例：`codecatalyst-ecs-cluster` |
| deployment-platform | 部署平台的名称。 硬编码为 `AWS:ECS`。 |
| service | 在工作流运行期间部署到的 Amazon ECS 服务的名称。 示例：`codecatalyst-ecs-service` |
| task-definition-arn | 在工作流运行期间注册的任务定义的 Amazon 资源名称（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`。
**对应的用户界面：工作流程图/ ECSDeploy action\$1nn/ aws/ecs-deploy @v1 标签**
## DependsOn
(*ECSDeployAction*/**DependsOn**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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：配置 tab/Advanced -可选/计算类型**
## 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：配置 tab/Advanced -可选/计算舰队**
## Timeout
(*ECSDeployAction*/**Timeout**)
（可选）
指定操作在 CodeCatalyst 结束操作之前可以运行的时间（以分钟（YAML 编辑器）或小时和分钟（可视化编辑器）为单位。最小值为 5 分钟，最大值如 [中的工作流程配额 CodeCatalyst](workflows-quotas.md) 中描述。默认超时值与最大超时值相同。
对应的 UI：“配置”选项卡/**超时 – 可选**
## Environment
(*ECSDeployAction*/**Environment**)
（必需）
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*ECSDeployAction*/Environment/Connections/**Name**)
（如果包含 [Connections](#deploy.action.ecs.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Role
(*ECSDeployAction*/Environment/Connections/**Role**)
（如果包含 [Connections](#deploy.action.ecs.environment.connections)，则为必需）
指定**部署到 Amazon ECS** 操作用于访问 AWS的 IAM 角色的名称。请确保您已将[该角色添加到您的 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在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）“配置” 选项卡/' '/ 角色 Environment/account/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 区域。有关区域代码的列表，请参阅《AWS 一般参考》**中的 [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。
对应的 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 服务配置为使用 blue/green 部署，则为必填项，否则省略）
指定现有 CodeDeploy 应用程序规范 (AppSpec) 文件的名称和路径。此文件必须位于 CodeCatalyst 源存储库的根目录中。有关 AppSpec 文件的更多信息，请参阅《*AWS CodeDeploy 用户指南》*中的[CodeDeploy 应用程序规范 (AppSpec) 文件](https://docs.aws.amazon.com/codedeploy/latest/userguide/application-specification-files.html)。
**注意**
只有在您已将 Amazon ECS 服务配置为执行 blue/green 部署时，才提供 CodeDeploy 信息。对于滚动更新部署（默认），请省略 CodeDeploy 信息。有关更多信息，请参阅《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)。
本节介绍如何使用工作流程将容器化应用程序部署到 Kubernetes 集群中。 CodeCatalyst 为此，您必须将**部署到 Kubernetes 集群**操作添加到工作流。此操作使用一个或多个 Kubernetes 清单文件将您的应用程序部署到您在 Amazon Elastic Kubernetes Service（EKS）中设置的 Kubernetes 集群。有关示例清单，请参阅[教程：将应用程序部署到 Amazon EKS](deploy-tut-eks.md) 中的 [部署 .yaml](deploy-tut-eks.md#deploy-tut-eks-source-files-deployment-yml)。
有关 Kubernetes 的更多信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/home/)。
有关 Amazon EKS 的更多信息，请参阅《Amazon EKS 用户指南》**中的[什么是 Amazon EKS？](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html)
**Topics**
+ [“部署到 Kubernetes 集群”操作的工作原理](#deploy-action-eks-howitworks)
+ [“部署到 Amazon EKS”操作使用的运行时映像](#deploy-action-eks-runtime)
+ [教程：将应用程序部署到 Amazon EKS](deploy-tut-eks.md)
+ [添加“部署到 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*到已配置的集群中。有关此命令的更多信息，请参阅《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 EKS 和其他一些服务将容器化应用程序部署到亚马逊 Elastic Kubernetes S CodeCatalyst ervice 中。 AWS 部署的应用程序是简单“Hello, World\$1” 基于 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)。
+ 在你的项目中，你需要一个 C CodeCatalyst I/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 User Guide》**中的 [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。
**启动开发环境**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 User Guide》**中的 [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)。
1. 按如下方式创建 IAM Identity Center 用户：
1. 登录 AWS 管理控制台 并打开 AWS IAM Identity Center 控制台，网址为[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/)。
（如果您之前从未登录过 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-permission-set`将`codecatalyst-eks-user`和分配给你的 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 账户**，然后选择您为其分配了 `codecatalyst-eks-user` 用户和权限集的 AWS 账户 的名称。
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` 指令）
**注意**
与 Amazon EKS 的 CodeCatalyst 集成不支持@@ [私有集群](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\$1” 消息。
+ 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)
+ [部署 .yaml](#deploy-tut-eks-source-files-deployment-yml)
### index.html
`index.html` 文件在浏览器中显示“Hello, World\$1” 消息。
**添加 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 Reference](https://docs.docker.com/engine/reference/builder/)。
此处指定的 Dockerfile 指示使用 Apache 2.4 基本映像（`httpd`）。它还包括用于将名为 `index.html` 的源文件复制到提供网页的 Apache 服务器上的文件夹中的指令。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 添加到您的存储库中。
### 部署 .yaml
在此部分中，您将 `deployment.yaml` 文件添加到存储库。`deployment.yaml` 文件是一个 Kubernetes 清单，它定义两种要运行的 Kubernetes 资源类型或*类别*：“服务”和“部署”。
+ “服务”将负载均衡器部署到 Amazon EC2 中。负载均衡器为您提供面向 Internet 的公有 URL 和标准端口（端口 80），您可以使用它们浏览找到“Hello, World\$1” 应用程序的修订。
+ “部署”部署三个容器组（pod），每个容器组（pod）将包含一个带“Hello, World\$1”的 Docker 容器 应用程序的修订。这三个容器组（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*已替换为您所在的地区。
有关此命令的详细信息，请参阅 [Manage IAM users and roles](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** 操作对您的 Kubernetes 集群的 `system:masters` 权限。
## 步骤 8：创建并运行工作流
在此步骤中，您将创建一个工作流来提取源文件，将源文件构建到 Docker 映像中，然后将该映像部署到 Amazon EKS 集群中的三个容器组（pod）中。
工作流包含以下按顺序运行的构造块：
+ 触发器 – 当您将更改推送到源存储库时，此触发器会自动启动工作流运行。有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](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），每个容器组（pod）包含一个“Hello, World\$1” 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)。
+ 两个实例都*us-west-2*使用您的 AWS 地区代码。有关区域代码的列表，请参阅《AWS 一般参考》**中的 [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
**注意**
如果您决定不创建生成和部署角色，请*codecatalyst-eks-deploy-role*使用`CodeCatalystWorkflowDevelopmentRole-spaceName`角色名称替换*codecatalyst-eks-build-role*和。有关该角色的更多信息，请参阅[步骤 5：创建 AWS 角色](#deploy-tut-eks-roles)。
1. （可选）选择**验证**，确保 YAML 代码在提交之前有效。
1. 选择**提交**。
1. 在**提交工作流**对话框中，输入以下内容：
1. 对于**提交消息**，移除文本并输入：
```
Add first workflow
```
1. 对于**存储库**，选择 `codecatalyst-eks-source-repository`。
1. 对于**分支名称**，选择“主”。
1. 选择**提交**。
现在，您已创建工作流。由于在工作流顶部定义了触发器，因此工作流运行会自动启动。具体而言，当您将 `workflow.yaml` 文件提交（并推送）到源存储库时，触发器启动了工作流运行。
**查看工作流运行进度**
1. **在 CodeCatalyst 控制台的导航窗格中，选择 C **I/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\$1” 网页将显示在浏览器中，这表示您已成功部署应用程序。
## 步骤 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 控制台的导航窗格中，选择 C **I/CD**，然后选择 Workflows。**
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 名称**值复制并粘贴到浏览器的地址栏中。
“Tutorial Complete\$1” 网页将显示在浏览器中，这表示您已成功部署新版本的应用程序。
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 EK** S 服务。
# 添加“部署到 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 映像。有关 Dockerfile 的更多信息，请参阅 [Dockerfile reference](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 文件添加角色，请参阅 A **mazon 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。存储库将存储您的应用程序源文件、Dockerfile 和 Kubernetes 清单。有关更多信息，请参阅 [使用源存储库存储代码并协作处理代码 CodeCatalyst使用源存储库存储代码并进行协作](source.md)。
------
#### [ Visual ]
**使用可视化编辑器添加“部署到 Kubernetes 集群”操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 编辑器添加“部署到 Kubernetes 集群”操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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)。
| 键 | 值 |
| --- | --- |
| cluster | 在工作流运行期间部署到的 Amazon EKS 集群的 Amazon 资源名称（ARN）。 示例：`arn:aws:eks:us-west-2:111122223333:cluster/codecatalyst-eks-cluster` |
| deployment-platform | 部署平台的名称。 硬编码为 `AWS:EKS`。 |
| 元数据 | 预留。与工作流运行期间部署的集群相关的 JSON 格式的元数据。 |
| namespace | 已将集群部署到的 Kubernetes 命名空间。 示例：`default` |
| resources | 预留。与工作流运行期间部署的资源相关的 JSON 格式的元数据。 |
| server | API 服务器端点的名称，可使用管理工具（例如 `kubectl`）通过此端点与集群进行通信。 有关更多信息，请参阅《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**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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：配置 tab/Advanced -可选/计算类型**
## 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：配置 tab/Advanced -可选/计算舰队**
## Timeout
(*DeployToKubernetesCluster*/**Timeout**)
（可选）
指定操作在 CodeCatalyst 结束操作之前可以运行的时间（以分钟（YAML 编辑器）或小时和分钟（可视化编辑器）为单位。最小值为 5 分钟，最大值如 [中的工作流程配额 CodeCatalyst](workflows-quotas.md) 中描述。默认超时值与最大超时值相同。
对应的 UI：“配置”选项卡/**超时 – 可选**
## Environment
(*DeployToKubernetesCluster*/**Environment**)
（必需）
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*DeployToKubernetesCluster*/Environment/Connections/**Name**)
（可选）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Role
(*DeployToKubernetesCluster*/Environment/Connections/**Role**)
（如果包含 [Connections](#deploy.action.eks.environment.connections)，则为必需）
指定**部署到 Kubernetes 集群**操作用于访问 AWS的 IAM 角色的名称。请确保您已将[该角色添加到您的 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)，了解有关向账户连接添加 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**
## 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 文档中的 [Subdividing your cluster using Kubernetes namespaces](https://kubernetes.io/docs/tasks/administer-cluster/namespaces/#subdividing-your-cluster-using-kubernetes-namespaces)。
如果省略命名空间，则使用值 `default`。
对应的 UI：“配置”选项卡/**命名空间**
## Region
(*DeployToKubernetesCluster*/Configuration/**Region**)
（必需）
指定您的 Amazon EKS 集群和服务所在的 AWS 区域。有关区域代码的列表，请参阅《AWS 一般参考》**中的 [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)。
对应的 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**)
（必需）
指定 YAML 格式的 Kubernetes 清单文件的路径，这些文件在 Kubernetes 文档中称作*配置文件*、*config 文件*，或简称为*配置*。
如果您使用了多个清单文件，请将它们置于一个文件夹中并引用该文件夹。Kubernetes 会按字母数字顺序处理清单文件，因此请务必在文件名前添加递增数字或字母，以便控制处理顺序。例如：
`00-namespace.yaml`
`01-deployment.yaml`
如果清单文件位于源存储库中，则该路径相对于源存储库根文件夹。如果该文件位于上一工作流操作生成的构件中，则该路径相对于构件根文件夹。
示例：
`Manifests/`
`deployment.yaml`
`my-deployment.yml`
请勿使用通配符（`*`）。
**注意**
不支持 [Helm 图表](https://helm.sh/docs/topics/charts/)和 [kustomization 文件](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/)。
有关清单文件的更多信息，请参阅 Kubernetes 文档中的 [Organizing resource configurations](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 你可以在 De **ploy CloudFormation stack** 操作中使用什么。
**提示**
有关向您展示如何使用 “部署** 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 堆栈。
本教程中的应用程序是一个输出“Hello World”消息的简单 Web 应用程序。它由一个 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 **Deploy CloudFormation stack** 操作访问您的 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)，但您无需立即创建此角色，因为当您在步骤 5 中运行工作流时，`sam-template.yml` 文件会为您创建它。
**创建部署角色**
1. 按如下步骤操作，为角色创建策略：
1. 登录到 AWS。
1. 使用 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 在导航窗格中，选择**策略**。
1. 选择**创建策略**。
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. 选择**创建策略**。
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. 在导航窗格中，选择**角色**。
1. 选择**创建角色**。
1. 选择 **AWS 服务**。
1. 在 “**用例**” 部分，**CloudFormation**从下拉列表中进行选择。
1. 选择 **CloudFormation** 单选按钮。
1. 选择底部的**下一步**。
1. 使用搜索框找到以下权限策略，然后选中它们对应的复选框。
**注意**
如果您搜索一个策略，但该策略未显示，请务必选择**清除筛选条件**，然后重试。
+ **CloudWatchFullAccess**
+ **AWS CloudFormationFullAccess**
+ **IAMFull访问**
+ **AWS Lambda\$1 FullAccess**
+ **亚马逊APIGateway管理员**
+ **亚马逊 3 FullAccess**
+ **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`）添加到连接。这是因为在部署角色之间 CodeCatalyst 已经建立连接*之后 *CloudFormation**（不是 CodeCatalyst） AWS 使用堆栈角色。由于堆栈角色不用于获取 CodeCatalyst 访问权限 AWS，因此无需将其与账户连接相关联。
**将构建角色和部署角色添加到账户连接**
1. 在中 CodeCatalyst，导航到您的空间。
1. 选择 **AWS accounts (账户)**。此时将显示账户连接列表。
1. 选择代表您在其中创建构建和部署角色的 AWS 账户的账户连接。
1. **从管理控制台中选择 “ AWS 管理角色**”。
此时将出现 “**将 IAM 角色添加到 Amazon CodeCatalyst 空间**” 页面。您可能需要登录才能访问该页面。
1. 选择**添加您在 IAM 中创建的现有角色**。
这将显示一个下拉列表。该列表显示所有具有包含 `codecatalyst-runner.amazonaws.com` 和 `codecatalyst.amazonaws.com` 服务主体的信任策略的 IAM 角色。
1. 在该下拉列表中，选择 `codecatalyst-build-role`，然后选择**添加角色**。
1. 选择**添加 IAM 角色**，再选择**添加您在 IAM 中创建的现有角色**，然后在下拉列表中选择 `codecatalyst-deploy-role`。选择**添加角色**。
现在，您已将构建角色和部署角色添加到您的空间。
1. 复制 A **mazon CodeCatalyst 显示名称**的值。您稍后在创建工作流时将需要此值。
## 步骤 4：创建 Amazon S3 存储桶
在此步骤中，您将创建可在其中存储无服务器应用程序的部署包 .zip 文件的 Amazon S3 存储桶。
**创建 Amazon S3 存储桶**
1. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在主窗格中，选择**创建存储桶**。
1. 对于**存储桶名称**，输入：
```
codecatalyst-cfn-s3-bucket
```
1. 对于 **AWS 区域**，选择一个区域。本教程假设您选择了**美国西部（俄勒冈州）us-west-2**。有关 Amazon S3 支持的区域的信息，请参阅《AWS 一般参考》**中的 [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目 `codecatalyst-cfn-project`。
1. 在导航窗格中，选择**代码**，然后选择**源存储库**。
1. 从源存储库列表中，选择您的存储库 `codecatalyst-cfn-source-repository`。
1. 在**文件**中，选择**创建文件**。
1. 对于**文件名**，输入：
```
.npmignore
```
1. 在文本框中，输入以下代码：
```
tests/*
```
1. 选择**提交**，然后再次选择**提交**。
现在，您已在存储库的根目录中创建名为 `.npmignore` 的文件。
### package.json 文件
`package.json` 文件包含有关您的 Node 项目的重要元数据，例如项目名称、版本号、描述、依赖项以及描述如何运行应用程序并与之交互的其他详细信息。
本教程中的 `package.json` 包括依赖项列表和 `test` 脚本。测试脚本执行以下操作：
+ 通过使用 [mocha](https://mochajs.org/)，测试脚本运行 `hello-world/tests/unit/` 中指定的单元测试，并使用 [xunit]() 报告器将结果写入 `junit.xml` 文件。
+ 通过使用 [Istanbul (nyc)](https://istanbul.js.org/)，测试脚本使用 [clover](https://openclover.org/doc/manual/4.2.0/general--about-openclover.html) 报告器生成代码覆盖率报告（`clover.xml`）。有关更多信息，请参阅 Istanbul 文档中的 [Using alternative reporters](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 提供了一种有用的:: [Serverless AWS:: Function 资源](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)类型。这种类型执行许多 behind-the-scenes配置，你通常必须写出这些配置才能使用基本 CloudFormation 语法。例如，`AWS::Serverless::Function` 创建一个 Lambda 函数、Lambda 执行角色和启动该函数的事件源映射。如果你想用 basic 来编写，你必须对所有这些代码进行编码 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`文件包含下载和安装 AWS SAM CLI 实用程序的说明。工作流使用此实用工具来打包 `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
```
在前面的代码中，*us-west-2*替换为您所在 AWS 的地区。
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. 选择**提交**，然后再次选择**提交**。
现在，您已将名为 `test-handler.js` 的文件添加到 `hello-world/tests/unit` 文件夹下。
现在，您已添加所有源文件。
请花点时间仔细检查您的工作，确保已将所有文件置于正确的文件夹中。文件夹结构如下所示：
```
.
|— 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 package manager (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)。
+ *us-west-2*包含您的 Amazon S3 存储桶所在区域（第一个实例）和堆栈将部署的位置（第二个实例）的两个实例。这两个区域可能不同。本教程假定两个区域都设置为 `us-west-2`。有关 Amazon S3 和支持的区域的详细信息 CloudFormation，请参阅中的[服务终端节点和配额*AWS 一般参考*](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)。
+ 将 *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 资源名称 (ARN)。[步骤 2：创建 AWS 角色](#deploy-tut-lambda-cfn-roles)
**注意**
如果您决定不创建构建、部署和堆叠角色 *codecatalyst-build-role**codecatalyst-deploy-role*，请使用角色的*arn:aws:iam::111122223333:role/StackRole*名称或 ARN 替换、和。`CodeCatalystWorkflowDevelopmentRole-spaceName`有关该角色的更多信息，请参阅[步骤 2：创建 AWS 角色](#deploy-tut-lambda-cfn-roles)。
有关前面显示的代码中的属性的信息，请参阅['部署 CloudFormation 堆栈'动作 YAML](deploy-action-ref-cfn.md)。
1. （可选）选择**验证**，确保 YAML 代码在提交之前有效。
1. 选择**提交**。
1. 在**提交工作流**对话框中，输入以下内容：
1. 对于**工作流文件名**，保留默认值 `codecatalyst-cfn-workflow`。
1. 对于**提交消息**，输入：
```
add initial workflow file
```
1. 对于**存储库**，选择 **codecatalyst-cfn-source-repository**。
1. 对于**分支名称**，选择**主**。
1. 选择**提交**。
现在，您已创建工作流。由于在工作流顶部定义了触发器，因此工作流运行会自动启动。具体而言，当您将 `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://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。
1. 观察 AWS SAM 模板创建的 **codecatalyst-cfn-stack**API。API 名称来自工作流定义文件（`codecatalyst-cfn-workflow.yaml`）中的 `Configuration/name` 值。
1. 打开 AWS Lambda 控制台，网址为[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 删除 `codecatalyst-cfn-workflow`。
1. 删除 `codecatalyst-cfn-environment`。
1. 删除 `codecatalyst-cfn-source-repository`。
1. 删除 `codecatalyst-cfn-project`。
**要在里面清理干净 AWS 管理控制台**
1. 清理一下 CloudFormation，如下所示：
1. 在 [https://console.aws.amazon.com/cloudformat](https://console.aws.amazon.com/cloudformation/) ion 上打开 CloudFormation 控制台。
1. 删除 `codecatalyst-cfn-stack`。
删除堆栈将从 API Gateway 和 Lambda 服务中移除所有教程资源。
1. 在 Amazon S3 中进行清理，如下所示：
1. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
# 配置回滚
默认情况下，如果 **Deploy CloudFormation 堆栈**操作失败，它将导致堆栈回滚 CloudFormation 到上次已知的稳定状态。您可以更改行为，使回滚不仅在操作失败时发生，而且还会在出现指定的 Amazon CloudWatch 警报时发生。有关 CloudWatch 警报的更多信息，请参阅[亚马逊* CloudWatch 用户指南中的使用亚马逊 CloudWatch *警报](https://docs.aws.amazon.com/)。
您也可以更改默认行为，以便在操作失败时 CloudFormation 不会回滚堆栈。
按照以下说明操作来配置回滚。
**注意**
您无法手动启动回滚。
------
#### [ Visual ]
**开始前的准备工作**
1. 确保您的[工作流程](workflow.md)包含有效的 De **ploy CloudFormation 堆栈**操作。有关更多信息，请参阅 [部署 CloudFormation 堆栈](deploy-action-cfn.md)。
1. 在 “**部署 CloudFormation **堆栈” 操作的 “**堆栈角色-可选**” 字段中指定的角色中，确保包含**CloudWatchFullAccess**权限。有关创建此具有适当权限的角色的信息，请参阅[步骤 2：创建 AWS 角色](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles)。
**为 “部署 CloudFormation 堆栈” 操作配置回滚警报**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 选择您的**部署 CloudFormation 堆栈**操作。
1. 在详细信息窗格中，选择**配置**。
1. 在底部，展开**高级**。
1. 在 “**监控警报**” 下 ARNs，选择 “**添加警报**”。
1. 在以下字段中输入信息。
+ **警报 ARN**
指定要用作回滚触发器的亚马逊 CloudWatch 警报的亚马逊资源名称 (ARN)。例如 `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`。您可以拥有最多 5 个回滚触发器。
**注意**
如果您指定 CloudWatch 警报 ARN，则还需要配置其他权限才能使操作能够访问。 CloudWatch有关更多信息，请参阅 [配置回滚](#deploy-consumption-enable-alarms)。
+ **监控时间**
指定 CloudFormation 监视指定警报的时间段，介于 0 到 180 分钟之间。在部署完所有堆栈资源*后*开始监控。如果警报发生在指定的监控时间内，则部署将失败，并回 CloudFormation 滚整个堆栈操作。
默认值：0。 CloudFormation 仅在部署堆栈资源时监控警报，而不在部署堆栈资源之后监视警报。
------
#### [ YAML ]
**为 “部署 CloudFormation 堆栈” 操作配置回滚触发器**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 在 De **ploy CloudFormation 堆栈**操作的`role-arn`属性中指定的角色中，确保包含**CloudWatchFullAccess**权限。有关创建此具有适当权限的角色的信息，请参阅[步骤 2：创建 AWS 角色](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles)。
------
------
#### [ Visual ]
**关闭 “部署 CloudFormation 堆栈” 操作的回滚功能**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择包含**部署 CloudFormation 堆栈**操作的工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 选择您的**部署 CloudFormation 堆栈**操作。
1. 在详细信息窗格中，选择**配置**。
1. 在底部，展开**高级**。
1. 启用**禁用回滚**。
------
#### [ YAML ]
**关闭 “部署 CloudFormation 堆栈” 操作的回滚功能**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 资源名称（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**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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：配置 tab/Advanced -可选/计算类型**
## 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：配置 tab/Advanced -可选/计算舰队**
## Timeout
(*DeployCloudFormationStack*/**Timeout**)
（可选）
指定操作在 CodeCatalyst 结束操作之前可以运行的时间（以分钟（YAML 编辑器）或小时和分钟（可视化编辑器）为单位。最小值为 5 分钟，最大值如 [中的工作流程配额 CodeCatalyst](workflows-quotas.md) 中描述。默认超时值与最大超时值相同。
对应的 UI：“配置”选项卡/**超时 (分钟) – 可选**
## Environment
(*DeployCloudFormationStack*/**Environment**)
（必需）
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*DeployCloudFormationStack*/Environment/Connections/**Name**)
（如果包含 [Connections](#deploy.action.cfn.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Role
(*DeployCloudFormationStack*/Environment/Connections/**Role**)
（如果包含 [Connections](#deploy.action.cfn.environment.connections)，则为必需）
指定 De **ploy CloudFormation 堆栈**操作用于访问的 IAM 角色的名称 AWS 和 CloudFormation 服务。请确保您已将[该角色添加到您的 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**
## Inputs
(*DeployCloudFormationStack*/**Inputs**)
（可选）
`Inputs` 部分中定义了工作流运行期间 `DeployCloudFormationStack` 所需的数据。
**注意**
每个 Deplo **y 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**)
（必需）
为 De **ploy 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**)
（必需）
指定堆栈角色的亚马逊资源名称 (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 命令参考*》中的 deplo CloudFormation [y](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 命令参考*》中的 dep CloudFormation [loy](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 命令参考*》中的 dep CloudFormation [loy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) 参数。
有关 Depl **oy 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**)
（可选）
指定是否希望 **Deploy 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 无法在分配的时间内创建整个堆栈，它将因超时而导致堆栈创建失败并回滚该堆栈。
默认情况下，堆栈创建从不超时。但是，单个资源可能会根据它们所实施服务的性质而具有自己的超时。例如，如果堆栈中的单个资源发生超时，则堆栈创建也会超时，即使尚未达到您为堆栈创建指定的超时也不例外。
**对应的用户界面：配置选项卡/高级/超CloudFormation时**
## notification-arns
(*DeployCloudFormationStack*/Configuration/**notification-arns**)
（可选）
指定您 CodeCatalyst 要向其发送通知消息的 Amazon SNS 主题的 ARN。例如 `arn:aws:sns:us-east-1:111222333:MyTopic`。当 **Deploy CloudFormation 堆栈**操作运行时，与 CodeCatalyst CloudFormation 协调，为堆栈创建或更新过程中发生的每个 CloudFormation 事件发送一条通知。（事件显示在 CloudFormation 控制台堆栈的 “**事件**” 选项卡中。） 最多可以指定五个主题。有关更多信息，请参阅 [Amazon SNS 是什么？](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)。
**对应的用户界面：“配置” 选项卡/高级/ “通知” ARNs**
## monitor-alarm-arns
(*DeployCloudFormationStack*/Configuration/**monitor-alarm-arns**)
（可选）
指定要用作回滚触发器的亚马逊 CloudWatch 警报的亚马逊资源名称 (ARN)。例如 `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`。您可以拥有最多 5 个回滚触发器。
**注意**
如果您指定 CloudWatch 警报 ARN，则还需要配置其他权限才能使操作能够访问。 CloudWatch有关更多信息，请参阅 [配置回滚](deploy-consumption-enable-alarms.md)。
**对应的用户界面：“配置” 选项卡/高级/监控警报 ARNs**
## monitor-timeout-in-minutes
(*DeployCloudFormationStack*/Configuration/**monitor-timeout-in-minutes**)
（可选）
指定 CloudFormation 监视指定警报的时间段，介于 0 到 180 分钟之间。在部署完所有堆栈资源*后*开始监控。如果警报发生在指定的监控时间内，则部署将失败，并回 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 部署” 操作](#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 部署” 操作
如果您使用开发了应用程序 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) Developer Guide》**中的 [AWS CDK Toolkit (cdk command)](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 月版映像中提供的最新工具。要升级操作，请在工作流定义文件中将其 `Identifier` 属性设置为 `aws/cdk-deploy@v2`。有关更多信息，请参阅 [“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) 和[“AWS CDK 部署”操作 YAML](cdk-dep-action-ref.md) 中 `Role` 属性的说明。
```
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) Developer Guide》**中的 [How to bootstrap](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) Developer Guide》**中的 [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)。
------
#### [ Visual ]
**使用可视化编辑器添加AWS CDK “部署” 操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 install”错误？](troubleshooting-workflows.md#troubleshooting-workflows-npm)，了解有关如何修复错误的信息。
------
#### [ YAML ]
**使用 YAML 编辑器添加AWS CDK “部署” 操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 install”错误？](troubleshooting-workflows.md#troubleshooting-workflows-npm)，了解有关如何修复错误的信息。
------
# “AWS CDK 部署”变量
**AWS CDK 部署**操作在运行时会生成并设置以下变量。这些变量被称为*预定义变量*。
有关在工作流中引用这些变量的信息，请参阅 [使用预定义变量](workflows-using-predefined-variables.md)。
| 键 | 值 |
| --- | --- |
| stack-id | 在工作流程运行期间部署到的 AWS CDK 应用程序堆栈的 Amazon 资源名称 (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 variables* | 除了生成前面列出的变量外，**AWS CDK 部署**操作还将*CloudFormation*输出变量作为*工作流*变量公开，以便在后续的工作流操作中使用。默认情况下，该操作仅公开它找到的前四个（或更少） CloudFormation变量。要确定哪些变量已公开，请运行一次 **AWS CDK 部署**操作，然后在运行详细信息页面的**变量**选项卡中查看。如果**变量**选项卡上列出的变量不是您需要的，则可以使用 `CfnOutputVariables` YAML 属性配置其他变量。有关更多信息，请参阅[“AWS CDK 部署”操作 YAML](cdk-dep-action-ref.md) 中 [CfnOutputVariables](cdk-dep-action-ref.md#cdk.dep.cfn.out) 属性的描述。 |
# “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)。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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：配置 tab/Advanced -可选/计算类型**
## 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：配置 tab/Advanced -可选/计算舰队**
## 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`。如果您未指定构件，则该操作会合成模板，但不会将模板保存在构件中。考虑将合成的模板保存在构件中，以便保留其记录，供测试或故障排除之用。
**对应的用户界面：输出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 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*CDKDeploy*/Environment/Connections/**Name**)
（如果包含 [Connections](#cdk.dep.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## 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在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）“配置” 选项卡/' '/ 角色 Environment/account/role**
## Configuration
(*CDKDeploy*/**Configuration**)
（必需）
可在其中定义操作的配置属性的部分。
对应的 UI：**配置**选项卡
## StackName
(*CDKDeploy*/Configuration/**StackName**)
（必需）
AWS CDK 应用程序堆栈的名称，显示在 AWS CDK 应用程序目录的入口点文件中。`bin`以下示例显示了 TypeScript入口点文件的内容，其中突出显示了堆栈名称。*red italics*如果您的入口点文件使用的是不同语言，该文件看起来会很相似。
```
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 区域 将 AWS CDK 应用程序堆栈部署到哪里。有关区域代码的列表，请参阅[区域端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes)。
如果您未指定区域，则**AWS CDK 部署**操作将部署到您的 AWS CDK 代码中指定的区域。有关更多信息，请参阅《AWS Cloud Development Kit (AWS CDK) Developer Guide》**中的 [Environments](https://docs.aws.amazon.com/cdk/v2/guide/environments.html)。
对应的 UI：“配置”选项卡/**区域**
## Tags
(*CDKDeploy*/Configuration/**Tags**)
（可选）
指定要应用于 AWS CDK 应用程序堆栈中 AWS 资源的标签。标签应用于堆栈自身以及堆栈中的各个资源。有关标记的更多信息，请参阅《AWS Cloud Development Kit (AWS CDK) Developer Guide》**中的 [Tagging](https://docs.aws.amazon.com/cdk/v2/guide/tagging.html)。
**对应的用户界面：配置 tab/Advanced -可选/标签**
## Context
(*CDKDeploy*/Configuration/**Context**)
（可选）
以键值对的形式指定要与 AWS CDK 应用程序堆栈关联的上下文。有关上下文的更多信息，请参阅《AWS Cloud Development Kit (AWS CDK) Developer Guide》**中的 [Runtime contexts](https://docs.aws.amazon.com/cdk/v2/guide/context.html)。
**相应的 UI：配置 tab/Advanced -可选/上下文**
## CdkCliVersion
(*CDKDeploy*/Configuration/**CdkCliVersion**)
（可选）
此属性适用于 **AWS CDK 部署**操作的 1.0.13 或更高版本，以及 **AWS CDK 引导**操作的 1.0.8 或更高版本。
指定下列项之一：
+ 您希望此操作使用的 AWS Cloud Development Kit (AWS CDK) 命令行界面 (CLI)（也称为 AWS CDK 工具包）的完整版本。示例：`2.102.1`。在构建和部署您的应用程序时，请考虑指定完整版本，从而确保一致性和稳定性。
Or
+ `latest`。请考虑指定 `latest`，从而利用 CDK CLI 的最新功能和修复。
该操作会将指定版本（或最新版本）的 AWS CDK CLI 下载到 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 引导” 操作使用的 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 输出变量的更多信息，请参阅 *AWS Cloud Development Kit (AWS CDK) API 参考*中的`CfnOutput`[类 CfnOutput （构造）](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutput.html)中提供的构造文档。
相应的 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 等标准工具运行您的应用程序。如果操作未能使用这些工具成功运行您的应用程序，则合成将不会执行，操作将失败。要解决此问题，您可以在应用程序`cdk.json`的文件中指定成功运行应用程序所需的确切命令，然后使用不涉及**AWS CDK 部署**操作的方法合成应用程序。 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) Developer Guide》中的 [Deploying stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy)、[Synthesizing stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-synth) 和 [Skipping synthesis](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-nosynth)。
有关云程序集的信息，请参阅**《AWS Cloud Development Kit (AWS CDK) API Reference》中的 [Cloud Assembly](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) Developer Guide》**中的 [Bootstrapping](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 引导” 操作使用的 CDK CLI 版本](#cdk-boot-action-cdk-version)
+ [“AWS CDK bootstrap” 操作使用的运行时镜像](#cdk-boot-action-runtime)
+ [示例：引导应用程序 AWS CDK](cdk-boot-action-example-workflow.md)
+ [添加 “AWS CDK 引导” 操作](cdk-boot-action-add.md)
+ [“AWS CDK 引导”变量](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) Developer Guide》**的 [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) 主题中介绍的引导任务。
## “AWS CDK 引导” 操作使用的 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 引导”操作版本 | 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 月版映像中提供的最新工具。要升级操作，请在工作流定义文件中将其 `Identifier` 属性设置为 `aws/cdk-bootstrap@v2`。有关更多信息，请参阅 [“AWS CDK 部署”操作 YAML](cdk-dep-action-ref.md)。
| “AWS CDK 引导”操作版本 | 运行时环境映像 |
| --- | --- |
| 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 引导” 操作
按照以下说明，将 **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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 install”错误？](troubleshooting-workflows.md#troubleshooting-workflows-npm)，了解有关如何修复错误的信息。
------
#### [ YAML ]
**使用 YAML 编辑器添加 “AWS CDK bootstrap” 操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon CodeCatalyst**。
1. 搜索 **AWS CDK 引导**操作，然后选择 **\$1**，将操作添加到工作流图表中并打开其配置窗格。
1. 根据需求修改 YAML 代码中的属性。[“AWS CDK 引导”操作 YAML](cdk-boot-action-ref.md)中提供了每个可用属性的解释。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
**注意**
如果您的 **AWS CDK 引导**操作失败并出现 `npm install` 错误，请参阅[如何修复“npm install”错误？](troubleshooting-workflows.md#troubleshooting-workflows-npm)，了解有关如何修复错误的信息。
------
# “AWS CDK 引导”变量
**AWS CDK 引导**操作在运行时会生成并设置以下变量。这些变量被称为*预定义变量*。
有关在工作流中引用这些变量的信息，请参阅 [使用预定义变量](workflows-using-predefined-variables.md)。
| 键 | 值 |
| --- | --- |
| deployment-platform | 部署平台的名称。 硬编码为 `AWS:CloudFormation`。 |
| region | 在工作流程运行期间部署 AWS CDK 引导堆栈的区域代码。 AWS 区域 示例：`us-west-2` |
| stack-id | 已部署的 AWS CDK 引导堆栈的 Amazon 资源名称 (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**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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：配置 tab/Advanced -可选/计算类型**
## 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：配置 tab/Advanced -可选/计算舰队**
## 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 启动引导**过程之前，bootstrap 操作会将指定工件中的应用程序合成到 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`。如果您未指定构件，则该操作会合成模板，但不会将模板保存在构件中。考虑将合成的模板保存在构件中，以便保留其记录，供测试或故障排除之用。
**对应的用户界面：输出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 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*CDKBootstrapAction*/Environment/Connections/**Name**)
（如果包含 [Connections](#cdk.boot.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Role
(*CDKBootstrapAction*/Environment/Connections/**Role**)
（如果包含 [Connections](#cdk.boot.environment.connections)，则为必需）
指定引导操作用于访问 AWS 和添加**AWS CDK 引导堆**栈的 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**
## 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**)
（可选）
此属性适用于 **AWS CDK 部署**操作的 1.0.13 或更高版本，以及 **AWS CDK 引导**操作的 1.0.8 或更高版本。
指定下列项之一：
+ 您希望此操作使用的 AWS Cloud Development Kit (AWS CDK) 命令行界面 (CLI)（也称为 AWS CDK 工具包）的完整版本。示例：`2.102.1`。在构建和部署您的应用程序时，请考虑指定完整版本，从而确保一致性和稳定性。
Or
+ `latest`。请考虑指定 `latest`，从而利用 CDK CLI 的最新功能和修复。
该操作会将指定版本（或最新版本）的 AWS CDK CLI 下载到 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 引导” 操作使用的 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 发布**操作在 [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 发布**操作所需的权限和信任策略的更多信息，请参阅[“Amazon S3 发布”操作 YAML](s3-pub-action-ref.md) 中的 [Role](s3-pub-action-ref.md#s3.pub.environment.connections.role) 属性的说明。
```
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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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**)
（可选）
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（\$1）。不允许使用空格。不能使用引号以使变量名能够包含特殊字符和空格。
有关变量的更多信息（包括示例），请参阅[在工作流中使用变量](workflows-working-with-variables.md)。
对应的 UI：“输入”选项卡/**变量 – 可选**
## Environment
(*S3Publish*/**Environment**)
（必需）
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*S3Publish*/Environment/Connections/**Name**)
（如果包含 [Connections](#s3.pub.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Role
(*S3Publish*/Environment/Connections/**Role**)
（如果包含 [Connections](#s3.pub.environment.connections)，则为必需）
指定 A **mazon S3 发布操作用于访问 AWS 和将文件复制到 Amaz** on 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**
## Configuration
(*S3Publish*/**Configuration**)
（必需）
可在其中定义操作的配置属性的部分。
对应的 UI：**配置**选项卡
## SourcePath
(*S3Publish*/Configuration/**SourcePath**)
（必需）
指定要发布到 Amazon S3 的目录或文件的名称和路径。目录或文件可以位于源存储库或先前操作的构件中，并且相对于源存储库或构件根目录。
示例：
指定 `./myFolder/` 会将 `/myFolder` 的内容复制到 Amazon S3，并保留底层目录结构。
指定 `./myFolder/myfile.txt` *仅*将 `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 云 VPCs 中的目标和 AWS 账户 Amazon。要启用这些部署，必须设置 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 账户**。在此过程中，添加工作流访问 AWS 账户中的资源所需的 IAM 角色。有关更多信息，请参阅 [允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。
1. 在您的 CodeCatalyst 项目中，**创建一个包含步骤 1 中的 AWS 账户 s 和 IAM 角色之一的环境**。有关更多信息，请参阅 [创建环境](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)。
+ 包含您的工作流程操作需要访问的 IAM 角色的 AWS 账户连接 AWS。有关创建账户连接的信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。对于每个环境，最多使用一个账户连接。
**注意**
您可以在没有账户连接的情况下创建环境；但您稍后需添加该连接。
+ 以下 CodeCatalyst 角色之一：
+ **空间管理员**
+ **项目管理员**
+ **贡献者**
**注意**
如果您具有**贡献者**角色，则可以创建一个环境，但无法将该环境与 AWS 账户 连接关联。你需要请具有**空间管理员或**项目管理员****角色的人员将环境与 AWS 账户 连接关联。
有关权限和角色的更多信息，请参阅[向用户授予项目权限](projects-members.md)。
**创建环境**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**环境**。
1. 在**环境名称**中，输入一个名称，例如 **Production** 或 **Staging**。
1. 在**环境类型**中，选择下列选项之一：
+ **非生产** – 在将应用程序投入生产之前，可在其中测试应用程序以确保其按预期运行的环境。
+ **生产** – 一个公开可用的“实时”环境，用于托管您最终的应用程序。
如果您选择**生产**，则 UI 中与环境关联的所有操作旁边都会显示一个**生产**徽章。该徽章可帮助您快速查看哪些操作正在部署到生产中。除了徽章的外观外，生产环境和非生产环境之间没有区别。
1. （可选）在**描述**中，输入描述，例如 **Production environment for the hello-world app**。
1. 在**AWS 账户 连接中-可选**，选择要与此环境关联的 AWS 账户连接。分配了此环境的工作流操作将能够连接到关联的 AWS 账户。有关在中创建 AWS 账户 连接的更多信息 CodeCatalyst，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。
如果您要使用的 AWS 账户 连接未列出，则可能是因为您的项目中不允许使用该连接。有关更多信息，请参阅《A *mazon 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 连接的更多信息，请参阅《[亚马逊* CodeCatalyst 管理员指南》中的管理亚马逊*虚拟私有云](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html)。
如果您要使用的 VPC 连接未列出，则可能是因为它包含了您的项目中不允许的 AWS 账户 连接。有关更多信息，请参阅《A *mazon CodeCatalyst 管理员*指南》中的[配置受项目限制的账户连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
1. 选择 “**创建环境**”。 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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图中，选择环境支持的操作。有关更多信息，请参阅 [哪些操作支持在中显示其部署信息 CodeCatalyst？](deploy-environments.md#deploy-environments-supported-targets)。
1. 选择**配置**选项卡，然后在**环境**字段中指定信息，如下所示。
**环境**
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 VPC。
**注意**
如果默认 IAM 角色不具有操作所需的权限，则可以将操作配置为使用其他角色。有关更多信息，请参阅[更改操作的 IAM 角色](deploy-environments-switch-role.md)。
有关环境的更多信息，请参阅[部署到 AWS 账户 和 VPCs](deploy-environments.md)和[创建环境](deploy-environments-creating-environment.md)。
1. （可选）更改与操作关联的 IAM 角色。如果角色包含操作的一组错误权限，则可能需要更改角色。
要更改角色，请执行以下操作：
1. 在 W **hat's in*my-environment*？** 框，然后选择垂直省略号图标 (![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_cn/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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 选择**部署活动**选项卡，并确认部署的**状态**为**成功**。这表示工作流运行已成功部署您的应用程序资源。
1. 选择**部署目标**选项卡，并确认已显示您的应用程序资源。
# 将 VPC 与环境关联
在使用具有 VPC 连接的环境配置操作时，该操作将在连接到 VPC 的情况下运行，遵守网络规则并访问关联的 VPC 所指定的资源。一个或多个环境可使用同一 VPC 连接。
按照以下说明操作来将 VPC 连接与环境关联。
**将 VPC 连接与环境关联**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**环境**。
1. 选择您的环境（例如 `Production`）。
1. 选择**环境属性**选项卡。
1. 选择**管理 VPC 连接**，再选择所需的 VPC 连接，然后选择**确认**。这会将选定的 VPC 连接与此环境关联。
**注意**
如果您要使用的 VPC 连接未列出，则可能是因为该 AWS 账户 连接包含您的项目中不允许的连接。有关更多信息，请参阅《A *mazon CodeCatalyst 管理员*指南》中的[配置受项目限制的账户连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html)。
有关更多信息，请参阅《*CodeCatalyst 管理员指南》*中的 “[管理 Amazon 虚拟私有云](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html)”。
# 将 AWS 账户 与环境关联
按照以下说明将 AWS 账户 与环境相关联。当您将 AWS 账户 与环境关联时，分配给该环境的工作流操作将能够连接到该环境 AWS 账户。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。
**开始前的准备工作**
您需要以下项：
+ 包含您的工作流程操作需要访问的 IAM 角色的 AWS 账户连接 AWS。有关创建账户连接的信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。对于每个环境，最多使用一个账户连接。
+ 以下 CodeCatalyst 角色之一：**空间管理员**或**项目管理员**。有关更多信息，请参阅 [向用户授予项目权限](projects-members.md)。
**将 AWS 账户 与环境关联**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**环境**。
1. 选择您的环境（例如 `Production`）。
1. 选择**编辑环境**。
1. 在**环境属性**下的 **AWS 账户 连接 – 可选**下拉列表中，选择所需的 AWS 账户。
如果您要使用的 AWS 账户 连接未列出，则可能是因为您的项目中不允许使用该连接。有关更多信息，请参阅《A *mazon 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择代表要更新其 IAM 角色的操作的框。
1. 选择**配置**选项卡。
1. 在 W **hat's in*my-environment*？** 框中，选择垂直省略号图标 (![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/elipsis.png))。
1. 选择**切换角色**。
1. 在**切换角色**对话框的 **IAM 角色**下拉列表中，选择您希望该操作使用的 IAM 角色。此角色将覆盖环境中指定的默认 IAM 角色。如果要使用的角色不在列表中，请确保已将它添加到空间。有关更多信息，请参阅 [将 IAM 角色添加到账户连接](ipa-connect-account-addroles.md)。
所选角色现在出现在 W **hat's in*my-environment*？** 框以及 “**在工作流程中定义”** 徽章。此角色还显示在工作流定义文件的 `Connections:` 部分中。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**向操作分配其他 IAM 角色（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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_cn/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 部署” 操作中显示应用程序网址](#deploy-app-url-cdk)
+ [在 “部署 CloudFormation 堆栈” 操作中显示应用程序 URL](#deploy-app-url-cfn)
+ [在所有其他操作中显示应用程序 URL](#deploy-app-url-other)
配置完 URL 后，请按照以下说明操作来验证它是否按预期显示：
+ [验证是否已添加应用程序 URL](#deploy-app-url-verify)
**在 “AWS CDK 部署” 操作中显示应用程序网址**
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',
});
...
}
}
```
有关该`CfnOutput`构造的更多信息，请参阅 *AWS Cloud Development Kit (AWS CDK) API 参考 CfnOutputProps*中的[接口](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutputProps.html)。
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 操作或操作**，请执行以下操作以显示应用程序网址。
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在以下情况下，目标可能会过时：
+ 您删除了已部署到目标的工作流。
+ 您更改了要部署到的堆栈或集群。
+ 您在 AWS 控制台中从或 Amazon ECS 服务中删除了堆栈 CloudFormation 或集群。
**移除部署目标**
1. 打开 CodeCatalyst 控制台，[网址为 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**运行**。
1. 选择已部署应用程序的工作流运行。
1. 在工作流图中，选择要查看其日志的操作。
1. 选择**日志**选项卡并展开各个部分以显示日志消息。
1. 要查看更多日志，请选择 “**摘要**” 选项卡，然后选择 “**查看于” CloudFormation（如果可用），在**那里查看更多日志。您可能需要登录 AWS。
**查看从环境开始的部署操作的日志**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**环境**。
1. 选择已在其中部署堆栈的环境，例如 `Production`。
1. 选择**部署活动**可查看堆栈的部署历史记录、部署状态（例如，**成功**或**失败**）以及其他与部署相关的信息。
1. 选择**部署目标**可查看有关已部署到环境中的堆栈、集群或其他目标的信息。您可以查看堆栈名称、区域、提供商和标识符等信息。
**从操作开始查看部署信息**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**运行**。
# 使用触发器自动启动工作流运行
您可以使用 CodeCatalyst 工作流程触发器自动启动 Amazon 工作流程。
*工作流触发器*简称*触发器*，使您可以在发生某些事件（例如代码推送）时自动启动工作流运行。您可能需要配置触发器，使软件开发人员不必通过 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)
+ [示例：一个简单的“push to main”触发器](#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)
+ [示例：带有拉取、分支和“CLOSED”事件的触发器](#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 启动工作流程运行。`main`
再举一个例子，如果您将提交推送到`feature-branch-123`，则使用工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。`feature-branch-123`
```
Triggers:
- Type: PUSH
```
**注意**
如果您希望只有在推送到 `main` 时才启动工作流运行，请参阅[示例：一个简单的“push to main”触发器](#workflows-add-trigger-examples-push-main)。
## 示例：一个简单的“push to main”触发器
以下示例显示了一个触发器，在代码被推送到源存储库中的 `main` 分支（而且*仅在*推送到 `main` 分支）时，该触发器将启动工作流运行。
```
Triggers:
- Type: PUSH
Branches:
- main
```
## 示例：一个简单的拉取请求触发器
以下示例显示了一个触发器，在源存储库中创建或修订了任何拉取请求时，该触发器将启动工作流运行。
*激活此触发器后，使用工作流程定义文件和您要提取的分支（即源分支）中的其他源文件 CodeCatalyst 启动工作流程运行。*
例如，如果您使用名为的源分支`feature-123`和名为的目标分支创建拉取请求`main`，则使用工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。`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）启动工作流运行的触发器。
激活此触发器后，使用`main`分支中的文件 CodeCatalyst 启动工作流程运行，然后为以开头的每个分支开始额外运行`release-`。
例如，如果您的源存储库中有名为`main``release-v1``bugfix-1`、、和`bugfix-2`的分支，则会 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
```
## 示例：带有拉取、分支和“CLOSED”事件的触发器
以下示例演示了一个触发器，每当有人对以 `main` 开头的分支关闭拉取请求时，该触发器就会启动工作流运行。
在本示例中：
+ 当您关闭对以 `main` 开头的目标分支的拉取请求时，就会自动启动工作流运行，该工作流将使用（现已关闭）源分支中的工作流定义文件和其他源文件。
+ 如果您已将源存储库配置为在合并拉取请求后自动删除分支，则这些分支将永远没有机会进入 `CLOSED` 状态。这意味着合并的分支不会激活拉取请求 `CLOSED` 触发器。在这种情况下，激活 `CLOSED` 触发器的唯一方法是关闭拉取请求而不合并。
```
Triggers:
- Type: PULLREQUEST
Branches:
- main.*
Events:
- CLOSED
```
## 示例：带有推送、分支和文件的触发器
以下示例演示了一个触发器，每当对 `main` 分支上的 `filename.txt` 文件或 `src` 目录中的任何文件进行更改时，该触发器就会启动工作流运行。
激活此触发器后，使用`main`分支中的工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。
```
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：**对于推送和拉取请求触发器，如果要指定分支，您必须在触发器配置中指定目标（即“至”）分支。切勿指定源（即“自”）分支。
在以下示例中，从任何分支推送至 `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` 中的文件运行。（但是，如果您在 `main` 中创建 `test` 分支，则工作流将使用 `test` 中的文件运行。） 请查看**准则 3** 以了解原因。
# 添加触发器到工作流
按照以下说明在您的 Amazon CodeCatalyst 工作流程中添加推送、拉取或计划触发器。
有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。
------
#### [ Visual ]
**添加触发器（可视化编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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` 事件的行为不太好说明，最好通过一个例子来理解。请参阅[示例：带有拉取、分支和“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 表达式，用于描述您希望何时执行计划的工作流运行。
中的 Cron 表达式 CodeCatalyst 使用以下六字段语法，其中每个字段用空格分隔：
*minutes* *hours* *days-of-month* *month* *days-of-week* *year*
**cron 表达式示例**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/workflows-add-trigger-add.html)
在中指定 cron 表达式时 CodeCatalyst，请务必遵循以下准则：
+ 为每个 `SCHEDULE` 触发器指定一个 cron 表达式。
+ 在 YAML 编辑器中，将 cron 表达式用双引号（`"`）括起来。
+ 使用协调世界时（UTC）格式指定时间。不支持其他时区。
+ 两次运行之间应至少配置 30 分钟的运行间隔。不支持更快的节奏。
+ 指定*days-of-month*或字*days-of-week*段，但不能同时指定两者。如果您在其中一个字段中指定值或星号（`*`），则必须在另一个字段中使用问号（`?`）。星号表示“全部”，问号表示“任何”。
有关 cron 表达式的更多示例以及有关通配符（如`?`、和）的信息 `*``L`，请参阅《*亚马逊 EventBridge *用户指南[》中的 Cron 表达式参考](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html)。 EventBridge 和中的 Cron 表达式 CodeCatalyst 的工作方式完全相同。
有关计划触发器的示例，请参阅[示例：工作流中的触发器](workflows-add-trigger-examples.md)。
**分支**和**分支模式**
（可选）
指定触发器监控的源存储库中的分支，以便知道何时启动工作流运行。您可以使用正则表达式模式来定义分支名称。例如，使用 `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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 根据以下示例的指导，添加 `Triggers` 部分和底层属性。有关更多信息，请参阅 [工作流 YAML 定义](workflow-reference.md)中的[Triggers](workflow-reference.md#triggers-reference)。
代码推送触发器类似于下文：
```
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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中选择**源**框。
1. 在**触发器**下，选择垃圾桶图标以将 `Triggers` 部分从工作流中删除。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**删除“触发器”部分（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 找到 `Triggers` 部分并将其删除。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
# 停止工作流运行
使用以下过程停止正在进行的工作流运行。如果您意外启动了运行，则可能需要停止运行。
停止工作流程运行时， CodeCatalyst 等待正在进行的操作完成，然后才会在控制台中将运行标记为 “**已停止**” CodeCatalyst 。任何还没有机会启动的操作都不会启动，而且会被标记为**已放弃**。
**注意**
如果运行已排队（也就是说，没有正在进行的操作），则运行将立即停止。
有关工作流运行的更多信息，请参阅[运行工作流](workflows-working-runs.md)。
**停止工作流运行**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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)。
## 我可以设置阶段门与其他操作并行运行吗？
不能。阶段门只能在操作之前或之后运行。有关更多信息，请参阅[按顺序执行阶段门和操作](workflows-gates-depends-on.md)。
## 我能否使用阶段门来阻止工作流运行的启动？
可以，有资格要求。
您可以阻止工作流运行去*执行任务*，这与阻止其*启动*略有不同。
要阻止工作流执行任务，请在工作流中的第一个操作之前添加阶段门。在这种情况下，工作流运行*将启动*，这意味着它将下载您的源存储库文件，但在阶段门解锁之前，它无法执行任务。
**注意**
在启动后被阶段门阻止的工作流仍计入*每个空间的并行工作流运行最大数量*配额和其他配额。为确保您不会超过工作流配额，请考虑使用工作流触发器来有条件地启动工作流，而不是使用阶段门。还可以考虑使用拉取请求批准规则代替阶段门。有关配额、触发器和拉取请求批准规则的更多信息，请参阅 [中的工作流程配额 CodeCatalyst](workflows-quotas.md)、[使用触发器自动启动工作流运行](workflows-add-trigger.md)和[管理将拉取请求与审批规则合并的要求](source-pull-requests-approval-rules.md)。
## 阶段门的限制
阶段门具有以下限制：
+ 阶段门不能与计算共享功能结合使用。有关此特征的更多信息，请参阅[跨操作共享计算](compute-sharing.md)。
+ 阶段门不能在操作组中使用。有关操作组的更多信息，请参阅[将操作分组为操作组](workflows-group-actions.md)。
# 向工作流添加阶段门
在 Amazon CodeCatalyst 中，您可以向工作流添加阶段门，让工作流在满足某些条件的情况下才能运行。按照以下说明向工作流添加阶段门。
有关阶段门的更多信息，请参阅[用阶段门控制工作流运行](workflows-gates.md)。
**添加和配置阶段门**
1. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左侧选择**阶段门**。
1. 在阶段门目录中，搜索阶段门，然后选择加号（**\$1**），将该阶段门添加到您的工作流中。
1. 配置阶段门。选择**可视化**以使用可视化编辑器，或者选择 **YAML** 以使用 YAML 编辑器。有关详细说明，请参阅：
+ [添加“批准”阶段门](workflows-approval-add.md)
1. （可选）选择**验证**以确保 YAML 代码有效。
1. 选择**提交**以提交您的更改。
# 按顺序执行阶段门和操作
在 Amazon CodeCatalyst 中，您可以将某个阶段门设置为在工作流操作、操作组或阶段门之前或之后运行。例如，您可以将 `Approval` 阶段门设置为在 `Deploy` 操作之前运行。在这种情况下，`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** 的情况下）。
## 何时使用“批准”阶段门
通常，在工作流将应用程序和其他资源部署到生产服务器或任何必须验证质量标准的环境中时，您可以在工作流中使用**批准**阶段门。通过在部署到生产环境之前放置阶段门，您向审阅者提供了机会，在新的软件修订版面向公众发布之前对其进行验证。
## 谁可以提供批准？
任何用户，只要是您的项目的成员且具有**贡献者**或**项目管理员**角色，就可以提供批准。具有**空间管理员**角色且属于您的项目空间的用户也可以提供批准。
**注意**
具有**审阅者**角色的用户无法提供批准。
## 如何通知用户需要该用户的批准？
要通知用户需要该用户的批准，您必须：
+ 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_cn/codecatalyst/latest/userguide/images/flows/runmode-queued-ma.png)
**图 2**：“取代运行模式”和**批准**阶段门
![\[“批准”阶段门如何与“取代运行模式”配合使用\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/runmode-superseded-ma.png)
**图 3**：“并行运行模式”和**批准**阶段门
![\[“批准”阶段门如何与“并行运行模式”配合使用\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/runmode-parallel-ma.png)
# 示例：“批准”阶段门
以下示例说明如何在名为 `Staging` 和 `Production` 的两个操作之间添加一个名为 `Approval_01` 的**批准**阶段门。`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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 在左上角，选择**阶段门**。
1. 在**阶段门**目录的**批准**中，选择加号（**\$1**）。
1. 选择**输入**，然后在**依赖于**字段中执行以下操作。
指定必须成功运行才能使该阶段门运行的操作、操作组或阶段门。默认情况下，当您向工作流添加阶段门时，阶段门的设置取决于工作流中的最后一个操作。如果删除此属性，则阶段门将不依赖于任何设置，并且将首先运行，然后再执行其他操作。
**注意**
阶段门必须配置为在操作、操作组或阶段门之前或之后运行。阶段门无法设置为与其他操作、操作组和阶段门并行运行。
有关**依赖于**功能的更多信息，请参阅 [按顺序执行阶段门和操作](workflows-gates-depends-on.md)。
1. 选择**配置**选项卡。
1. 在**阶段门名称**字段中，执行以下操作。
指定要为阶段门指定的名称。在工作流中，所有阶段门名称都必须唯一。阶段门名称仅限字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（\$1）。不允许使用空格。您不能使用引号在阶段门名称中启用特殊字符和空格。
1. （可选）在**批准数**字段中，执行以下操作。
指定解锁**批准**阶段门所需的最小审批数。最小值为 `1`。最大值为 `2`。如果省略，则默认值为 `1`。
**注意**
如果要省略 `ApprovalsRequired` 属性，请从工作流定义文件中删除该阶段门的 `Configuration` 部分。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**向工作流添加“批准”阶段门（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 根据以下示例的指导，添加 `Approval` 部分和底层属性。有关更多信息，请参阅 [工作流 YAML 定义](workflow-reference.md) 中的 [“批准”阶段门 YAML](approval-ref.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. 选择**保存**。
# 批准或拒绝工作流运行
包含**批准**阶段门的工作流运行将需要得到批准或拒绝。用户可以通过以下方式提供批准或拒绝：
+ 控制 CodeCatalyst 台
+ 团队成员提供的链接
+ 自动发送的 Slack 通知
在用户提供了批准或拒绝后，此决定无法撤消。
**注意**
只有某些用户可以批准或拒绝工作流运行。有关更多信息，请参阅[谁可以提供批准？](workflows-approval.md#workflows-approval-who)。
**开始前的准备工作**
确保已在工作流中添加了**批准**阶段门。有关更多信息，请参阅 [添加“批准”阶段门](workflows-approval-add.md)。
**要批准或拒绝工作流程，请从 CodeCatalyst 控制台开始运行**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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_cn/codecatalyst/latest/userguide/images/flows/RunMode-Queued.png)
在以下情况下使用排队运行模式：
+ **您希望在功能和运行之间保持一对一的关系，在使用取代模式时，这些功能可能会被分组**。例如，当您在提交 1 中合并功能 1 时，运行 1 会启动；当您在提交 2 中合并功能 2 时，运行 2 会启动，依此类推。如果您使用取代模式而不是排队模式，则您的功能（和提交）将一起分组到运行中，并会取代其他运行。
+ **您需要避免使用并行模式时可能出现的争用情况和意外问题**。例如，如果有两位软件开发人员 Wang 和 Saanvi，他们在大致相同的时间启动工作流运行以部署到 Amazon ECS 集群，那么 Wang 的运行可能会在集群上启动集成测试，而 Saanvi 的运行会向集群部署新的应用程序代码，从而导致 Wang 的测试失败或测试了错误的代码。再举一个例子，您的目标可能没有锁定机制，在这种情况下，两次运行可能会以意想不到的方式覆盖彼此的更改。
+ **您想限制 CodeCatalyst 用于处理运行的计算资源上的负载**。例如，如果工作流中有三个操作，则您最多可能会同时进行三个运行。通过对一次可以进行的运行数施加限制，可以使运行吞吐量更具可预测性。
+ **您想限制工作流向第三方服务发出的请求数量**。例如，您的工作流可能有一个构建操作，其中包括从 Docker Hub 提取映像的说明。[Docker Hub 对每个账户每小时可以发出的拉取请求数量](https://www.docker.com/increase-rate-limits)有一定的限制，在超过限制时会被阻止。使用排队运行模式可降低运行吞吐量，这样就可以减少每小时向 Docker Hub 发出的请求数，从而避免可能出现的锁定情况以及导致的构建和运行失败。
**最大队列大小**：50
有关**最大队列大小**的注意事项：
+ 最大队列大小是指在工作流的*所有队列*中，允许的运行的最大数量。
+ 如果队列中的运行超过 50 个，则 CodeCatalyst 会丢弃第 51 个及随后的运行。
**失败行为**：
如果某个运行在操作处理时变得没有响应，则其后面的运行将暂停在队列中，直到操作超时。操作在 1 小时后超时。
如果运行在操作内部失败，则允许排队在其后面的第一个运行继续进行。
## 关于取代运行模式
*取代运行模式*与*排队运行模式*大致相同，不同之处在于：
+ 如果排队的运行赶上了队列中的另一个运行，则后一个运行将取代（接管）先前的运行，而先前的运行将被取消并标记为“取代”。
+ 作为第一个要点中描述的行为的结果，使用取代运行模式时，队列只能包含一个运行。
以[Figure 1](#figure-1-workflow-queued-run-mode) 中的工作流为指南，对此工作流应用取代运行模式将导致以下结果：
+ **Run-7g777** 将取代队列中的另外两个运行，并且将是 **Queue \$11** 中唯一剩下的运行。**Run-6f666** 和 **Run-5e555** 将被取消。
+ **Run-3c333** 将取代 **Run-2b222**，成为 **Queue \$12** 中唯一剩下的运行。**Run-2b222** 将被取消。
在有以下需求时，请使用取代运行模式：
+ 比排队模式更好的吞吐量
+ 相比排队模式向第三方服务发出更少的请求；如果第三方服务有速率限制（例如 Docker Hub），这将非常有利
## 关于并行运行模式
在*并行运行模式*中，运行是相互独立的，不会等待其他运行完成后才开始。其中没有队列，运行吞吐量仅受工作流内部的操作完成速度的限制。
在开发环境中使用并行运行模式，每个用户都有自己的功能分支，并部署到不与其他用户共享的目标。
**重要**
如果您有多个用户可以部署到的共享目标，例如生产环境中的 Lambda 函数，请不要使用并行模式，因为可能会导致争用情况。当并行工作流运行尝试同时更改共享资源时，就会出现*争用情况*，导致不可预测的结果。
**最大并行运行数量**：每个 CodeCatalyst 空间 1000 个
## 配置运行模式
您可以将运行设置为排队、取代或并行模式。默认使用排队模式。
当您将运行从排队或取代模式更改为并行模式时，CodeCatalyst 会取消排队中的运行，并使当前由操作处理的运行能够完成，而不是取消。
当您将运行从并行模式更改为排队或取代模式时，CodeCatalyst 会让所有当前正在进行的并行运行完成。将运行更改为排队或取代模式后开始的任何运行都使用新模式。
------
#### [ Visual ]
**使用可视化编辑器更改运行模式**
1. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
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. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 添加 `RunMode` 属性，如下所示：
```
Name: Workflow_6d39
SchemaVersion: "1.0"
RunMode: QUEUED|SUPERSEDED|PARALLEL
```
有关更多信息，请参阅[工作流 YAML 定义](workflow-reference.md)的[顶级属性](workflow-reference.md#workflow.top.level)部分中对 `RunMode` 属性的说明。
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` 和 `cacheKey2` 的多个缓存进行缓存的 YAML 代码片段示例。
```
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 应用缓存访问限制，以确保一个工作流程中的操作无法修改其他工作流程中的缓存。这样可以防止各个工作流收到其他工作流中可能推送的错误数据，影响其构建或部署。限制是通过缓存范围来强制执行的，该范围将缓存隔离到每个工作流和分支对。例如，分支 `feature-A` 中的 `workflow-A` 与同级分支 `feature-B` 中的 `workflow-A` 具有不同的文件缓存。
当工作流查找指定的文件缓存但无法找到时，就会发生缓存未命中。出现这种情况可能有多种原因，例如创建了新分支或引用了新缓存但新缓存尚未创建时。这种情况也可能发生在缓存过期时，默认情况下，缓存在上次使用的 14 天后过期。为了减少缓存未命中率并提高缓存命中率， CodeCatalyst 支持后备缓存。回退缓存是备用缓存，它提供了恢复部分缓存的机会，部分缓存可能是某个缓存的较旧版本。在恢复缓存时，首先在 `FileCaching` 下搜索属性名称的匹配，如果未找到，则评估 `RestoreKeys`。如果属性名称和所有 `RestoreKeys` 均出现缓存未命中，则工作流将继续运行，因为缓存是尽力提供服务，并不提供保证。
## 创建缓存
您可以按照以下说明向工作流添加缓存。
------
#### [ Visual ]
**使用可视化编辑器添加缓存**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择要添加缓存的操作。
1. 选择**配置**。
1. 在**文件缓存 – 可选**下，选择**添加缓存**，然后在字段中输入信息，如下所示：
**键**
指定主缓存属性的名称。缓存属性名称在您的工作流内必须是唯一的。每个操作在 `FileCaching` 中最多可以有五个条目。
**路径**
为您的缓存指定关联路径。
**恢复键 – 可选**
指定在找不到主缓存属性时用作回退手段的恢复键。恢复键名称在您的工作流内必须是唯一的。每个缓存在 `RestoreKeys` 中最多可以有五个条目。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器添加缓存**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 在**工作流**下，选择**运行**。
此时将显示项目中所有存储库的所有分支中的所有工作流的所有运行。
页面中包括以下列：
+ **ID** – 运行的唯一标识符。选择运行 ID 链接以查看有关运行的详细信息。
+ **状态** – 工作流运行的处理状态。有关运行状态的更多信息，请参阅[工作流运行状态](workflows-view-run-status.md)。
+ **触发器** – 启动工作流运行的人员、提交、拉取请求（PR，Pull Request）或计划。有关更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。
+ **工作流** – 启动运行的工作流的名称，以及工作流定义文件所在的源存储库和分支。您可能需要展开列宽才能看到此信息。
**注意**
如果此列设置为**不可用**，则通常是因为关联的工作流已删除或已移动。
+ **开始时间** – 工作流运行的启动时间。
+ **持续时间** – 处理工作流运行所花费的时间。持续时间过长或过短都可能表示存在问题。
+ **结束时间** – 工作流运行的结束时间。
## 查看特定工作流所有运行的状态和详细信息
您可能需要查看与特定工作流关联的所有运行的状态和详细信息，以查看是否有任何运行在工作流中造成瓶颈，或者查看哪些运行当前正在进行或已完成。
**查看特定工作流的所有运行的状态和详细信息**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 在工作流的名称下，选择**运行**。
将显示与所选工作流关联的运行。
此页面分为两个部分：
+ **活跃运行** – 显示正在进行的运行。这些运行将处于以下状态：**进行中**。
+ **运行历史记录** – 显示已完成（即不在进行中）的运行。
有关运行状态的更多信息，请参阅[工作流运行状态](workflows-view-run-status.md)。
## 在工作流图表中查看工作流的运行
当多个运行一起在工作流中执行时，您可以查看工作流中所有运行的状态。运行结果显示在工作流图表中（而不是列表视图）。图表直观地显示哪些运行正在由哪些操作处理，哪些运行正在队列中等待。
**查看多个运行在工作流中一起执行的状态**
**注意**
仅当您的工作流使用排队或取代运行模式时，此过程才适用。有关更多信息，请参阅 [配置运行的排队行为](workflows-configure-runs.md)。
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 行动](#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 bootstrap**
此操作会预置部署 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 工作流程中运行 GitHub 操作。*CodeCatalyst*有关更多信息，请参阅 [使用工作流调用 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 实验室操作*是 Amazon Labs 的一部分，Amazon CodeCatalyst Labs 是实验性应用程序的试验场。 CodeCatalyst 已经开发了实验室操作来展示与 AWS 服务的集成。
以下 CodeCatalyst 实验室操作可用：
+ **部署到 AWS Amplify 主机**
该操作会将应用程序部署到 Amplify Hosting。
+ **部署到 AWS App Runner**
此操作会将源映像存储库中的最新映像部署到 App Runner。
+ **部署到亚马逊 CloudFront 和亚马逊 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 安全软件进行扫描**
此操作会创建已配置代码路径的 zip 存档，并使用 “ CodeGuru 安全” 来运行代码扫描。
+ **Terraform Community Edition**
此操作会运行 Terraform Community Edition 的 `plan` 和 `apply` 操作。
CodeCatalyst 实验室操作的文档可在每个操作的自述文件中找到。
有关向工作流程添加 CodeCatalyst 实验室操作和查看其自述文件的信息，请参阅[添加操作到工作流](workflows-add-action.md)。
### GitHub 行动
Acti *GitHub on* 很像一个[CodeCatalyst 动作](#workflows-actions-types-cc)，不同之处在于它是为与 GitHub 工作流程一起使用而开发的。有关 GitHub 操作的详细信息，请参阅[GitHub 操作](https://docs.github.com/en/actions)文档。
在 CodeCatalyst 工作流程中，您可以将 GitHub CodeCatalyst 操作与原生操作一起使用。
为方便起见， CodeCatalyst 控制台提供了对多个常用 GitHub操作的访问权限。您也可以使用 [GitHub Marketplace](https://github.com/marketplace/actions) 中列出的任何 GitHub 操作（但有一些限制）。
操作文档可在每个 GitHub 操作的自述文件中找到。
有关更多信息，请参阅 [与 GitHub 操作集成](integrations-github-actions.md)。
### 第三方操作
*第三方操作*是由第三方供应商创作并在 CodeCatalyst 控制台中提供的操作。第三方操作的示例包括分别由 **Mend 和 Sonar 编写的 “修复 SCA**” 和 “**SonarCloud 扫描**” 操作。
第三方操作的文档可在每个操作的自述文件中找到。第三方供应商也可能提供其它文档。
有关向工作流中添加第三方操作和查看操作自述文件的信息，请参阅[添加操作到工作流](workflows-add-action.md)。
# 添加操作到工作流
按照以下说明向工作流添加操作，然后进行配置。
**添加和配置操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 动作有 b **y AWS** 标签。
+ CodeCatalyst 实验室操作带有 “**按 CodeCatalyst 实验室**” 标签。
+ 第三方操作有 b **y *vendor*** 标签，其中*vendor*是第三方供应商的名称。
+ 选择**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)
+ [添加“部署到 Amazon ECS”操作](deploy-action-ecs-adding.md)
+ [添加“部署到 Kubernetes 集群”操作](deploy-action-eks-adding.md)
+ [添加 “部署 CloudFormation 堆栈” 操作](deploy-action-cfn-adding.md)
+ [添加 “AWS CDK 部署” 操作](cdk-dep-action-add.md)
+ [添加 “AWS CDK 引导” 操作](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，在要删除的操作中，选择垂直省略号（![\[Ellipsis.\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/images/flows/elipsis.png)）图标，然后选择**删除**。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器删除操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 找到 YAML 中包含要删除的操作的部分。
选择该部分并按键盘上的 Delete 键。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
# 开发自定义操作
您可以使用动作开发套件 (ADK) 开发自定义 CodeCatalyst 操作以在工作流程中使用。然后，您可以将该操作发布到 CodeCatalyst 操作目录，以便其他 CodeCatalyst 用户可以在其工作流程中查看和使用它。
**开发、测试和发布操作（高级任务）**
1. 安装开发操作所需的工具和程序包。
1. 创建 CodeCatalyst 存储库来存储您的操作代码。
1. 初始化操作。这会列出操作所需的源文件，包括您可以用自己的代码更新的操作定义文件（`action.yml`）。
1. 引导操作代码以获取构建、测试和发布操作项目所需的工具和库。
1. 在本地计算机上生成操作，然后将更改推送到存储 CodeCatalyst库。
1. 在本地使用单元测试测试操作，然后在中运行 ADK 生成的工作流程。 CodeCatalyst
1. 在 CodeCatalyst 控制台中选择 “**发布” 按钮，将 CodeCatalyst 操作发布**到操作目录。
有关详细步骤，请参阅 [Amazon Acti CodeCatalyst on 开发套件开发者指南](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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)。有关更多信息，请参阅[工作流 YAML 定义](workflow-reference.md)的[操作](workflow-reference.md#actions-reference)中对 `action-group-name` 属性的说明。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择将依赖于其他操作的操作。
1. 选择**输入**选项卡。
1. 在**依赖于 – 可选**中，执行以下操作：
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](workflows-depends-on.md)。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器设置依赖关系**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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
```
## 示例：输入由其他操作生成的构件
以下示例向您展示了如何在 `BuildActionA` 中输出名为 `ARTIFACT4` 的构件并将其输入到 `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:
```
## 示例：引用多个构件中的文件
以下示例向您展示了如何在 `BuildActionC` 中输出名为 `ART5` 和 `ART6` 的两个构件，然后在 `BuildActionD` 中（位于 `Steps` 下）引用名为 `file5.txt`（在构件 `ART5` 中）和 `file6.txt`（在构件 `ART6` 中）的两个文件。
**注意**
有关引用文件的更多信息，请参阅[在构件中引用文件](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
```
## 示例：在单个构件中引用文件
以下示例向您展示了如何在 `BuildActionE` 中输出名为 `ART7` 的构件，然后在 `BuildActionF` 中（位于 `Steps` 下）引用 `file7.txt`（在构件 `ART7` 中）文件。
请注意，引用并不像在`build-output`目录前面那样需要前`$CATALYST_SOURCE_DIR_`*artifact-name*缀[示例：引用多个构件中的文件](#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
以下示例向您展示了如何在 `BuildActionG` 中输出名为 `ART8` 的构件，然后在 `BuildActionH` 中（位于 `Steps` 下）引用 `file8.txt`（在构件 `ART8` 中）文件。
请注意引用是如何需要`$CATALYST_SOURCE_DIR_`*artifact-name*前缀的，就像在中一样[示例：引用多个构件中的文件](#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`、`ActionI` 中输出名为 `ART9` 的构件，然后在 `ActionJ` 中引用 `file9.txt`（在构件 `ART9` 中）。
有关引用文件的更多信息，请参阅[在构件中引用文件](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择将生成构件的操作。
1. 选择**输出**选项卡。
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`。
+ 要指定所有文件，请使用 `"**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `directory` 的目录中的所有文件和目录，请使用 `"directory/**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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_cn/codecatalyst/latest/userguide/workflows-working-artifacts-refer-files.html)
有关示例，请参阅 [构件示例](workflows-working-artifacts-ex.md)。
**注意**
在以下情况下，你可以省略*artifact-path*，只指定相对于工件根目录的文件路径：
包含引用的操作仅包含 `Inputs` 下的一项（例如，它包含一个输入构件而不包含任何源）。
您要引用的文件位于主输入中。*主输入*要么是 `WorkflowSource`，要么是列出的第一个输入构件（如果没有 `WorkflowSource`）。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
# 下载构件
您可以下载由您的 Amazon CodeCatalyst 工作流操作生成的构件，并进行检查以排除故障。您可以下载两种类型的构件：
+ **源构件** – 包含运行开始时存在的源存储库内容的快照的构件。
+ **工作流构件** – 在工作流配置文件的 `Outputs` 属性中定义的构件。
**下载工作流输出的构件**
1. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 找到要编辑其版本的操作。
1. 找到操作的 `Identifier` 属性，然后将版本设置为下列项之一：
+ actionidentifier @v *major* — 使用此语法让工作流程使用特定的主要版本，并允许自动选择最新的次要版本和补丁版本。
+ 操作标识符 @v *major*。 *minor*— 使用此语法让工作流程使用特定的次要版本，并允许自动选择最新的补丁版本。
+ 操作标识符 @v *major*。 *minor*。 *patch*— 使用此语法让工作流程使用特定的补丁版本。
**注意**
如果您不确定可用的版本，请参阅[列出可用的操作版本](workflows-action-versions-determine.md)。
**注意**
不能省略主要版本。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
# 列出可用的操作版本
按照以下说明来确定哪些版本的操作可供您在工作流中使用。
------
#### [ Visual ]
**确定哪些操作版本可用**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 找到要查看其版本的操作：
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择任意工作流的名称，或创建一个工作流。有关创建工作流的信息，请参阅[创建工作流](workflows-create-workflow.md)。
1. 选择**编辑**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 在下拉列表中，选择 CodeCatalyst要查看的 **Amazon** CodeCatalyst、 CodeCatalyst Labs 和第三方操作，或者选择**GitHub**查看精选 GitHub操作。
1. 搜索操作，然后选择其名称。请不要选择加号（**\$1**）。
有关该操作的详细信息将显示。
1. 在右上角附近的操作详细信息对话框中，选择**版本**下拉列表以查看该操作的可用版本列表。
------
#### [ YAML ]
*不可用。选择“可视化”以查看可视化编辑器说明。*
------
# 查看操作的源代码
您可以查看操作的源代码，以确保其中不包含危险代码、安全漏洞或其他缺陷。
按照以下说明查看[CodeCatalyst](workflows-actions.md#workflows-actions-types-cc)、[CodeCatalyst Labs](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 找到要查看其代码的操作：
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择任意工作流的名称，或创建一个工作流。有关创建工作流的信息，请参阅[创建工作流](workflows-create-workflow.md)。
1. 选择**编辑**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 在下拉列表中，选择 CodeCatalyst要查看的 **Amazon** CodeCatalyst、 CodeCatalyst Labs 和第三方操作。
1. 搜索操作，然后选择其名称。请不要选择加号（**\$1**）。
有关该操作的详细信息将显示。
1. 在靠近底部的操作详细信息对话框中，选择**下载**。
出现的页面中显示操作源代码所在的 Amazon S3 存储桶。有关 Amazon S3 的信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[什么是 Amazon S3？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)
1. 检查代码，确保代码符合您对质量和安全性的要求。
# 与 GitHub 操作集成
Acti *GitHub on* 很像一个[CodeCatalyst 动作](workflows-actions.md#workflows-actions-types-cc)，不同之处在于它是为与 GitHub 工作流程一起使用而开发的。有关 GitHub 操作的详细信息，请参阅[GitHub 操作](https://docs.github.com/en/actions)文档。
在 CodeCatalyst 工作流程中，您可以将 GitHub CodeCatalyst 操作与原生操作一起使用。
有两种方法可以向 CodeCatalyst 工作流程中添加 GitHub 操作：
+ 您可以从 CodeCatalyst 控制台的精选列表中选择 “ GitHub 操作”。有几种流行的 GitHub 操作可供选择。有关更多信息，请参阅 [添加精心策划 GitHub 的动作](integrations-github-action-add-curated.md)。
+ 如果您要使用的 GitHub 操作在 CodeCatalyst 控制台中不可用，则可以使用 “**GitHub 操作” 操作**将其添加。
***GitHub 操作操作***是一种封装*CodeCatalyst 动作*并使其与 CodeCatalyst 工作流程兼容的 GitHub 动作。
以下是封装 Su [per-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 操作操作**（由标识`aws/github-actions-runner@v1`）封装了 Super-Linter 操作（由标识`github/super-linter@v4`），使其在工作流程中起作用。 CodeCatalyst
有关更多信息，请参阅 [添加 “GitHub 操作” 操作](integrations-github-action-add.md)。
所有 GitHub 动作（无论是否精选）都必须封装在 Actions 动**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)
+ [GitHub 操作的局限性 CodeCatalyst](#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)
+ [教程：使用动作的 Lint 代码 GitHub](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 Actions'动作 YAML](github-action-ref.md)
## GitHub 动作与动作有何不同 CodeCatalyst ？
GitHub 在 CodeCatalyst 工作流程中使用的操作与 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 操作以及 [GitHubMarketplace](https://github.com/marketplace/actions) 中可用的任何 GitHub 操作。如果您决定使用 Marketplace 中的 GitHub 操作，请记住以下[限制](#integrations-github-actions-limitations)。
## GitHub 操作的局限性 CodeCatalyst
+ GitHub 操作不能与 CodeCatalyst [Lambda 计算](workflows-working-compute.md#compute.types)类型一起使用。
+ GitHub 操作在 [2022 年 11 月](build-images.md#build.previous-image)的运行时环境 Docker 镜像上运行，其中包括较旧的工具。有关映像和工具的更多信息，请参阅[指定运行时环境映像](build-images.md)。
+ GitHub 内部依赖于[`github`上下文](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context)或引用 GitHub特定资源的操作在中不起作用。 CodeCatalyst例如，以下操作在以下情况下不起作用 CodeCatalyst：
+ 尝试添加、更改或更新 GitHub 资源的操作。示例包括更新拉取请求或在中创建问题的操作 GitHub。
+ 几乎所有操作都列在 [https://github.com/actions](https://github.com/actions) 中。
+ GitHub 作为 [Docker 容器操作的操作](https://docs.github.com/en/actions/creating-actions/about-custom-actions#docker-container-actions)可以运行，但必须由默认 Docker 用户（root）运行。请不要以用户 1001 的身份运行此操作。（在撰写本文时，用户 1001 在中工作 GitHub，但不在中 CodeCatalyst。） 有关更多信息，请参阅 [Dockerfile 操作支持 GitHub ](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions)中的[用户](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions#user)主题。
有关可通过 CodeCatalyst 控制台 GitHub 执行的操作的列表，请参阅[添加精心策划 GitHub 的动作](integrations-github-action-add-curated.md)。
## 如何添加 GitHub 操作（高级步骤）？
向 CodeCatalyst 工作流程添加 GitHub 操作的高级步骤如下：
1. 在您的 CodeCatalyst 项目中，您可以**创建工作流程**。在工作流中，您可以定义如何构建、测试和部署应用程序。有关更多信息，请参阅 [入门工作流](workflows-getting-started.md)。
1. 在工作流程中，您可以**添加精心策划的 GitHub 操作**或**添加 GitHub 操作操作**。
1. 您可以执行下列操作之一：
+ 如果您选择添加一个经策管操作，请配置该操作。有关更多信息，请参阅 [添加精心策划 GitHub 的动作](integrations-github-action-add-curated.md)。
+ 如果您选择添加非精选动作，则在**GitHub操作操作中粘贴该 GitHub 操作****的 YAM** L 代码。您可以在 M [GitHubarketplac](https://github.com/marketplace/actions) e 中选择的 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吗？
不是。 Acti GitHub on 在中运行 CodeCatalyst，使用 CodeCatalyst[运行时环境镜像](workflows-working-compute.md)。
## 我也可以使用 GitHub 工作流程吗？
否。
## “GitHub 动作” 操作使用的运行时镜像
CodeCatalyst **GitHub 操作操作**在 [2022 年 11 月的图像](build-images.md#build.previous-image)上运行。有关更多信息，请参阅 [活动映像](build-images.md#build-curated-images)。
# 教程：使用动作的 Lint 代码 GitHub
在本教程中，您将将 [Super-Linter GitHub 操作](https://github.com/marketplace/actions/super-linter)添加到亚马逊 CodeCatalyst 工作流程中。Super-Linter 操作检查代码，查找代码存在错误、格式问题和可疑结构的区域，然后将结果输出到控制台）。 CodeCatalyst将 linter 添加到工作流后，您可以运行工作流来对示例 Node.js 应用程序（`app.js`）进行 lint 检查。之后，您可以修复报告的问题，并再次运行工作流以查看是否已成功修复问题。
**提示**
考虑使用 Super-Linter 来对 YAML 文件（例如 [CloudFormation 模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)）进行 lint 检查。
**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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 选择**提交**。
现在，您已创建一个名为 `app.js` 的文件。
## 步骤 3：创建运行 Super-Linter 操作的工作流
在此步骤中，您将创建一个工作流，当您将代码推送到源存储库时，该工作流将运行 Super-Linter 操作。该工作流包含您在 YAML 文件中定义的以下构建基块：
+ **触发器** – 当您将更改推送到源存储库时，此触发器会自动启动工作流运行。有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。
+ **“GitHub 操作” 操作** — 触发后，“**GitHub 操作**” 操作会运行 Super-Linter 操作，该操作反过来会检查源存储库中的所有文件。如果 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. 前往 Market [place GitHub 中的 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 控制台中，选择 “**日志**” 选项卡，然后选择 **Lint Code Base**。
这将显示 Super-Linter 操作生成的日志。
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. 修复源存储库中的 `app.js` 和 `README.md`，然后提交您的更改。
**提示**
要修复 `README.md`，请在代码块中添加 `markdown`，如下所示：
```
```markdown
Setup examples:
...
```
```
您的更改将自动启动另一个工作流。等待该工作流完成。如果您已修复所有问题，则该工作流将成功。
## 清理
进行清理 CodeCatalyst 以从您的环境中删除本教程的痕迹。
**要清理干净 CodeCatalyst**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 删除 `codecatalyst-linter-source-repository`。
1. 删除 `codecatalyst-linter-workflow`。
在本教程中，你学习了如何将 Super-Linter GitHub 操作添加到 CodeCatalyst 工作流程中以整理一些代码。
# 添加 “GitHub 操作” 操作
***GitHub 操作操作***是一种封装*CodeCatalyst 动作*并使其与 CodeCatalyst 工作流程兼容的 GitHub 动作。
有关更多信息，请参阅 [与 GitHub 操作集成](integrations-github-actions.md)。
要将 “**GitHub 操作” 操作**添加到工作流程，请执行以下步骤。
**提示**
有关向您展示如何使用 “**GitHub 操作” 操作**的教程，请参阅[教程：使用动作的 Lint 代码 GitHub](integrations-github-action-tutorial.md)。
------
#### [ Visual ]
**使用可视化编辑器添加 “GitHub 操作” 动作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Actions'动作 YAML](github-action-ref.md)。本参考提供了有关在 YAML 编辑器和可视化编辑器中显示的每个字段（以及对应的 YAML 属性值）的详细信息。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器添加 “GitHub 操作” 操作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Actions'动作 YAML](github-action-ref.md)中提供了每个可用属性的解释。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
## 'GitHub 操作'动作定义
**GitHub 操作操作**定义为工作流程定义文件中的一组 YAML 属性。有关这些属性的信息，请参阅[工作流 YAML 定义](workflow-reference.md)中的['GitHub Actions'动作 YAML](github-action-ref.md)。
# 添加精心策划 GitHub 的动作
*策划的 GitHub 操作*是在 CodeCatalyst 控制台中可用的 GitHub 操作，可作为如何在 CodeCatalyst工作流程中使用 GitHub 操作的示例。
策划的 GitHub 操作被封装在由标识符标识的 CodeCatalyst-authored Actions [**GitHub 操作**](integrations-github-action-add.md)中。`aws/github-actions-runner@v1`例如，以下是精心策划的 Acti GitHub on [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.
```
在前面的代码中，Actions CodeCatalyst **GitHub 操作**（由标识`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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Actions'动作 YAML](github-action-ref.md)。本参考提供了有关 “**GitHub操作**” 操作中可用的每个字段（以及相应的 YAML 属性值）的详细信息，因为该字段同时出现在 YAML 和可视编辑器中。
有关策划的 Acti GitHub on 可用的配置选项的信息，请参阅其文档。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**使用 YAML 编辑器添加精选 GitHub 动作**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Actions'动作 YAML](github-action-ref.md)。
有关策划的 Acti GitHub on 可用的配置选项的信息，请参阅其文档。
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 Action 中导出 GitHub 输出参数，以便其他 CodeCatalyst 工作流操作可以使用该参数。
**导出 GitHub 输出参数**
1. 打开工作流并选择**编辑**。有关更多信息，请参阅 [创建工作流](workflows-create-workflow.md)。
1. 在生成要导出的输出参数的 **GitHub Actions** 操作中，添加一个包含基础 `Variables` 属性的 `Outputs` 部分，如下所示：
```
Actions:
MyGitHubAction:
Identifier: aws/github-actions-runner@v1
Outputs:
Variables:
- 'step-id_output-name'
```
进行如下替换：
+ 将 *step-id* 替换为 GitHub 操作的 `steps` 部分中的 `id:` 属性的值。
+ 将 *output-name* 替换为 GitHub 输出参数的名称。
**示例**
以下示例演示如何导出名为 `SELECTEDCOLOR` 的 GitHub 输出参数。
```
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*使用生成输出参数的 Acti CodeCatalyst **GitHub on** 的名称（不要使用 GitHub 操作的`name`或`id`）。
+ *output-name*使用你之前记下的输出参数的`Variables`值。
**示例**
```
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: echo ${MyGitHubAction.random-color-generator_SELECTEDCOLOR}
```
**带上下文的示例**
以下示例说明如何在 `GitHubActionA` 中设置 `SELECTEDCOLOR` 变量、输出该变量，然后在 `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 Actions'动作 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操作**操作。
对应的用户界面：工作流程图// **aws*action-name*/@v1 标签 github-actions-runner**
## DependsOn
(*action-name*/**DependsOn**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的用户界面：配置在tab/Environment/What里面*my-environment*吗？ **/三点菜单/ 切换角色**
## Name
(*action-name*/Environment/Connections/**Name**)
（如果包含 [Connections](#github.environment.connections)，则为必需）
指定账户连接的名称。
对应的用户界面：配置在tab/Environment/What里面*my-environment*吗？ **/三点菜单/ 切换角色**
## Role
(*action-name*/Environment/Connections/**Role**)
（如果包含 [Connections](#github.environment.connections)，则为必需）
指定 IAM 角色的名称，该操作使用此角色来访问 Amazon S3 和 Amazon ECR 等 AWS 服务并在其中进行处理。确保将此角色添加到空间中的 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 操作” 操作**所需的权限。使用具有更广泛权限的角色可能会带来安全风险。
对应的用户界面：配置在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**)
（可选）
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（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)。
**对应的用户界面：输出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`。
+ 要指定所有文件，请使用 `"**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `directory` 的目录中的所有文件和目录，请使用 `"directory/**/*"`。`**` glob 模式表示匹配任意数量的子目录。
+ 要指定名为 `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**变量名称-1**）
（可选）
指定希望操作导出的变量的名称。此变量必须已在同一操作的 `Inputs` 或 `Steps` 部分中定义。
有关变量的更多信息（包括示例），请参阅[在工作流中使用变量](workflows-working-with-variables.md)。
**对应的用户界面：输出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自动发现两个测试报告`TestSuiteTwo.xml`，`TestSuiteOne.xml`则关联 CodeCatalyst 的报告将命名为 `AutoDiscoveredTestSuiteOne` and。`AutoDiscoveredTestSuiteTwo`
相应的 UI：输出tab/Reports/Automatically发现报告/ **报告**前缀
## IncludePaths
(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)
（如果包含并启用 [AutoDiscoverReports](#github.outputs.autodiscover)，或者包含 [Reports](#github.configuration.reports)，则为必需）
指定搜索原始报告时 CodeCatalyst 包含的文件和文件路径。例如，如果您指定`"/test/report/*"`，则会在操作使用的整个[构建映像](build-images.md)中 CodeCatalyst 搜索该`/test/report/*`目录。当它找到该目录时， CodeCatalyst 然后在该目录中查找报告。
**注意**
如果您的文件路径包含一个或多个星号（`*`）或其他特殊字符，请用双引号（`""`）将路径括起来。有关特殊字符的更多信息，请参阅[语法准则和惯例](workflow-reference.md#workflow.terms.syntax.conv)。
如果省略此属性，则默认值为 `"**/*"`，这意味着搜索范围包括所有路径的所有文件。
**注意**
对于手动配置的报告，`IncludePaths` 必须是与单个文件匹配的 glob 模式。
对应的 UI：
+ **输出tab/Reports/Automatically discover reports/'Include/exclude路径'/包括路径**
+ **输出tab/Reports/Manually配置报告/ *report-name-1* /'包含/排除路径'/包含路径**
## ExcludePaths
(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)
Or
(*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 discover reports/'Include/exclude路径'/排除路径**
+ **输出tab/Reports/Manually配置报告/ *report-name-1* /'包含/排除路径'/排除路径**
## SuccessCriteria
(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)
Or
(*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**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)
（可选）
指定测试报告中必须通过测试的百分比，关联 CodeCatalyst的报告才会被标记为通过。有效值包括十进制数字。例如：`50`、`60.5`。通过率标准仅适用于测试报告。有关测试报告的更多信息，请参阅[测试报告](test-workflow-actions.md#test-reports)。
对应的 UI：
+ **输出tab/Reports/Automatically discover reports/Success标准/通过率**
+ **输出tab/Reports/Manually配置报告 *report-name-1* //成功标准/通过率**
## LineCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)
Or
(*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 discover reports/Success标准/线路覆盖范围**
+ **输出tab/Reports/Manually配置报告 *report-name-1* //成功标准/线路覆盖率**
## BranchCoverage
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)
Or
(*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 discover reports/Success标准/分支机构覆盖范围**
+ **输出tab/Reports/Manually配置报告 *report-name-1* //成功标准/分支覆盖范围**
## Vulnerabilities
(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)
（可选）
指定 SCA 报告中允许将关联 CodeCatalyst 报告标记为已通过的最大漏洞数量和严重性。要指定漏洞，您必须指定：
+ 要计入的漏洞的最低严重性。有效值（按严重程度从高到低）为 `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 discover reports/Success标准/漏洞**
+ **输出tab/Reports/Manually配置报告 *report-name-1* //成功标准/漏洞**
## Reports
(*action-name*/Outputs/**Reports** )
（可选）
一个部分，用于指定测试报告的配置。
对应的 UI：“输出”选项卡/**报告**
## report-name-1
（*action-name*/Outputs/Reports/**报告名称 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 编辑器）。
+ 对于由 s [implecov](https://github.com/simplecov-ruby/simplecov) 生成的 SimpleCov JSON，而不是 s [implecov-json](https://github.com/vicentllongo/simplecov-json)，请指定 S **implecov（可视化编辑器）或**（YAML 编辑器）。`SIMPLECOV`
+ 对于软件组成分析（SCA）报告：
+ 对于 SARIF，请指定 **SARIF**（可视化编辑器）或 `SARIFSCA`（YAML 编辑器）。
对应的用户界面：输出tab/Reports/Manually configure reports/Add报告*report-name-1*//**报告类型**和**报告格式**
## Configuration
(*action-name*/**Configuration**)
（必需）可在其中定义操作的配置属性的部分。
对应的 UI：**配置**选项卡
## Steps
(*action-name*/Configuration/**Steps**)
（必需）
在 GitHub M [GitHub arketplac](https://github.com/marketplace) e 中指定操作详情页面上显示的操作代码。按照以下指南来添加代码：
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例如，在前面的代码块中，您可以删除中的代码*red italics*，然后添加**粗体**代码。
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)。
对应的用户界面：“配置” 选项卡/ **GitHub 操作 YAML**
# 配置计算和运行时映像
在 CodeCatalyst 工作流程中，您可以指定用于运行工作流程操作的 CodeCatalyst 计算和运行时环境映像。
*计算*是指为运行工作流操作而管理和维护的计算引擎（CPU、内存和操作系统）。 CodeCatalyst
**注意**
如果计算被定义为工作流的属性，则不能将其定义为该工作流中任何操作的属性。同样，如果计算被定义为任何操作的属性，则无法将其定义为工作流中的属性。
*运行时环境镜像*是一个 Docker 容器，在其中 CodeCatalyst运行工作流程操作。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 不支持某些用例，如果这会对您造成影响，请使用 EC2 计算类型：
+ Lambda 不支持来自指定注册表的运行时环境映像。
+ Lambda 不支持需要 root 权限的工具。对于 `yum` 或 `rpm` 之类的工具，请使用 Amazon EC2 计算类型或其他不需要 root 权限的工具。
+ Lambda 不支持 Docker 构建或运行。不支持以下使用 Docker 镜像的操作：部署 AWS CloudFormation 堆栈、部署到 Amazon ECS、Amazon S3 发布、 AWS CDK 引导、 AWS CDK 部署、 AWS Lambda 调用和 GitHub 操作。Lambda GitHub 计算也不支持在 “ CodeCatalyst GitHub 操作” 操作中运行的基于 Docker 的操作。您可以使用不需要 root 权限的替代方案，例如 Podman。
+ Lambda 不支持写入到 `/tmp` 外部的文件。配置工作流操作时，您可以重新配置工具来安装或写入到 `/tmp`。如果您的构件操作要安装 `npm`，请务必将其配置为安装到 `/tmp`。
+ Lambda 不支持超过 15 分钟的运行时。
## 计算实例集
CodeCatalyst 提供以下计算队列：
+ 按需车队
+ 预置实例集
对于按需实例集，当工作流操作启动时，工作流会预置所需的资源。操作完成后，计算机就会被销毁。您只需为运行操作的分钟数付费。按需实例集是完全托管式的，并包括自动扩展功能以应对需求激增。
CodeCatalyst 还提供预配置的队列，其中包含由 Amazon EC2 提供支持并由维护的机器。 CodeCatalyst使用预置的实例集，您可以配置一组专用计算机来运行工作流操作。这些计算机保持空闲状态，可随时开始立即处理操作。使用预置实例集，您的计算机将始终处于运行状态，并且只要预置完毕，它们就会产生成本。
要创建、更新或删除实例集，您必须拥有**空间管理员**角色或**项目管理员**角色。
## 按需实例集属性
CodeCatalyst 提供以下按需队列：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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。
**架构**
处理器架构。以下架构可用：
+ x86\$164
+ Arm64
**计算机类型**
每个实例的计算机类型。以下计算机类型可用：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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. 选择**删除**。
# 向操作分配实例集或计算
默认情况下，工作流操作使用具有 Amazon EC2 计算类型的 `Linux.x86-64.Large` 按需实例集。要改为使用预置的实例集，或者使用其他按需实例集（例如 `Linux.x86-64.2XLarge`），请按照以下说明操作。
------
#### [ Visual ]
**开始前的准备工作**
+ 如果您要分配预置实例集，则必须先创建预置实例集。有关更多信息，请参阅[创建预置的实例集](projects-create-compute-resource.md)。
**向操作分配预置实例集或其他实例集类型**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择要向其分配预置实例集或新实例集类型的操作。
1. 选择**配置**选项卡。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 找到您要向其分配预置实例集或新实例集类型的操作。
1. 在操作中，添加一个 `Compute` 属性并将 `Fleet` 设置为您的实例集名称或按需实例集类型。有关更多信息，请参阅[构建和测试操作 YAML](build-action-ref.md) 中相应操作 `Fleet` 属性的说明。
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/` |
| 工作流结构 | 操作只能按顺序运行 | 操作可以并行运行 |
| 跨工作流操作访问数据 | 访问缓存的工作流来源（`WorkflowSource`） | 访问共享构件的输出（需要额外配置） |
## 启用计算共享
请按照以下说明，为工作流启用计算共享。
------
#### [ Visual ]
**使用可视化编辑器启用计算共享**
1. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
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. 通过访问 [https://codecatalyst.aws/](https://codecatalyst.aws/) 打开 CodeCatalyst 控制台。
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 发布](#compute-share-s3)
### 示例：Amazon S3 发布
以下工作流示例说明了如何通过两种方式执行 Amazon S3 发布操作：首先使用输入构件，然后使用计算共享。使用计算共享时，不需要输入构件，因为您可以访问缓存的 `WorkflowSource`。此外，不再需要“构建”操作中的输出构件。S3 发布操作配置为使用显式 `DependsOn` 属性来保持连续操作；“构建”操作必须成功运行才能运行 S3 发布操作。
+ 如果未使用计算共享，则需要使用输入构件并将输出与后续操作共享：
```
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
```
# 指定运行时环境映像
*运行时环境镜像*是一个 Docker 容器，在其中 CodeCatalyst运行工作流程操作。Docker 容器在您选择的计算平台上运行，包括操作系统和工作流程操作可能需要的额外工具，例如 AWS CLI、Node.js 和.tar。
默认情况下，工作流程操作将在由提供和维护的其中一个[活动图像](#build-curated-images)上运行 CodeCatalyst。仅构建操作和测试操作支持自定义映像。有关更多信息，请参阅 [为操作分配自定义运行时环境 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 定义中包含一个 `Container` 部分，用于明确指定 [2024 年 3 月版映像](#build.default-image)。您可以选择移除 `Container` 部分以恢复到 [2022 年 11 月版映像](#build.previous-image)。
+ 在 2024 年 3 月 26 日之前添加到工作流中的构建操作和测试操作将*不会*在其 YAML 定义中包含 `Container` 部分，因此将使用 [2022 年 11 月版映像](#build.previous-image)。您可以保留 2022 年 11 月版映像，也可以升级该映像。要升级映像，请在可视化编辑器中打开操作，选择**配置**选项卡，然后从**运行时环境 Docker 映像**下拉列表中选择 2024 年 3 月版映像。此选择将在操作的 YAML 定义中添加 `Container` 部分，而该部分中将填入相应的 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每个计算 type/fleet 组合有一张 2024 年 3 月的图像。
下表显示在每个 2024 年 3 月版映像上安装的工具。
**2024 年 3 月版映像工具**
| 工具 | CodeCatalyst 适用于 Linux 的亚马逊 EC2 x86\$164-`CodeCatalystLinux_x86_64:2024_03` | CodeCatalyst 适用于 Linux 的 Lambda x86\$164-`CodeCatalystLinuxLambda_x86_64:2024_03` | CodeCatalyst 适用于 Linux 的亚马逊 EC2 Arm64-`CodeCatalystLinux_Arm64:2024_03` | CodeCatalyst 适用于 Linux 的 Lambda Arm64-`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 | 不适用 | 24.0.9 | 不适用 |
| Docker Compose | 2.23.3 | 不适用 | 2.23.3 | 不适用 |
| 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 月版映像
每个计算 type/fleet 组合都有一个 2022 年 11 月的图像。如果您配置了[预置实例集](workflows-working-compute.md#compute.fleets)，则还可将 2022 年 11 月版 Windows 映像用于构建操作。
下表显示在每个 2022 年 11 月版映像上安装的工具。
**2022 年 11 月版映像工具**
| 工具 | CodeCatalyst 适用于 Linux 的亚马逊 EC2 x86\$164-`CodeCatalystLinux_x86_64:2022_11` | CodeCatalyst 适用于 Linux 的 Lambda x86\$164-`CodeCatalystLinuxLambda_x86_64:2022_11` | CodeCatalyst 适用于 Linux 的亚马逊 EC2 Arm64-`CodeCatalystLinux_Arm64:2022_11` | CodeCatalyst 适用于 Linux 的 Lambda Arm64-`CodeCatalystLinuxLambda_Arm64:2022_11` | CodeCatalyst 适用于 Windows 的亚马逊 EC2 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 | 不适用 | 不适用 | 1.30.1 |
| Docker | 23.01 | 不适用 | 23.0.1 | 不适用 | 不适用 |
| Docker Compose | 2.16.0 | 不适用 | 2.16.0 | 不适用 | 不适用 |
| 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 | 不适用 | 3.9.15 | 不适用 | 3.11.2 | 不适用 |
| pip | 22.2 | 22.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 |
## 如果活动映像未包括我需要的工具，该怎么办？
如果提供的[活动图像](#build-curated-images)均不 CodeCatalyst 包含您需要的工具，则有以下几种选择：
+ 您可以提供包含必要工具的自定义运行时环境 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 映像
如果您不想使用提供的 A [ctive 镜像](#build-curated-images) CodeCatalyst，则可以提供自定义运行时环境 Docker 镜像。如果要提供自定义映像，请确保其中安装了 Git。映像可以存放在 Docker Hub、Amazon Elastic Container Registry 或任何公共存储库中。
要了解如何创建自定义 Docker 映像，请参阅 Docker 文档中的 [Containerize an application](https://docs.docker.com/get-started/02_our_app/)。
按照以下说明操作，将您的自定义运行时环境 Docker 映像分配给操作。指定映像后，在操作开始时将其 CodeCatalyst 部署到您的计算平台。
**注意**
**以下操作不支持自定义运行时环境 Docker 镜像：**部署 CloudFormation 堆栈**、**部署到 ECS** 和**GitHub 操作**。自定义运行时环境 Docker 镜像也不支持 Lambda 计算类型。**
------
#### [ Visual ]
**使用可视化编辑器分配自定义运行时环境 Docker 映像**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图中，选择将使用您的自定义运行时环境 Docker 映像的操作。
1. 选择**配置**选项卡。
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 映像通过 Amazon ECR 添加对 Node.js 18 的支持](#workflows-working-custom-image-ex-ecr-node18)
+ [示例：使用自定义运行时环境 Docker 映像通过 Docker Hub 添加对 Node.js 18 的支持](#workflows-working-custom-image-ex-docker-node18)
### 示例：使用自定义运行时环境 Docker 映像通过 Amazon ECR 添加对 Node.js 18 的支持
以下示例说明如何使用自定义运行时环境 Docker 映像通过 [Amazon ECR](https://gallery.ecr.aws/amazonlinux/amazonlinux) 添加对 Node.js 18 的支持。
```
Configuration:
Container:
Registry: ECR
Image: public.ecr.aws/amazonlinux/amazonlinux:2023
```
### 示例：使用自定义运行时环境 Docker 映像通过 Docker Hub 添加对 Node.js 18 的支持
以下示例说明如何使用自定义运行时环境 Docker 映像通过 [Docker Hub](https://hub.docker.com/_/node) 添加对 Node.js 18 的支持。
```
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择**创建工作流**以创建工作流。有关更多信息，请参阅 [创建工作流](workflows-create-workflow.md)。
在工作流程创建过程中，您可以指定要 CodeCatalyst存储工作流程定义文件的存储库、分支和文件夹。
# 指定工作流操作的源存储库
按照以下说明指定用于工作流操作的源存储库。在启动时，操作将配置的源存储库中的文件捆绑到构件中，将该构件下载到运行该操作的[运行时环境 Docker 映像](build-images.md)，然后使用下载的文件完成其处理。
**注意**
目前，在一个工作流操作中，您只能指定一个源存储库，即工作流定义文件所在的源存储库（位于 `.codecatalyst/workflows/` 目录或其子目录中）。此源存储库由标签 `WorkflowSource` 表示。
------
#### [ Visual ]
**指定操作将使用的源存储库（可视化编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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/node` 中的 `@types`）
+ 一组[版本](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`从公共外部注册表 ([npmj](https://www.npmjs.com/) s.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 **空间**。有关更多信息，请参阅 [创建空间](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 导航到您的项目 `codecatalyst-package-project`。
1. 在导航窗格中，选择**代码**，然后选择**源存储库**。
1. 选择**添加存储库**，然后选择**创建存储库**。
1. 在**存储库名称**中，输入：
```
hello-world-app
```
1. 选择**创建**。
## 步骤 2：创建 CodeCatalyst 和网关软件包存储库
在此步骤中，您将在 CodeCatalyst 项目中创建包存储库，并将其连接到网关存储库（也包括在您的 CodeCatalyst 项目中）。稍后，您将本教程中的依赖项 `lodash` 从 npmjs.com 导入到这两个存储库中。
网关存储库是将你的软件包存储库连接到公共 npmjs.co CodeCatalyst m 的 “粘合剂”。
有关程序包存储库的更多信息，请参阅[在中发布和共享软件包 CodeCatalyst](packages.md)。
**注意**
本教程使用*CodeCatalyst 软件包存储库*和*网关存储库*这两个术语来指您在以下过程中创建 CodeCatalyst 的两个存储库。
**创建 CodeCatalyst 软件包和网关存储库**
1. 在导航窗格中，选择**程序包**。
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
```
初始化过程将在 `hello-world-app` 的根目录中创建一个 `package.json` 文件。
1. 将开发环境中的 npm 客户端连接到你的 CodeCatalyst 包存储库：
1. 切换到 CodeCatalyst 控制台。
1. 在导航窗格中，选择**程序包**。
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. 导入 `lodash` 版本 4.17.20：
```
npm install lodash@v4.17.20 --save --save-exact
```
npm 按以下顺序在以下位置查找 `lodash` 版本 4.17.20：
+ 在开发环境中。它在该位置找不到此版本。
+ 在 CodeCatalyst 软件包存储库中。它在该位置找不到此版本。
+ 在网关存储库中。它在该位置找不到此版本。
+ 在 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`并验证中的行是否***red bold***已添加：
```
{
"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. 在导航窗格中，选择**程序包**。
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`**
此命令会打印出已下载到运行该操作的 Docker 映像的 `lodash` 的版本。
+ **`- 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-package-repository*替换为您在中创建的 CodeCatalyst 软件包存储库的名称[步骤 2：创建 CodeCatalyst 和网关软件包存储库](#packages-tutorial-package-repo)。
有关此文件中的属性的信息，请参阅[构建和测试操作 YAML](build-action-ref.md)。
1. （可选）选择**验证**，确保 YAML 代码在提交之前有效。
1. 选择**提交**。
1. 在**提交工作流**对话框中，输入以下内容：
1. 对于**工作流文件名**，保留默认值 `codecatalyst-package-workflow`。
1. 对于**提交消息**，输入：
```
add initial workflow file
```
1. 对于**存储库**，选择 **hello-world-app**。
1. 对于**分支名称**，选择**主**。
1. 选择**提交**。
现在，您已创建工作流。
**运行工作流**
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
```
此消息指示 `lodash` 版本 4.17.20 已下载到运行工作流操作的 Docker 映像。
## 步骤 6：阻止来自 npmjs.com 的导入
现在 4.17.20 `lodash` 版本已存在于您的网关和 CodeCatalyst软件包存储库中，您可以阻止其他版本的导入。阻止可防止您意外导入可能包含恶意代码的更高（或更早）版本的 `lodash`。有关更多信息，请参阅[编辑程序包来源控制](package-origin-controls.md)和[依赖项替换攻击](package-origin-controls.md#dependency-substitution-attacks)。
按照以下说明操作，阻止将 `lodash` 导入到网关存储库中。当您在网关上阻止程序包时，它们也会在下游位置被阻止。
**阻止导入到网关存储库**
1. 在导航窗格中，选择**程序包**。
1. 选择 **npm-publish-registry-gateway**。
1. 选择 `lodash`。
1. 在顶部附近，选择**源控制**。
1. 在**上游**下，选择**阻止**。
1. 选择**保存**。
现在，您已阻止从 npmjs.com 导入网关存储库（以及下游存储库和计算机）中。
## 步骤 7：测试阻止功能
在此部分中，您将验证您在 [步骤 6：阻止来自 npmjs.com 的导入](#packages-tutorial-block) 中设置的阻止是否有效。首先，将“Hello World”配置为 `lodash` 的请求版本 4.17.2**1**，而不是网关存储库中可用的版本，即 4.17.2**0**。然后，检查应用程序是否无法从 nmpjs.com 中拉取版本 4.17.21，这表示已成功阻止。作为最终测试，您需要解除阻止导入到网关存储库，并检查应用程序是否能成功拉取 `lodash` 的版本 4.17.21。
使用以下一组过程来测试阻止功能。
**开始前的准备工作**
1. 切换到您的开发环境。
1. 提取您之前使用 CodeCatalyst 控制台创建的`codecatalyst-package-workflow.yaml`文件：
```
git pull
```
**将“Hello World”配置为“lodash”的请求版本 4.17.21**
1. 打开 `/hello-world-app/package.json`。
1. 将`lodash`版本更改为 4.17.21，如所示：***red bold***
```
{
"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”是否无法拉取“lodash”的版本 4.17.21**
1. 在版本不匹配的情况下运行工作流：
1. 切换到 CodeCatalyst 控制台。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 在 `codecatalyst-package-workflow` 旁边，选择**操作**，然后选择**运行**。
npm 会在 `package.json` 中查找依赖项，并看到“Hello World”需要 `lodash` 的版本 4.17.21。npm 按以下顺序在以下位置查找依赖项：
+ 在运行该操作的 Docker 映像中。它在该位置找不到此版本。
+ 在 CodeCatalyst 软件包存储库中。它在该位置找不到此版本。
+ 在网关存储库中。它在该位置找不到此版本。
+ 在 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. 在导航窗格中，选择**程序包**。
1. 选择 **npm-publish-registry-gateway**。
1. 选择 `lodash`。
1. 在顶部附近，选择**源控制**。
1. 在**上游**下，选择**允许**。
1. 选择**保存**。
您现在已解除阻止导入 `lodash`。
您的工作流现在可以导入 `lodash` 的版本 4.17.21。
**测试是否已解除阻止来自 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
```
此消息指示已下载 `lodash` 版本 4.17.21。
1. 验证版本 4.17.21 是否已导入到您的 CodeCatalyst 和网关存储库中：
1. 在导航窗格中，选择**程序包**。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，对要配置的程序包存储库选择**构建**或**测试**操作。
1. 选择**程序包**。
1. 从**添加配置**下拉菜单中，选择要用于工作流操作的程序包配置。
1. 选择**添加程序包存储库**。
1. 在 P **ackage 存储库**下拉菜单中，指定您希望该操作使用的 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 使此令牌可用作环境变量，供您在操作中引用。
| 环境变量 | 值 |
| --- | --- |
| CATALYST\$1MACHINE\$1RESOURCE\$1NAME | 授权令牌的用户身份。 |
| CATALYST\$1PACKAGES\$1AUTHORIZATION\$1TOKEN | 授权令牌的值。 |
**注意**
请注意，只有在您将操作配置为导出授权令牌后，才会填充这些环境变量。
按照以下说明在工作流操作中使用授权令牌。
------
#### [ Visual ]
**将导出的授权令牌与操作配合使用（可视化编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，对要配置的程序包存储库选择**构建**或**测试**操作。
1. 选择**程序包**。
1. 开启**导出授权令牌**。
------
#### [ YAML ]
**将导出的授权令牌与操作配合使用（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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
```
如果您包含覆盖范围，则优先使用最后一个存储库。在本示例中，在 `PackageRegistries` 中最后一次配置范围 `@scope2` 是为 `my-repo-2` 配置的。这会覆盖为 `my-repo-1` 配置的范围 `@scope2`。
## 示例：手动配置`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)。之后，可以在后续工作流操作中引用这些变量。如果您不想将所有顶级密钥都转换为变量，则可以使用筛选条件来指定确切的密钥。有关更多信息，请参阅[“AWS Lambda 调用”操作 YAML](lam-invoke-action-ref.md) 中的 [ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters) 属性描述。
**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 函数中并由 Lambda 函数执行的功能，请使用此操作。
例如，您可能希望工作流在开始构建应用程序之前向 Slack 频道发送 `Build started` 通知。在此情况下，您的工作流将包括一个 **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` 和 `us-west-2`）中的 `Notify-Start` Lambda 函数。此 Lambda 函数一经调用，就会发送一条 Slack 通知，表明部署已开始。
+ **部署 CloudFormation 堆栈**操作 (`Deploy`)-**AWS Lambda 调用**操作完成后，**部署 CloudFormation 堆栈**操作将运行模板 (`cfn-template.yml`) 来部署您的应用程序堆栈。有关 “**部署 CloudFormation 堆栈**” 操作的更多信息，请参阅[部署 CloudFormation 堆栈](deploy-action-cfn.md)。
**注意**
以下工作流示例仅用于说明目的，如果不执行附加配置，则无法运行。
**注意**
在接下来的 YAML 代码中，如果需要，可以省略 `Connections:` 部分。如果您省略这些部分，则必须确保在您的环境中 Defa **ult 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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 |
| 地点 | Seattle |
| department | \$1"company": "Amazon", "team": "AWS"\$1 |
**注意**
您可以使用 `ResponseFilters` YAML 属性更改生成的变量。有关更多信息，请参阅 [“AWS Lambda 调用”操作 YAML](lam-invoke-action-ref.md) 中的 [ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters)。
运行时由 “in AWS Lambda voke” 操作生成和设置的变量称为*预定义*变量。
有关在工作流中引用这些变量的信息，请参阅[使用预定义变量](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**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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**)
（可选）
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（\$1）。不允许使用空格。不能使用引号以使变量名能够包含特殊字符和空格。
有关变量的更多信息（包括示例），请参阅[在工作流中使用变量](workflows-working-with-variables.md)。
对应的 UI：“输入”选项卡/**变量 – 可选**
## Environment
(*LambdaInvoke*/**Environment**)
（必需）
指定要用于操作的 CodeCatalyst 环境。该操作连接到在所选环境中指定的 AWS 账户 和可选的 Amazon VPC。该操作使用环境中指定的默认 IAM 角色连接到 AWS 账户，并使用在 A [mazon VPC 连接](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html)中指定的 IAM 角色连接到亚马逊 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 定义文档中 **Role** 属性的描述。
有关账户连接的更多信息，请参阅[允许在已连接的情况下访问 AWS 资源 AWS 账户](ipa-connect-account.md)。有关向环境添加账户连接的信息，请参阅[创建环境](deploy-environments-creating-environment.md)。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## Name
(*LambdaInvoke*/Environment/Connections/**Name**)
（如果包含 [Connections](#lam.invoke.environment.connections)，则为必需）
指定账户连接的名称。
对应的 UI：根据操作版本的不同，为下列项之一：
+ （新版本）配置tab/Environment/What在*my-environment*吗？ **/三点菜单/ 切换角色**
+ **（旧版本）配置选项卡/ Environment/account/role ''/账户连接AWS **
## 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**
## Configuration
(*LambdaInvoke*/**Configuration**)
（必需）
可在其中定义操作的配置属性的部分。
对应的 UI：**配置**选项卡
## Function
(*LambdaInvoke*/Configuration/**Function**)
（必需）
指定此操作将调用的 AWS Lambda 函数。您可以指定函数的名称或其 Amazon 资源名称（ARN）。您可以在 Lambda 控制台中查找名称或 ARN。
**注意**
Lambda 函数所在的 AWS 账户可以与下指定的账户不同。`Connections:`
对应的 UI：“配置”选项卡/**函数**
## AWSRegion
(*LambdaInvoke*/Configuration/**AWSRegion**)
（必需）
指定您的 AWS Lambda 函数所在的 AWS 区域。有关区域代码的列表，请参阅《AWS 一般参考》**中的 [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。
对应的 UI：“配置”选项卡/**目标存储桶 – 可选**
## RequestPayload
(*LambdaInvoke*/Configuration/**RequestPayload**)
（可选）
如果要将请求有效载荷传递到 **AWS Lambda 调用**操作，请在此处以 JSON 格式指定该请求有效载荷。
示例请求有效载荷：
```
'{ "key": "value" }'
```
如果您不想将请求有效载荷传递到 Lambda 函数，请忽略此属性。
**注意**
您可以指定 `RequestPayload` 或 `RequestPayloadFile`，但不能同时指定两者。
有关请求有效载荷的更多信息，请参阅《AWS Lambda API 参考》**中的 [Invoke](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 参考》**中的 [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) 主题。
对应的 UI：“配置”选项卡/**请求有效载荷文件 – 可选**
## ContinueOnError
(*LambdaInvoke*/Configuration/**RequestPayloadFile**)
（可选）
指定即使调用的 AWS Lambda 函数失败，是否也将 **AWS Lambda 调用**操作标记为成功。考虑将此属性设置为 `true` 以允许在 Lambda 失败的情况下启动工作流中的后续操作。
默认情况下，如果 Lambda 函数失败（在可视化编辑器中为“off”，在 YAML 编辑器中为 `false`），则操作将失败。
对应的 UI：“配置”选项卡/**出错时继续**
## LogType
(*LambdaInvoke*/Configuration/**LogType**)
（可选）
指定是否要在 Lambda 函数被调用后提供的响应中包含错误日志。您可以在控制台的 **Lambda 调用**操作的 “**日志” 选项卡中查看这些日志**。 CodeCatalyst 可能的值有：
+ `Tail` – 返回日志
+ `None` – 不返回日志
默认值为 **Tail**。
有关日志类型的更多信息，请参阅《AWS Lambda API 参考》**中的 [Invoke](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 [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)
## 何时使用此操作
如果您的工作流使用动态内容（例如提交 ID 或时间戳）来构建和标记 Docker 映像，请使用此操作。
如果您的任务定义文件包含始终保持不变的映像值，请不要使用此操作。在这种情况下，您可以手动将映像名称输入任务定义文件中。
## “渲染 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 任务定义**操作以及构建和部署操作的完整工作流示例。该工作流旨在构建 Docker 映像并将其部署到 Amazon ECS 集群中。工作流包含以下按顺序运行的构造块：
+ **触发器** – 当您将更改推送到源存储库时，此触发器会自动启动工作流运行。有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在左上角，选择 **\$1 操作**打开操作目录。
1. 从下拉列表中选择 A **mazon 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](deploy-action-ecs.md) 中的说明操作，将**部署到 Amazon ECS** 操作添加到工作流中。添加部署操作时，请执行以下操作：
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://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择包含已完成的渲染操作的运行。
1. 在工作流图表中，选择渲染操作。
1. 选择**输出**。
1. 选择**变量**。
1. 这将显示任务定义文件的名称。该名称类似于 `task-definition--259-0a2r7gxlTF5X-.json`。
**查看更新后的任务定义文件的内容**
1. 查找包含已完成的渲染操作的运行：
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择包含已完成的渲染操作的运行。
1. 在工作流运行中，在顶部的**可视化**和 **YAML** 旁边，选择**工作流输出**。
1. 在**构件**部分中，选择包含更新后的任务定义文件的构件旁边的**下载**。此构件的**生成者**列将设置为渲染操作的名称。
1. 打开 .zip 文件以查看任务定义 .json 文件。
# “渲染 Amazon ECS 任务定义”变量
**渲染 Amazon ECS 任务定义**操作在运行时会生成并设置以下变量。这些变量被称为*预定义变量*。
有关在工作流中引用这些变量的信息，请参阅 [使用预定义变量](workflows-using-predefined-variables.md)。
| 键 | 值 |
| --- | --- |
| task-definition | 为已由**渲染 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`。
**对应的用户界面：工作流程图/ ECSRenderTaskDefinition \$1nn/ aws/ @v1 标签 ecs-render-task-definition**
## DependsOn
(*ECSRenderTaskDefinition*/**DependsOn**)
（可选）
指定必须成功运行才能使该操作运行的操作、操作组或阶段门。
有关“依赖于”功能的更多信息，请参阅[顺序操作](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**)
（必需）
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（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 弹性容器注册表 (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：“输出”选项卡/变量/**名称**字段
# 在工作流中使用变量
*变量*是一个键值对，其中包含您可以在 Ama CodeCatalyst zon 工作流程中引用的信息。工作流运行时，变量的值部分将替换为实际值。
在工作流中，您可以使用两种类型的变量：
+ **用户定义的变量** – 这些是您定义的键-值对。
+ **预定义变量** – 这些是工作流自动发出的键-值对。您无需对其进行定义。
有关工作流的更多信息，请参阅[使用工作流进行构建、测试和部署使用工作流进行构建、测试和部署](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)
# 使用用户定义的变量
*用户定义的变量*是您定义的键-值对。这些变量分为两种类型：
+ **纯文本变量**，简称为**变量** – 这些是您在工作流定义文件中以纯文本形式定义的键-值对。
+ **密钥** — 这些是您在 Ama CodeCatalyst zon 控制台的单独**密钥**页面上定义的键值对。*键*（名称）是一个公共标签，*值*包含您要保密的信息。您只能在工作流定义文件中指定键。在工作流定义文件中，使用密钥代替密码和其他敏感信息。
**注意**
为简洁起见，本指南使用术语*变量*来表示*纯文本变量*。
有关变量的更多信息，请参阅[在工作流中使用变量](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` 部分中定义两个变量 `VAR1` 和 `VAR2`。
```
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 属性导出变量
以下示例向您演示了如何使用 `Outputs` 部分定义两个变量 `REPOSITORY-URI` 和 `TIMESTAMP` 并导出它们。
```
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
```
## 示例：引用在同一操作中定义的变量
以下示例向您演示了如何在 `MyBuildAction` 中指定变量 `VAR1`，然后使用 `$VAR1` 在同一个操作中引用该变量。
```
Actions:
MyBuildAction:
Identifier: aws/build@v1
Inputs:
Variables:
- Name: VAR1
Value: my-value
Configuration:
Steps:
- Run: $VAR1
```
## 示例：引用在其他操作中定义的变量
以下示例向您演示了如何在 `BuildActionA` 中指定变量 `TIMESTAMP`，使用 `Outputs` 属性导出变量，然后使用 `${BuildActionA.TIMESTAMP}` 在 `BuildActionB` 中进行引用。
```
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 控制台的 S **ec** rets 页面上指定，然后才能在工作流程定义文件中使用。有关更多信息，请参阅 [使用密钥遮蔽数据](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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择要设置变量的操作。
1. 选择**输入**。
1. 在**变量 – 可选**中，选择**添加变量**，然后执行以下操作：
指定一系列 name/value 对，用于定义要提供给操作的输入变量。变量名称仅限字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（\$1）。不允许使用空格。不能使用引号以使变量名能够包含特殊字符和空格。
有关变量的更多信息（包括示例），请参阅[在工作流中使用变量](workflows-working-with-variables.md)。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**在“输入”部分中定义变量（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择要设置变量的操作。
1. 选择**配置**。
1. 在 **Shell 命令**或 GitHub Actions **YAML**（无论哪个可用）中，在操作中显式或隐`Steps`式地定义一个变量。
+ 要显式定义变量，请将其直接包含在 `Steps` 部分的 bash 命令中。
+ 要隐式定义变量，请在操作的 `Steps` 部分引用的文件中指定该变量。
有关示例，请参阅 [变量示例](workflows-working-with-variables-ex.md)。有关更多信息，请参阅相应操作的[工作流 YAML 定义](workflow-reference.md)。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**在“步骤”部分中定义变量（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 选择您的项目。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择**可视化**。
1. 在工作流图表中，选择要从中导出变量的操作。
1. 选择**输出**。
1. 在**变量 – 可选**中，选择**添加变量**，然后执行以下操作：
指定希望操作导出的变量的名称。此变量必须已在同一操作的 `Inputs` 或 `Steps` 部分中定义。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
------
#### [ YAML ]
**导出变量（YAML 编辑器）**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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://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://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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 Labs 操作，请改为参阅[确定您的工作流会发出哪些预定义变量](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 引导”变量](cdk-boot-action-variables.md)
+ [“AWS Lambda 调用”变量](lam-invoke-action-variables.md)
+ [“渲染 Amazon ECS 任务定义”变量](render-ecs-action-variables.md)
# 使用密钥遮蔽数据
有时您可能需要在工作流中使用敏感数据，例如身份验证凭证。应避免将这些值以纯文本形式存储在存储库中的任何地方，因为任何有权访问包含密钥的存储库的人都可以看到密钥。同样，不应在任何工作流定义中直接使用这些值，因为它们将作为文件在存储库中可见。使用 CodeCatalyst，您可以通过向项目添加密钥，然后在工作流程定义文件中引用该密钥来保护这些值。请注意，每个操作最多可有 5 个密钥。
**注意**
密钥只能用于替换工作流定义文件中的密码和敏感信息。
**Topics**
+ [创建密钥](workflows-secrets.creating.md)
+ [编辑密钥](workflows-secrets.editing.md)
+ [使用密钥](workflows-secrets.using.md)
+ [删除密钥](workflows-secrets.deleting.md)
# 创建密钥
使用以下过程创建密钥。密钥包含您想要隐藏以防其他人查看的敏感信息。
**注意**
密钥对操作可见，在写入文件时不会被屏蔽。
**创建密钥**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**密钥**。
1. 选择**创建密钥**。
1. 输入以下信息：
**名称**
输入密钥的名称。
**值**
输入密钥的值。这是您想要隐藏以防其他人查看的敏感信息。默认情况下，该值不显示。要显示该值，请选择**显示值**。
**描述**
（可选）输入密钥的描述。
1. 选择**创建**。
# 编辑密钥
使用以下过程编辑步骤。
**编辑密钥**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**密钥**。
1. 在密钥列表中，选择要编辑的密钥。
1. 选择**编辑**。
1. 编辑以下属性：
**值**
输入密钥的值。这是您要隐藏以防其他人查看的值。默认情况下，该值不显示。
**描述**
（可选）输入密钥的描述。
1. 选择**保存**。
# 使用密钥
要在工作流操作中使用密钥，您必须获取密钥的引用标识符并在工作流操作中使用该标识符。
**Topics**
+ [获取密钥的标识符](#workflows-using-secrets.get-identifier)
+ [在工作流中引用密钥](#workflows-using-secrets.using-identifier)
## 获取密钥的标识符
使用以下过程获取密钥的引用标识符。您将此标识符添加到工作流中。
**获取密钥的引用标识符**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。
1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。
1. 选择**编辑**。
1. 选择 **YAML**。
1. 在工作流中搜索以下字符串：
```
${Secrets.
```
这将找到所有密钥的所有引用标识符。
1. 删除所选密钥的参考标识符，或将其替换为纯文本值。
1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。
1. 选择**提交**，输入提交消息，然后再次选择**提交**。
**删除密钥**
1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。
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 |
| 每份测试报告的最大测试用例数 | 20000 |
| 每份代码覆盖率报告的最大文件数 | 20000 |
| 每份报告的软件组成分析调查发现最大数量 | 20000 |
| 每份静态分析报告的文件最大数 | 20000 |
| 每个空间的最大并发工作流运行数 | 100 |
| 每个工作流的最大操作数量 | 50 |
| 每个工作流并发运行的操作的最大数 | 50 |
| 每个空间并发运行的操作的最大数 | 200 |
| 操作可以运行的最长时间 | 对于构件和测试操作，超时时间为 8 小时。 对于所有其他操作，超时时间为 1 小时。 |
| 每个空间与 AWS 账户 关联的环境最大数 | 5000 |
| 每个操作的最大密钥数 | 5 |
| 每个空间的最大密钥数 | 500,000 |
# 工作流运行状态
工作流运行可以处于以下几种状态之一：
+ **成功** – 工作流运行已成功处理。
+ **失败** – 工作流运行中的一个或多个操作失败。
+ **进行中** – 工作流运行当前正在处理中。
+ **已停止** – 在工作流运行期间，有人停止了工作流的运行。
+ **正在停止** – 当前正在停止工作流运行。
+ **已取消** — 工作流程运行已被取消， CodeCatalyst 因为在运行过程中关联的工作流程已被删除或更新。
+ **已取代** – 仅在配置了[取代运行模式](workflows-configure-runs.md#workflows-configure-runs-superseded)时才会发生。工作流程运行已被取消， CodeCatalyst 因为稍后的工作流程运行取代了该运行。
# 工作流程状态为 CodeCatalyst
工作流可能具有以下状态之一：
+ **有效** – 工作流可运行，可通过[触发器](workflows-add-trigger.md#workflows-add-trigger.title)激活。
标记为有效的工作流必须满足以下两个条件：
+ 工作流定义文件必须有效。
+ 工作流必须没有触发器，没有推送触发器，也没有使用当前分支上的文件运行的推送触发器。有关更多信息，请参阅[触发器和分支的使用准则](workflows-add-trigger-considerations.md)。
+ **无效** – 工作流的定义文件无效。工作流无法手动运行，也无法通过触发器自动运行。无效的工作流程与**工作流定义一起出现在 CodeCatalyst 控制台中出现*n*错误**消息（或类似消息）。
标记为无效的工作流必须满足以下条件：
+ 工作流定义文件必须有配置错误。
要修复配置错误的工作流定义文件，请参阅[如何修复 “工作流程定义有*n*错误” 错误？](troubleshooting-workflows.md#troubleshooting-workflows-asterisks)。
+ **非活动** – 工作流定义有效，但无法手动运行，也无法通过触发器自动运行。
标记为非活动的工作流必须满足以下两个条件：
+ 工作流定义文件必须有效。
+ 工作流定义文件必须包含推送触发器，该触发器指定的分支不同于工作流定义文件当前所在的分支。有关更多信息，请参阅[触发器和分支的使用准则](workflows-add-trigger-considerations.md)。
要将工作流从**非活动**切换为**活动**，请参阅[如何修复“工作流非活动”消息？](troubleshooting-workflows.md#troubleshooting-workflows-inactive)。
**注意**
如果有多个工作流处于**非活动**状态，则可以将其从视图中筛选出来。要筛选出非活动的工作流，请选择**工作流**页面顶部的**筛选工作流**字段，选择**状态**，选择**状态 \$1= 不等于**，然后选择**非活动**。
**注意**
如果工作流程指定了您稍后移除的资源（例如包存储库），则 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` 部分和一个包含 `Build` 和 `Test` 这两个操作的 `Actions` 部分。有关更多信息，请参阅 [关于工作流定义文件](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
```
+ **Triple dash (`---`)**：不要`---`在你的 YAML 代码中使用。 CodeCatalyst 忽略后面的所有内容。`---`
### 命名规范
在本指南中，我们使用*属性*和*部分*两词来指代工作流定义文件中的主要项目。
+ *属性*是任何包含冒号（`:`）的项目。例如，在下面的代码片段中，以下所有项都是属性：`Name`、`SchemaVersion`、`RunMode`、`Triggers`、`Type` 和 `Branches`。
+ *部分*是任何具有子属性的属性。在下面的代码片段中，有一个 `Triggers` 部分。
**注意**
在本指南中，“部分”有时被称为“属性”，反之亦然，视上下文而定。
```
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）。不允许使用空格。不能使用引号在工作流名称中启用特殊字符和空格。
**对应的用户界面：视觉 editor/Workflow 属性/工作流程名称**
### SchemaVersion
（必需）
工作流定义的架构版本。目前唯一有效的值是 `1.0`。
对应的 UI：*无*
### RunMode
（可选）
如何 CodeCatalyst 处理多次运行。可以使用下列值之一：
+ `QUEUED` – 多个运行排队并一个接一个地运行。一个队列中最多可包含 50 个运行。
+ `SUPERSEDED` – 多个运行排队并一个接一个地运行。一个队列只能有一个运行，因此如果两个运行同时出现在同一个队列中，则后一个运行将取代（接替）前一个运行，而前一个运行将被取消。
+ `PARALLEL` – 同时进行多个运行。
如果省略该属性，则默认值为 `QUEUED`。
有关更多信息，请参阅 [配置运行的排队行为](workflows-configure-runs.md)。
**对应的用户界面：视觉 editor/Workflow 属性/高级/运行模式**
### 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)。
**对应的用户界面：视觉 editor/Workflow 属性/高级/计算类型**
#### 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)。
**对应的用户界面：视觉 editor/Workflow 属性/高级/计算舰队**
#### SharedInstance
(Compute/**SharedInstance**)
（可选）
为您的操作指定计算共享功能。通过计算共享，工作流中的操作会在同一个实例（运行时环境映像）上运行。可以使用下列值之一：
+ `TRUE` 表示工作流操作之间共享运行时环境映像。
+ `FALSE` 表示为工作流中的每个操作启动和使用单独的运行时环境映像，因此如果没有额外的配置，就无法共享构件和变量等资源。
有关计算共享的更多信息，请参阅[跨操作共享计算](compute-sharing.md)。
对应的 UI：*无*
### Triggers
（可选）
该工作流的一个或多个触发器序列。如果未指定触发器，则必须手动启动工作流。
有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。
**对应的用户界面：可视化 editor/workflow 图表/触发器**
```
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)。
**对应的用户界面：可视化 editor/workflow 图/触发器/触发器类型**
#### Events
(Triggers/**Events**)
（如果触发器 `Type` 设置为 `PULLREQUEST`，则是必需的）
指定将启动工作流运行的拉取请求事件的类型。有效值如下所示：
+ **拉取请求已创建**（可视化编辑器）或 `OPEN`（YAML 编辑器）
工作流运行将在拉取请求创建后启动。
+ **拉取请求已关闭**（可视化编辑器）或 `CLOSED`（YAML 编辑器）
工作流运行将在拉取请求关闭后启动。`CLOSED` 事件的行为不太好说明，最好通过一个例子来理解。请参阅[示例：带有拉取、分支和“CLOSED”事件的触发器](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close)了解更多信息。
+ **对拉取请求进行了新的修订**（可视化编辑器）或 `REVISION`（YAML 编辑器）
工作流运行将在对拉取请求的修订创建后启动。在创建拉取请求时，将创建第一个修订。之后，每当有人将新的提交推送到拉取请求中指定的源分支时，就会创建一个新的修订。如果您在拉取请求触发器中包含 `REVISION` 事件，则可以忽略 `OPEN` 事件，因为 `REVISION` 是 `OPEN` 的超集。
您可以在同一个拉取请求触发器中指定多个事件。
有关示例，请参阅 [示例：工作流中的触发器](workflows-add-trigger-examples.md)。
**相应的用户界面： editor/workflow 拉取请求的可视化图表/触发器/事件**
#### Branches
(Triggers/**Branches**)
（可选）
指定触发器监控的源存储库中的分支，以便知道何时启动工作流运行。您可以使用正则表达式模式来定义分支名称。例如，使用 `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)。
对应的用户界面：视觉editor/workflow diagram/Triggers/**分支**
#### FilesChanged
(Triggers/**FilesChanged**)
（如果触发器 `Type` 设置为 `PUSH` 或 `PULLREQUEST`，则为可选的。如果触发器 `Type` 设置为 `SCHEDULE`，则不受支持。）
指定触发器监控的源存储库中的文件或文件夹，以便知道何时启动工作流运行。您可以使用正则表达式来匹配文件名或路径。
有关示例，请参阅 [示例：工作流中的触发器](workflows-add-trigger-examples.md)。
**相应的用户界面：可视化 editor/workflow 图表/触发器/文件已更改**
#### Expression
(Triggers/**Expression**)
（如果触发器 `Type` 设置为 `SCHEDULE`，则是必需的）
指定 cron 表达式，用于描述您希望何时执行计划的工作流运行。
中的 Cron 表达式 CodeCatalyst 使用以下六字段语法，其中每个字段用空格分隔：
*minutes* *hours* *days-of-month* *month* *days-of-week* *year*
**cron 表达式示例**
| 分钟 | 小时 | 一个月中的第几天 | Month | 星期几 | 年 | 意义 |
| --- | --- | --- | --- | --- | --- | --- |
| 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 | 星期六至星期日，从起始日晚上 10:00 至次日凌晨 2:00（UTC\$10）每隔 30 分钟运行一次工作流。 |
| 45 | 13 | L | \$1 | ? | 2023-2027 | 2023 年至 2027 年（含）之间，在每个月的最后一天下午 1:45（UTC\$10）运行工作流。 |
在中指定 cron 表达式时 CodeCatalyst，请务必遵循以下准则：
+ 为每个 `SCHEDULE` 触发器指定一个 cron 表达式。
+ 在 YAML 编辑器中，将 cron 表达式用双引号（`"`）括起来。
+ 使用协调世界时（UTC）格式指定时间。不支持其他时区。
+ 两次运行之间应至少配置 30 分钟的运行间隔。不支持更快的节奏。
+ 指定*days-of-month*或字*days-of-week*段，但不能同时指定两者。如果您在其中一个字段中指定值或星号（`*`），则必须在另一个字段中使用问号（`?`）。星号表示“全部”，问号表示“任何”。
有关 cron 表达式的更多示例以及有关通配符（如`?`、和）的信息 `*``L`，请参阅《*亚马逊 EventBridge *用户指南[》中的 Cron 表达式参考](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html)。 EventBridge 和中的 Cron 表达式 CodeCatalyst 的工作方式完全相同。
有关计划触发器的示例，请参阅[示例：工作流中的触发器](workflows-add-trigger-examples.md)。
对应的用户界面：视觉editor/workflow diagram/Triggers/**日程安排**
### 操作
此工作流程的一个或多个操作序列。 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)。
**对应的用户界面：可视化编辑器/ *action-name* /配置选项卡/ **操作名称或操作显示名称****
#### action-group-name
(Actions/*action-group-name*)
（可选）
一个*操作组*包含一个或多个操作。将操作分组为操作组有助于将工作流保持得井井有条，还可以配置不同组之间的依赖关系。
*action-group-name*替换为你要给操作组起的名字。操作组名称在工作流中必须是唯一的，并且只能包含字母数字字符、连字符和下划线。有关语法规则的更多信息，请参阅 [YAML 语法准则](#workflow.syntax.conv)。
有关操作组的更多信息，请参阅[将操作分组为操作组](workflows-group-actions.md)。
对应的 UI：*无*