工作流 YAML 定义

以下是工作流定义文件的参考文档。

工作流定义文件是描述您的工作流的 YAML 文件。默认情况下，该文件存储在源存储库根目录下的 ~/.codecatalyst/workflows/ 文件夹中。该文件的扩展名可以为 .yml 或 .yaml，并且扩展名必须小写。

要创建和编辑工作流定义文件，可以使用 vim 等编辑器，也可以使用 CodeCatalyst 控制台的可视化编辑器或 YAML 编辑器。有关更多信息，请参阅使用 CodeCatalyst 控制台的可视化编辑器和 YAML 编辑器。

注意

接下来的大多数 YAML 属性在可视化编辑器中都有对应的 UI 元素。要查找 UI 元素，请使用 Ctrl+F。该元素将与其关联的 YAML 属性一起列出。

工作流定义文件示例

下面是一个简单的工作流定义文件示例。该示例包括几个顶级属性、一个 Triggers 部分和一个包含 Build 和 Test 这两个操作的 Actions 部分。有关更多信息，请参阅关于工作流定义文件。


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 规范，因此该规范中允许的内容在工作流 YAML 中也是允许的。如果您不熟悉 YAML，这里有一些快速指南，可确保您提供有效的 YAML 代码。

区分大小写：工作流定义文件区分大小写，因此请确保使用本文档中显示的大小写。
特殊字符：我们建议使用引号或双引号将包含以下任意特殊字符的属性值引起来：{、}、[、]、&、*、#、?、|、-、<、>、=、!、%、@、:、` 和 ,

如果不加引号，前面列出的特殊字符可能会以意想不到的方式解释。
属性名称：属性名称（相对于属性值）仅限于字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（_）。不允许使用空格。不能使用引号或双引号在属性名称中启用特殊字符和空格。

不允许：

'My#Build@action'

My#Build@action

My Build Action

允许：

My-Build-Action_1
转义码：如果您的属性值包含转义码（如 \n 或 \t），请遵循以下准则：
- 使用单引号以字符串形式返回转义码。例如，'my string \n my string' 返回 my string \n my string 字符串。
- 使用双引号解析转义码。例如，"my string \n my new line" 返回：
```
my string
my new line
```

注释：在注释前加上 #。

示例：


Name: MyWorkflow
# This is a comment.
SchemaVersion: 1.0

三连线符（---）：不要在 YAML 代码中使用 ---。CodeCatalyst 会忽略 --- 之后的所有内容。

命名约定

在本指南中，我们使用属性和部分两词来指代工作流定义文件中的主要项目。

属性是任何包含冒号（:）的项目。例如，在下面的代码片段中，以下所有项都是属性：Name、SchemaVersion、RunMode、Triggers、Type 和 Branches。
部分是任何具有子属性的属性。在下面的代码片段中，有一个 Triggers 部分。

注意
在本指南中，“部分”有时被称为“属性”，反之亦然，视上下文而定。
```
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）、连字符（-）和下划线（_）。不允许使用空格。不能使用引号在工作流名称中启用特殊字符和空格。

对应的 UI：可视化编辑器/工作流属性/工作流名称

SchemaVersion

（必需）

工作流定义的架构版本。目前唯一有效的值是 1.0。

对应的 UI：无

RunMode

（可选）

CodeCatalyst 如何处理多个运行。可以使用下列值之一：

QUEUED – 多个运行排队并一个接一个地运行。一个队列中最多可包含 50 个运行。
SUPERSEDED – 多个运行排队并一个接一个地运行。一个队列只能有一个运行，因此如果两个运行同时出现在同一个队列中，则后一个运行将取代（接替）前一个运行，而前一个运行将被取消。
PARALLEL – 同时进行多个运行。

如果省略该属性，则默认值为 QUEUED。

有关更多信息，请参阅配置运行的排队行为。

对应的 UI：可视化编辑器/工作流属性/高级/运行模式

Compute

（可选）

用于运行工作流操作的计算引擎。您可以在工作流级别或操作级别指定计算，但不能同时在这两个级别指定计算。在工作流级别指定计算时，计算配置将应用于工作流中定义的所有操作。在工作流级别，您还可以在同一个实例上运行多个操作。有关更多信息，请参阅跨操作共享计算。

有关计算的更多信息，请参阅配置计算和运行时映像。

对应的 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 编辑器）

优化了操作启动速度。

有关计算类型的更多信息，请参阅计算类型。

对应的 UI：可视化编辑器/工作流属性/高级/计算类型

Fleet

(Compute/Fleet)

（可选）

指定将运行您的工作流或工作流操作的计算机或实例集。对于按需实例集，当操作开始时，工作流会预置操作所需的资源，操作完成后计算机就会被销毁。按需实例集的示例：Linux.x86-64.Large、Linux.x86-64.XLarge。有关按需实例集的更多信息，请参阅按需实例集属性。

使用预置的实例集，您可以配置一组专用计算机来运行工作流操作。这些计算机保持空闲状态，可随时开始立即处理操作。有关预置实例集的更多信息，请参阅预置实例集属性。

如果省略 Fleet，则默认值为 Linux.x86-64.Large。

有关计算实例集的更多信息，请参阅计算实例集。

对应的 UI：可视化编辑器/工作流属性/高级/计算实例集

SharedInstance

(Compute/SharedInstance)

（可选）

为您的操作指定计算共享功能。通过计算共享，工作流中的操作会在同一个实例（运行时环境映像）上运行。可以使用下列值之一：

TRUE 表示工作流操作之间共享运行时环境映像。
FALSE 表示为工作流中的每个操作启动和使用单独的运行时环境映像，因此如果没有额外的配置，就无法共享构件和变量等资源。

有关计算共享的更多信息，请参阅跨操作共享计算。

对应的 UI：无

Triggers

（可选）

该工作流的一个或多个触发器序列。如果未指定触发器，则必须手动启动工作流。

有关触发器的更多信息，请参阅使用触发器自动启动工作流运行。

对应的 UI：可视化编辑器/工作流程图/触发器


Name: MyWorkflow
SchemaVersion: 1.0
...
Triggers:
  - Type: PUSH
    Branches:
      - branch-name
    FilesChanged:
      - folder1/file
      - folder2/
 
  - Type: PULLREQUEST
    Events:
      - OPEN
      - CLOSED
      - REVISION
    Branches:
      - branch-name
    FilesChanged:
      - file1.txt
      
  - Type: SCHEDULE
    # Run the workflow at 10:15 am (UTC+0) every Saturday
    Expression: "15 10 ? * 7 *"
    Branches:
      - branch-name

Type

(Triggers/Type)

（设置了 Triggers 时是必需的）

指定触发器的类型。可以使用下列值之一：

推送（可视化编辑器）或 PUSH（YAML 编辑器）

当更改推送到源存储库时，推送触发器会启动工作流运行。工作流运行将使用您推送到的分支（即目标分支）中的文件。
拉取请求（可视化编辑器）或 PULLREQUEST（YAML 编辑器）

在源存储库中打开、更新或关闭拉取请求时，拉取请求触发器会启动工作流运行。工作流运行将使用您拉取自的分支（即源分支）中的文件。
计划（可视化编辑器）或 SCHEDULE（YAML 编辑器）

计划触发器按您指定的 cron 表达式定义的计划来启动工作流运行。对于源存储库中的每个分支，将使用分支的文件启动单独的工作流运行。[要限制在其上激活触发器的分支，请使用分支字段（可视化编辑器）或 Branches 属性（YAML 编辑器）。]

配置计划触发器时，请遵循以下指南：
- 每个工作流只能使用一个计划触发器。
- 如果您在 CodeCatalyst 空间中定义了多个工作流，我们建议您计划同时启动的工作流不要超过 10 个。
- 确保将触发器的 cron 表达式配置为在两次运行之间留出足够的时间。有关更多信息，请参阅 Expression。

有关示例，请参阅示例：工作流中的触发器。

对应的 UI：可视化编辑器/工作流程图/触发器/触发器类型

Events

(Triggers/Events)

（如果触发器 Type 设置为 PULLREQUEST，则是必需的）

指定将启动工作流运行的拉取请求事件的类型。有效值如下所示：

拉取请求已创建（可视化编辑器）或 OPEN（YAML 编辑器）

工作流运行将在拉取请求创建后启动。
拉取请求已关闭（可视化编辑器）或 CLOSED（YAML 编辑器）

工作流运行将在拉取请求关闭后启动。CLOSED 事件的行为不太好说明，最好通过一个例子来理解。请参阅示例：带有拉取、分支和“CLOSED”事件的触发器了解更多信息。
对拉取请求进行了新的修订（可视化编辑器）或 REVISION（YAML 编辑器）

工作流运行将在对拉取请求的修订创建后启动。在创建拉取请求时，将创建第一个修订。之后，每当有人将新的提交推送到拉取请求中指定的源分支时，就会创建一个新的修订。如果您在拉取请求触发器中包含 REVISION 事件，则可以忽略 OPEN 事件，因为 REVISION 是 OPEN 的超集。

您可以在同一个拉取请求触发器中指定多个事件。

有关示例，请参阅示例：工作流中的触发器。

对应的 UI：可视化编辑器/工作流程图/触发器/拉取请求事件

Branches

(Triggers/Branches)

（可选）

指定触发器监控的源存储库中的分支，以便知道何时启动工作流运行。您可以使用正则表达式模式来定义分支名称。例如，使用 main.* 来匹配以 main 开头的所有分支。

根据触发器的类型，要指定的分支会有所不同：

对于推送触发器，请指定要推送至的分支，即目标分支。对于每个匹配的分支，将使用匹配分支中的文件，启动一个工作流运行。

示例：main.*、mainline
对于拉取请求触发器，请指定要推送至的分支，即目标分支。对于每个匹配的分支，将使用工作流定义文件和源分支（不是匹配的分支）中的文件，启动一个工作流运行。

示例：main.*、mainline、v1\-.*（匹配以 v1- 开头的分支）
对于计划触发器，请指定包含您希望计划运行使用的文件的分支。对于每个匹配的分支，将使用工作流定义文件和匹配分支中的源文件，启动一个工作流运行。

示例：main.*、version\-1\.0

注意

如果您未指定分支，则触发器会监控源存储库中的所有分支，并将使用以下位置中的工作流定义文件和源文件启动工作流运行：

您要推送至的分支（对于推送触发器）。有关更多信息，请参阅示例：一个简单的代码推送触发器。
您要拉取自的分支（对于拉取请求触发器）。有关更多信息，请参阅示例：一个简单的拉取请求触发器。
所有分支（对于计划触发器）。源存储库中的每个分支将启动一个工作流运行。有关更多信息，请参阅示例：一个简单的计划触发器。

有关分支和触发器的更多信息，请参阅触发器和分支的使用准则。

有关更多示例，请参阅示例：工作流中的触发器。

对应的 UI：可视化编辑器/工作流程图/触发器/分支

FilesChanged

(Triggers/FilesChanged)

（如果触发器 Type 设置为 PUSH 或 PULLREQUEST，则为可选的。如果触发器 Type 设置为 SCHEDULE，则不受支持。）

指定触发器监控的源存储库中的文件或文件夹，以便知道何时启动工作流运行。您可以使用正则表达式来匹配文件名或路径。

有关示例，请参阅示例：工作流中的触发器。

对应的 UI：可视化编辑器/工作流程图/触发器/文件已更改

Expression

(Triggers/Expression)

（如果触发器 Type 设置为 SCHEDULE，则是必需的）

指定 cron 表达式，用于描述您希望何时执行计划的工作流运行。

CodeCatalyst 中的 Cron 表达式使用以下六个字段的语法，使用空格分隔每个字段：

分钟 小时 一个月中的第几天 月份 星期几 年

cron 表达式示例

分钟	小时	一个月中的第几天	月	星期几	年	含义
0	0	?	*	MON-FRI	*	每个星期一到星期五的午夜（UTC+0）运行工作流。
0	2	*	*	?	*	每天凌晨 2:00（UTC+0）运行工作流。
15	22	*	*	?	*	每天晚上 10:15（UTC+0）运行工作流。
0/30	22-2	?	*	SAT-SUN	*	星期六至星期日，从起始日晚上 10:00 至次日凌晨 2:00（UTC+0）每隔 30 分钟运行一次工作流。
45	13	L	*	?	2023-2027	2023 年至 2027 年（含）之间，在每个月的最后一天下午 1:45（UTC+0）运行工作流。

在 CodeCatalyst 中指定 cron 表达式时，请务必遵循以下准则：

为每个 SCHEDULE 触发器指定一个 cron 表达式。
在 YAML 编辑器中，将 cron 表达式用双引号（"）括起来。
使用协调世界时（UTC）格式指定时间。不支持其他时区。
两次运行之间应至少配置 30 分钟的运行间隔。不支持更快的节奏。
指定一个月中的第几天或者星期几，但不能同时指定两者。如果您在其中一个字段中指定值或星号（*），则必须在另一个字段中使用问号（?）。星号表示“全部”，问号表示“任何”。

有关 cron 表达式的更多示例和通配符（例如 ?、* 和 L）的信息，请参阅《Amazon EventBridge 用户指南》中的 Cron 表达式参考。EventBridge 和 CodeCatalyst 中的 Cron 表达式的工作方式完全相同。

有关计划触发器的示例，请参阅示例：工作流中的触发器。

对应的 UI：可视化编辑器/工作流程图/触发器/计划

操作

该工作流的一个或多个操作序列。CodeCatalyst 支持多种操作类型，如构建和测试操作，它们提供了不同类型的功能。每种操作类型都有：

表示操作的唯一硬编码 ID 的 Identifier 属性。例如，aws/build@v1 标识构建操作。
包含特定于操作的属性的 Configuration 部分。

有关每种操作类型的更多信息，请参阅操作类型。操作类型主题有每个操作的文档链接。

以下是工作流定义文件中操作和操作组的 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 语法准则。

有关操作命名惯例（包括限制）的更多信息，请参阅 action-or-gate-name。

对应的 UI：可视化编辑器/action-name/配置选项卡/操作名称或操作显示名称

action-group-name

（Actions/action-group-name）

（可选）

一个操作组包含一个或多个操作。将操作分组为操作组有助于将工作流保持得井井有条，还可以配置不同组之间的依赖关系。

将 action-group-name 替换为您要为操作组提供的名称。操作组名称在工作流中必须是唯一的，并且只能包含字母数字字符、连字符和下划线。有关语法规则的更多信息，请参阅 YAML 语法准则。

有关操作组的更多信息，请参阅将操作分组为操作组。

对应的 UI：无

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

工作流状态

跟踪和整理有关事务的工作