Workflow definition reference

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

A workflow definition file is a YAML file that describes your workflow. 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.

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
• Syntax guidelines and conventions
• Top-level properties
• Build and test action reference
• "Amazon S3 publish" action reference
• "AWS CDK bootstrap" action reference
• "AWS CDK deploy" action reference
• "AWS Lambda invoke" action reference
• "Deploy AWS CloudFormation stack" action reference
• "Deploy to Amazon ECS" action reference
• "GitHub Actions" action reference
• "Render Amazon ECS task definition" action reference

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.

• Case-sensitivity: The workflow definition file is case-sensitive, so make sure you use the casing shown in this documentation.

• Special characters: We recommend using quotes or double-quotes around property values that include any of the following special characters: {, } , [ , ] , &, * , # , ? , | , - , < , >, = , ! , % , @ , : , ` and ,

  If you don't include the quotes, the special characters listed previously may be interpreted in an unexpected way.

• Property names: Property names (as opposed to property values) are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). Spaces are not allowed. You cannot use quotes or double-quotes to enable special characters and spaces in property names.

  Not permitted:

  'My#Build@action'

  My#Build@action

  My Build Action

  Permitted:

  My-Build-Action_1

• Escape codes: If your property value includes escape codes (for example, \n or \t), follow these guidelines:

  • Use single quotes to return the escape code as a string. For example, 'my string \n my string', returns the string my string \n my string.

  • Use double quotes to parse the escape code. For example, "my string \n my new line", returns:

    my string
    my new line

• Comments: Preface comments with #.

  Example:

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

• Triple dash (---): Do not use --- in your YAML code. CodeCatalyst ignores everything after the ---.

Naming conventions

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

• A property is any item that includes a colon (:). For example, in the following code snippet, all of the following are properties: Name, SchemaVersion, RunMode, Triggers, Type, and Branches.

• A section is any property that has sub-properties. In the following code snippet, there is one Triggers section.

  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