Top-level properties
The following is the reference documentation for the top-level properties in the workflow definition file.
# Name
Name: workflow-name
# Schema version
SchemaVersion: 1.0
# Run mode
RunMode: QUEUED|SUPERSEDED|PARALLEL
# Compute
Compute:
...
# Triggers
Triggers:
...
# Actions
Actions:
...
Name
(Required)
The name of the workflow. The workflow name is shown in the workflows list and mentioned in notifications and logs. The workflow name and workflow definition file name can match, or you can name them differently. Workflow names do not need to be unique. Workflow names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in workflow names.
Corresponding UI: visual editor/Workflow properties/Workflow name
SchemaVersion
(Required)
The schema version of the workflow definition. Currently, the only valid value
is 1.0
.
Corresponding UI: none
RunMode
(Optional)
How CodeCatalyst handles multiple runs. You can use one of the following values:
-
QUEUED
– Multiple runs are queued and run one after the other. You can have up to 50 runs in a queue. -
SUPERSEDED
– Multiple runs are queued and run one after the other. A queue can only have one run, so if two runs end up together in the same queue, the later run supersedes (takes over from) the earlier run, and the earlier run is canceled. -
PARALLEL
– Multiple runs occur simultaneously.
If this property is omitted, the default is
QUEUED
.
For more information, see Configuring queued, superseded, and parallel runs.
Corresponding UI: visual editor/Workflow properties/Advanced/Run mode
Compute
(Optional)
The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. This compute is not shared however, as a separate compute is spun up for each action.
For more information about compute, see Working with compute and runtime environment Docker images.
Corresponding UI: none
Name: MyWorkflow
SchemaVersion: 1.0
...
Compute:
- Type: EC2 | Lambda
- Fleet: fleet-name
- SharedInstance: true | false
Type
(Compute/Type)
(Required if Compute
is set)
The type of compute engine. You can use one of the following values:
-
EC2 (visual editor) or
EC2
(YAML editor)Optimized for flexibility during action runs.
-
Lambda (visual editor) or
Lambda
(YAML editor)Optimized action start-up speeds.
For more information about compute types, see About compute types.
Corresponding UI: visual editor/Workflow properties/Advanced/Compute type
Fleet
(Compute/Fleet)
(Optional)
Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: Linux.x86-64.Large
, Linux.x86-64.XLarge
. For more information about on-demand fleets, see On-demand fleet properties.
With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see Provisioned fleet properties.
If Fleet
is omitted, the default is Linux.x86-64.Large
.
For more information about compute fleets, see About compute fleets.
Corresponding UI: visual editor/Workflow properties/Advanced/Compute fleet
Triggers
(Optional)
A sequence of one or more triggers for this workflow. If a trigger is not specified, then you must manually start your workflow.
For more information about triggers, see Working with triggers.
Corresponding UI: visual editor/workflow diagram/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.ext
Type
(Triggers/Type)
(Required if Triggers
is set)
The type of trigger. You can use one of the following values:
-
Push (visual editor) or
PUSH
(YAML editor)A push trigger starts a workflow run when code is pushed to your source repository.
-
Pull request (visual editor) or
PULLREQUEST
(YAML editor)A pull request trigger starts a workflow run when a pull request is opened or updated against your source repository.
Note
Pull request triggers are not supported if you are using a GitHub repository in your workflow. For more information, see Using GitHub repositories in CodeCatalyst workflows.
Note
Currently, push and pull request triggers only support the
WorkflowSource
source repository. For more information, see Working with sources.
Corresponding UI: visual editor/workflow diagram/Triggers/Trigger type
Events
(Triggers/Events)
(Required if the trigger Type
is set to PULLREQUEST
,
otherwise not supported)
Specify the type of pull request events that will start a workflow run. The following are the valid values:
-
Pull request is created (visual editor) or
OPEN
(YAML editor)The workflow run is started when a pull request is created.
-
Pull request is closed (visual editor) or
CLOSED
(YAML editor)The workflow run is started when a pull request is closed.
-
New revision is made to pull request (visual editor) or
REVISION
(YAML editor)The workflow run is started when a new revision is made to a pull request.
You can specify multiple events.
For more information and examples, see Working with triggers.
Corresponding UI: visual editor/workflow diagram/Triggers/Events for pull request
Branches
(Triggers/Branches)
(Optional)
Specify the branches in your source repository that the trigger monitors in order to know
when to start a workflow run. The branches are the destination branches that you will push
to, or create pull requests against. Examples: main
, mainline
. You
can specify multiple branches, and you can use regex to define your branch names. For
example, use main.*
to match all branches beginning with
main
.
For more information and examples, see Working with triggers.
Corresponding UI: visual editor/workflow diagram/Triggers/Branches
FilesChanged
(Triggers/FilesChanged)
(Optional)
Specify the files or folders in your source repository that the trigger monitors in order to know when to start a workflow run. You can use regular expressions to match file names or paths.
For more information and examples, see Working with triggers.
Corresponding UI: visual editor/workflow diagram/Triggers/Files changed
Actions
A sequence of one or more actions for this workflow. CodeCatalyst supports several action types, such as build and test actions, which offer different types of functionality. Each action type has:
-
an
Identifier
property that indicates the action's unique, hard-coded ID. For example,aws/build@v1
identifies the build action. -
a
Configuration
section that contains properties that are specific to the action.
For more information about each action type, see its reference documentation, available in the Workflow definition reference.
The following is the YAML reference for actions and action groups in the workflow definition file.
For more information about actions, see Working with actions.
Name: MyWorkflow
SchemaVersion: 1.0
...
Actions:
action-name
:
Identifier: action-identifier
Configuration:
...
#Action groups
action-group-name:
Actions:
...
action-name
(Actions/action-name
)
(Required)
Replace action-name
with a name you want to give the
action. Action names must be unique within the workflow, and must only include
alphanumeric characters, hyphens, and underscores. For more information about syntax rules,
see YAML syntax guidelines.
For more information about naming practices for actions, including restrictions, see the action-name.
Corresponding UI: visual editor/action-name
/Configuration
tab/Action name or Action display
name
action-group-name
(Actions/action-group-name
)
(Optional)
An action group contains one or more actions. Grouping actions into action groups helps you keep your workflow organized, and also allows you to configure dependencies between different groups of actions.
Replace action-group-name
with a name you want to give the
action group. Action group names must be unique within the workflow, and must only
include alphanumeric characters, hyphens, and underscores. For more information about
syntax rules, see YAML syntax guidelines.
For more information about action groups, see Grouping actions into action groups.
Corresponding UI: none