工作流程 YAML 定义

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

工作流程定义文件是描述您的工作流程的 YAML 文件。该文件存储在源存储库根目录下的~/.codecatalyst/workflows/文件夹中。该文件的扩展名可以是.yml 或.yaml。

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

注意

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

工作流程定义文件示例

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


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

Triple dash (---)：不要---在你的 YAML 代码中使用。 CodeCatalyst 忽略之后的所有内容。---

命名约定

在本指南中，我们使用术语属性和章节来指代工作流程定义文件中的主要项目。

属性是任何包含冒号 (:) 的项目。例如，在以下代码片段中，以下所有属性均为属性：Name、SchemaVersion、RunMode、TriggersType、和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）、连字符 (-) 和下划线 (_)。不允许使用空格。不能使用引号在工作流程名称中启用特殊字符和空格。

对应的用户界面：可视化编辑器/工作流程属性/工作流程名称

SchemaVersion

（必需）

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

对应的用户界面：无

RunMode

（可选）

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

QUEUED— 多个运行排队并一个接一个地运行。一个队列中最多可以运行 50 次。
SUPERSEDED— 多个运行排队并一个接一个地运行。一个队列只能运行一次，因此，如果两次运行最终在同一个队列中，则较晚的运行将取代（接管）先前的运行，而较早的运行将被取消。
PARALLEL— 同时进行多次运行。

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

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

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

Compute

（可选）

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

有关计算的更多信息，请参阅为工作流程配置计算和运行时环境 Docker 镜像。

对应的用户界面：无


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

优化了动作启动速度。

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

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

Fleet

(Compute/Fleet)

（可选）

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

使用已配置的队列，您可以配置一组专用计算机来运行您的工作流程操作。这些计算机处于闲置状态，可以立即处理操作。有关已配置队列的更多信息，请参阅。已配置的舰队属性

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

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

相应的用户界面：可视化编辑器/工作流属性/高级/计算队列

SharedInstance

(Compute/SharedInstance)

（可选）

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

TRUE表示运行时环境图像在工作流程操作之间共享。
FALSE意味着启动一个单独的运行时环境映像并将其用于工作流程中的每个操作，因此，如果没有额外的配置，您就无法共享工件和变量等资源。

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

对应的用户界面：无

Triggers

（可选）

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

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

相应的用户界面：可视化编辑器/工作流程图/触发器


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。

有关示例，请参阅触发器示例。

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

Events

(Triggers/Events)

（如果触发器设置为，Type则为必填项PULLREQUEST）

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

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

创建拉取请求后，工作流程就会启动。
拉取请求已关闭（可视化编辑器）或CLOSED（YAML 编辑器）

当拉取请求关闭时，工作流程就会开始运行。CLOSED事件的行为很棘手，最好通过一个例子来理解。请参阅示例：带有拉动、分支和 “CLOSED” 事件的触发器了解更多信息。
对拉取请求（可视化编辑器）或REVISION（YAML 编辑器）进行了新的修订

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

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

有关示例，请参阅触发器示例。

相应的用户界面：可视化编辑器/工作流程图/触发器/拉取请求事件

Branches

(Triggers/Branches)

（可选）

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

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

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

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

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

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

注意

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

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

有关分支和触发器的更多信息，请参阅分支时的触发注意事项。

有关更多示例，请参阅触发器示例。

相应的用户界面：可视化编辑器/工作流程图/触发器/分支

FilesChanged

(Triggers/FilesChanged)

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

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

有关示例，请参阅触发器示例。

相应的用户界面：可视化编辑器/工作流程图/触发器/文件已更改

Expression

(Triggers/Expression)

（如果触发器设置为，Type则为必填项SCHEDULE）

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

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

分钟小时days-of-month月份days-of-week年份

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	*	周六至周日每隔 30 分钟运行一次工作流程，时间为起始日晚上 10:00 至次日凌晨 2:00（UTC+0）。
45	13	L	*	?	2023-2027	在 2023 年至 2027 年（含）之间的当月最后一天下午 1:45（UTC+0）运行工作流程。

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

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

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

有关计划触发器的示例，请参阅触发器示例。

相应的用户界面：可视化编辑器/工作流程图/触发器/计划

操作

此工作流程的一个或多个操作序列。 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)

（必需）

将操作名称替换为要赋予操作的名称。操作名称在工作流程中必须是唯一的，并且只能包含字母数字字符、连字符和下划线。有关语法规则的更多信息，请参阅YAML 语法指南。

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

对应的用户界面：可视化编辑器/ 操作名称 /配置选项卡/ 操作名称或操作显示名称

action-group-name

(Actions/action-group-name)

（可选）

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

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

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

对应的用户界面：无

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

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

文档惯例

工作流程状态

跟踪和组织有问题的工作