Workflow YAML definition - Amazon CodeCatalyst (original) (raw)

The following is the reference documentation for the workflow definition file.

A workflow definition file is a YAML file that describes your workflow. By default, the file is stored in a ~/.codecatalyst/workflows/ folder in the root of your source repository. The file can have a .yml or .yaml extension, and the extension must be lowercase.

To create and edit the workflow definition file, you can use an editor such as vim, or you can use the CodeCatalyst console's visual editor or YAML editor. For more information, see Using the CodeCatalyst console's visual and YAML editors.

Note

Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use Ctrl+F. The element will be listed with its associated YAML property.

Topics

Example of a workflow definition file

The following is an example of a simple workflow definition file. It includes a few top-level properties, a Triggers section, and an Actions section with two actions: Build and Test. For more information, see About the workflow definition file.

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

Syntax guidelines and conventions

This section describes the syntax rules for the workflow definition file, as well as the naming conventions used in this reference documentation.

YAML syntax guidelines

The workflow definition file is written in YAML and follows the YAML 1.1 specification, so whatever is allowed in that specification is also allowed in the workflow YAML. If you're new to YAML, here are some quick guidelines to ensure you're supplying valid YAML code.

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

Naming conventions

In this guide, we use the terms property and_section_ to refer to the main items in a workflow definition file.

Note

In this guide, 'sections' are sometimes referred to as 'properties', and vise versa, depending on the context. 

Name: MyWorkflow  
SchemaVersion: 1.0  
RunMode: QUEUED  
Triggers:  
  - Type: PUSH  
    Branches:  
      - main

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:

If this property is omitted, the default isQUEUED.

For more information, see Configuring the queuing behavior of 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. At the workflow level, you can also run multiple actions on the same instance. For more information, see Sharing compute across actions.

For more information about compute, see Configuring compute and runtime 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:

For more information about compute types, see 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 Compute fleets.

Corresponding UI: visual editor/Workflow properties/Advanced/Compute fleet

SharedInstance

(Compute/SharedInstance)

(Optional)

Specify the compute sharing capability for your actions. With compute sharing, actions in a workflow run on the same instance (runtime environment image). You can use one of the following values:

For more information about compute sharing, see Sharing compute across actions.

Corresponding UI: none

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 Starting a workflow run automatically using 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.txt
      
  - Type: SCHEDULE
    # Run the workflow at 10:15 am (UTC+0) every Saturday
    Expression: "15 10 ? * 7 *"
    Branches:
      - branch-name

Type

(Triggers/Type)

(Required if Triggers is set)

Specify the type of trigger. You can use one of the following values:

For examples, see Examples: Triggers in workflows.

Corresponding UI: visual editor/workflow diagram/Triggers/Trigger type

Events

(Triggers/Events)

(Required if the trigger Type is set to PULLREQUEST)

Specify the type of pull request events that will start a workflow run. The following are the valid values:

You can specify multiple events in the same pull request trigger.

For examples, see Examples: Triggers in workflows.

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. You can use regex patterns to define your branch names. For example, use main.* to match all branches beginning withmain.

The branches to specify are different depending on the trigger type:

Note

If you don't specify branches, the trigger monitors all branches in your source repository, and will start a workflow run using the workflow definition file and source files in:

For more information about branches and triggers, see Usage guidelines for triggers and branches.

For more examples, see Examples: Triggers in workflows.

Corresponding UI: visual editor/workflow diagram/Triggers/Branches

FilesChanged

(Triggers/FilesChanged)

(Optional if the trigger Type is set to PUSH, orPULLREQUEST. Not supported if the trigger Type is set toSCHEDULE.)

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 examples, see Examples: Triggers in workflows.

Corresponding UI: visual editor/workflow diagram/Triggers/Files changed

Expression

(Triggers/Expression)

(Required if the trigger Type is set to SCHEDULE)

Specify the cron expression that describes when you want your scheduled workflow runs to occur.

Cron expressions in CodeCatalyst use the following six-field syntax, where each field is separated by a space:

minutes hours days-of-month month days-of-week year

Examples of cron expressions

Minutes Hours Days of month Month Days of week Year Meaning
0 0 ? * MON-FRI * Runs a workflow at midnight (UTC+0) every Monday through Friday.
0 2 * * ? * Runs a workflow at 2:00 am (UTC+0) every day.
15 22 * * ? * Runs a workflow at 10:15 pm (UTC+0) every day.
0/30 22-2 ? * SAT-SUN * Runs a workflow every 30 minutes Saturday through Sunday between 10:00 pm on the starting day and 2:00 am on the following day (UTC+0).
45 13 L * ? 2023-2027 Runs a workflow at 1:45 pm (UTC+0) on the last day of the month between the years 2023 and 2027 inclusive.

When specifying cron expressions in CodeCatalyst, make sure you follow these guidelines:

For more examples of cron expressions and information about wildcards like ?,*, and L, see the Cron expressions reference in the Amazon EventBridge User Guide. Cron expressions in EventBridge and CodeCatalyst work exactly the same way.

For examples of schedule triggers, see Examples: Triggers in workflows.

Corresponding UI: visual editor/workflow diagram/Triggers/Schedule

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:

For more information about each action type, see Action types. The Action types topic has links into the documentation for each action.

The following is the YAML reference for actions and action groups in the workflow definition file.

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)

(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-or-gate-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.

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