亚马逊 CodeCatalyst 不再向新买家开放。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [如何从中迁移 CodeCatalyst](migration.md)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 工作流 YAML 定义 以下是工作流定义文件的参考文档。 *工作流定义文件*是描述您的工作流的 YAML 文件。默认情况下，该文件存储在[源存储库](source-repositories.md)根目录下的 `~/.codecatalyst/workflows/` 文件夹中。该文件的扩展名可以为 .yml 或 .yaml，并且扩展名必须小写。 要创建和编辑工作流程定义文件，您可以使用编辑器（例如 vim），也可以使用 CodeCatalyst 控制台的可视化编辑器或 YAML 编辑器。有关更多信息，请参阅 [使用 CodeCatalyst 控制台的视觉编辑器和 YAML 编辑器](workflow.md#workflow.editors)。 **注意** 接下来的大多数 YAML 属性在可视化编辑器中都有对应的 UI 元素。要查找 UI 元素，请使用 **Ctrl\$1F**。该元素将与其关联的 YAML 属性一起列出。 **Topics** + [工作流定义文件示例](#workflow.anatomy) + [语法准则和惯例](#workflow.terms.syntax.conv) + [顶级属性](#workflow.top.level) ## 工作流定义文件示例 下面是一个简单的工作流定义文件示例。该示例包括几个顶级属性、一个 `Triggers` 部分和一个包含 `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：*无*