Build, test, and deploy with workflows in CodeCatalyst - Amazon CodeCatalyst

Amazon CodeCatalyst is in preview release and is subject to change.

Build, test, and deploy with workflows in CodeCatalyst

After writing your application code in a CodeCatalyst Dev Environment and pushing it to your CodeCatalyst source repository, you are ready to deploy it into AWS. The way to do this automatically is through a workflow.

A workflow is an automated procedure that describes how to build, test, and deploy your code as part of a continuous integration and continuous delivery (CI/CD) system. A workflow defines a series of steps, or actions, to take during a workflow run. A workflow also defines the events, or triggers, that cause the workflow to start. To set up a workflow, you create a workflow definition file using the CodeCatalyst console's visual or YAML editor.

About the workflow definition file

A workflow definition file is a YAML file that describes your workflow. The file is stored in an ~/.codecatalyst/workflows/ folder in the root of your source repository. The file can have a .yml or .yaml extension.

The following is an example of a simple workflow definition file. Each line is explained following the example.

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 .
Line Description
Name: MyWorkflow

Specifies the name of the workflow. For more information on the Name property, see Top-level properties.

SchemaVersion: 1.0

Specifies the workflow schema version. For more information on the SchemaVersion property, see Top-level properties.


Indicates how CodeCatalyst handles multiple runs. For more information on the run mode, see Configuring queued, superseded, and parallel runs.


Specifies the logic that will cause a workflow run to start. For more information on triggers, see Working with triggers.

- Type: PUSH Branches: - main

Indicates that the workflow must start whenever you push code to the main branch of the default source repository. For more information on the workflow source, see Working with sources.


Defines the tasks to perform during a workflow run. In this example, the Actions section defines a single action called Build. For more information on actions, see Working with actions.


Defines the properties for the Build action. For more information on the build action, see Building using workflows in CodeCatalyst.

Identifier: aws/build@v1

Specifies the unique, hard-coded identifier for the build action.

Inputs: Sources: - WorkflowSource

Indicates that the build action should look in the WorkflowSource source repository to find the files it needs to complete its processing. For more information, see Working with sources.


Contains the configuration properties that are specific to the build action.

Steps: - Run: docker build -t MyApp:latest .

Tells the build action to build a Docker image called MyApp and tag it with latest.

For a complete list of all the properties available in the workflow definition file, see the Workflow definition reference.

Using the CodeCatalyst console's visual and YAML editors

To create and edit the workflow definition file, you can use your preferred editor, but we recommend using the CodeCatalyst console's visual editor or YAML editor. These editors offer helpful file validation to ensure YAML property names, values, nesting, spacing, capitalization, and so on, are correct.

The following image shows a workflow in the visual editor. The visual editor offers you a complete user interface through which to create and configure your workflow definition file. The visual editor includes a workflow diagram (1) showing the workflow's main components, and a configuration area (2).

        Workflow visual editor

Alternatively, you can use the YAML editor, shown in the next image. Use the YAML editor to paste in large code blocks (from a tutorial, for example), or to add advanced properties that are not offered through the visual editor.

        Workflow YAML editor

You can toggle from the visual editor to the YAML editor to see the effect that your configurations have on the underlying YAML code.

Discovering workflows

You can view your workflow on the workflows landing page, along with other workflows you've set up in the same project.

The following image shows the workflows landing page. It is populated with two workflows: UnitTests and BuildToProd. You can see that both have been run a few times. You can choose View all runs to quickly see the run history, or you can click on the name of the workflow to see the workflow's YAML code and other detailed information.

        Workflow logs

Viewing workflow run details

You can view the details of a workflow run by clicking on the run in the workflow landing page.

The following image shows the details of a workflow run called Run-45f27 that was started automatically on a commit to source. The workflow diagram indicates that an action has failed (1). You can navigate to the logs (2) to view the detailed log messages and troubleshoot issues. For more information on workflow runs, see Working with runs.

        Workflow logs

Next steps

To learn more about workflows concepts, see Workflows concepts.

To create your first workflow, see Getting started with workflows in CodeCatalyst.