Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).

# Build, test, and deploy with workflows
<a name="workflow"></a>

After writing your application code in a [CodeCatalyst Dev Environment](devenvironment.md) and pushing it to your [CodeCatalyst source repository](source.md), you're ready to deploy it. 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](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors).

**Tip**  
For a quick look at how you might use workflows in a project, [create a project with a blueprint](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template). Each blueprint deploys a functioning workflow that you can review, run, and experiment with.

## About the workflow definition file
<a name="workflow.example"></a>

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](source-repositories.md). The file can have a .yml or .yaml extension, and the extension must be lowercase.

The following is an example of a simple workflow definition file. We explain each line of this example in the table that follows.

```
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 | 
| --- | --- | 
|  <pre>Name: MyWorkflow</pre>  |  Specifies the name of the workflow. For more information about the `Name` property, see [Top-level properties](workflow-reference.md#workflow.top.level).  | 
|  <pre>SchemaVersion: 1.0</pre>  |  Specifies the workflow schema version. For more information about the `SchemaVersion` property, see [Top-level properties](workflow-reference.md#workflow.top.level).  | 
|  <pre>RunMode: QUEUED</pre>  |  Indicates how CodeCatalyst handles multiple runs. For more information about the run mode, see [Configuring the queuing behavior of runs](workflows-configure-runs.md).  | 
|  <pre>Triggers:</pre>  |  Specifies the logic that will cause a workflow run to start. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).   | 
|  <pre>- Type: PUSH<br />  Branches:<br />    - main</pre>  |  Indicates that the workflow must start whenever you push code to the `main` branch of the default source repository. For more information about the workflow source, see [Connecting source repositories to workflows](workflows-sources.md).  | 
|  <pre>Actions:</pre>  |  Defines the tasks to perform during a workflow run. In this example, the `Actions` section defines a single action called `Build`. For more information about actions, see [Configuring workflow actions](workflows-actions.md).  | 
|  <pre>Build:</pre>  |  Defines the properties for the `Build` action. For more information about the build action, see [Building with workflows](build-workflow-actions.md).  | 
|  <pre>Identifier: aws/build@v1</pre>  |  Specifies the unique, hard-coded identifier for the build action.  | 
|  <pre>Inputs:<br />  Sources:<br />    - WorkflowSource</pre>  |  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 [Connecting source repositories to workflows](workflows-sources.md).  | 
|  <pre>Configuration:</pre>  |  Contains the configuration properties that are specific to the build action.  | 
|  <pre>Steps:<br />  - Run: docker build -t MyApp:latest .</pre>  |  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 YAML definition](workflow-reference.md).

## Using the CodeCatalyst console's visual and YAML editors
<a name="workflow.editors"></a>

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 help 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\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/workflow-visual-editor.png)


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\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/workflow-yaml-editor.png)


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
<a name="workflow.discovering"></a>

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

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

![\[Workflow logs\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/workflow-list.png)


## Viewing workflow run details
<a name="workflow.runs"></a>

You can view the details of a workflow run by choosing the run in the **Workflows** summary page.

The following image shows the details of a workflow run called **Run-cc11d** 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 about workflow runs, see [Running a workflow](workflows-working-runs.md).

![\[Workflow logs\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/workflow-visual-logs.png)


## Next steps
<a name="workflow.next"></a>

To learn more about workflows concepts, see [Workflows concepts](workflows-concepts.md).

To create your first workflow, see [Getting started with workflows](workflows-getting-started.md).

# Workflows concepts
<a name="workflows-concepts"></a>

Here are some concepts and terms to know when building, testing, or deploying your code with workflows in CodeCatalyst.

## Workflows
<a name="workflows-concepts-workflows"></a>

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](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors).

**Tip**  
For a quick look at how you might use workflows in a project, [create a project with a blueprint](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template). Each blueprint deploys a functioning workflow that you can review, run, and experiment with.

## Workflow definition files
<a name="workflows-concepts-workflows-def"></a>

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](source-repositories.md). The file can have a .yml or .yaml extension, and the extension must be lowercase.

For more information about the workflow definition file, see [Workflow YAML definition](workflow-reference.md).

## Actions
<a name="workflows-concepts-actions"></a>

An *action* is the main building block of a workflow, and defines a logical unit of work, or task, to perform during a workflow run. Typically, a workflow includes multiple actions that run sequentially or in parallel depending on how you've configured them.

For more information about actions, see [Configuring workflow actions](workflows-actions.md).

## Action groups
<a name="workflows-concepts-action-groups"></a>

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.

For more information about action groups, see [Grouping actions into action groups](workflows-group-actions.md).

## Artifacts
<a name="workflows-concepts-artifacts"></a>

An *artifact* is the output of a workflow action, and typically consists of a folder or archive of files. Artifacts are important because they allow you to share files and information between actions.

For more information about artifacts, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

## Compute
<a name="workflows-concepts-compute"></a>

*Compute* refers to the computing engine (the CPU, memory, and operating system) managed and maintained by CodeCatalyst to run workflow actions.

For more information about compute, see [Configuring compute and runtime images](workflows-working-compute.md).

## Environments
<a name="workflows-concepts-environments"></a>

A CodeCatalyst *environment*, not to be confused with a [Dev Environment](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html), defines the target AWS account and optional Amazon VPC that a CodeCatalyst [workflow](workflow.md) connects to. An environment also defines the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a workflow needs to access the AWS services and resources within the target account.

You can set up multiple environments and give them names such as development, test, staging, and production. When you deploy into these environments, information about the deployments appears on the CodeCatalyst **Deployment activity** and **Deployment targets** tabs in the environment.

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Gates
<a name="workflows-concepts-gates"></a>

A *gate* is a workflow component that you can use to prevent a workflow run from proceeding unless certain conditions are met. An example of a gate is the **Approval** gate where users must submit an approval in the CodeCatalyst console before the workflow run is allowed to continue.

You can add gates between sequences of actions in a workflow, or before the first action (which runs immediately after the **Source** downloads). You can also add gates after the last action, if you have a need to do so.

For more information about gates, see [Gating a workflow run](workflows-gates.md).

## Reports
<a name="workflows-concepts-test-reports"></a>

A *report* contains details about tests that occur during a workflow run. You can create reports such as a test report, a code coverage report, a software composition analysis report, and a static analysis report. You can use a report to help troubleshoot a problem during a workflow. If you have many reports from multiple workflows, you can use your reports to view trends and failure rates to help you optimize your applications and deployment configurations.

For more information about reports, see [Quality report types](test-workflow-actions.md#test-reporting).

## Runs
<a name="workflows-concepts-runs"></a>

A *run* is a single iteration of a workflow. During a run, CodeCatalyst performs the actions defined in the workflow configuration file and outputs the associated logs, artifacts, and variables.

For more information about runs, see [Running a workflow](workflows-working-runs.md).

## Sources
<a name="workflows-concepts-sources"></a>

A *source*, also called an *input source*, is a source repository to which a [workflow action](workflows-actions.md) connects in order to obtain the files it needs to carry out its operations. For example, a workflow action might connect to a source repository to obtain application source files in order to build an application.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

## Variables
<a name="workflows-concepts-variables"></a>

 A *variable* is a key-value pair that contains information that you can reference in your Amazon CodeCatalyst workflow. The value portion of the variable is replaced with an actual value when the workflow runs.

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

## Workflow triggers
<a name="workflows-concepts-triggers"></a>

A *workflow trigger*, or simply a *trigger*, allows you to start a workflow run automatically when certain events occur, like a code push. You might want to configure triggers to free your software developers from having to start workflow runs manually through the CodeCatalyst console.

You can use three types of trigger:
+ **Push** – A code push trigger causes a workflow run to start whenever a commit is pushed.
+ **Pull request** – A pull request trigger causes a workflow run to start whenever a pull request is either created, revised, or closed.
+ **Schedule** – A schedule trigger causes a workflow run to start on a schedule that you define. Consider using a schedule trigger to run nightly builds of your software so that the latest build is ready for your software developers to work on the next morning.

You can use push, pull request, and schedule triggers alone or in combination in the same workflow.

Triggers are optional—if you don't configure any, you can only start a workflow manually.

For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).

# Getting started with workflows
<a name="workflows-getting-started"></a>

In this tutorial, you'll learn how to create and configure your first workflow.

**Tip**  
Prefer to start with a preconfigured workflow? See [Creating a project with a blueprint](projects-create.md#projects-create-console-template), which includes instructions for setting up a project with a functioning workflow, sample application, and other resources.

**Topics**
+ [

## Prerequisites
](#get-started-create-workflow-prerequisites)
+ [

## Step 1: Create and configure your workflow
](#get-started-create-workflow-create)
+ [

## Step 2: Save your workflow with a commit
](#get-started-create-workflow-commit)
+ [

## Step 3: View run results
](#get-started-create-workflow-results)
+ [

## (Optional) Step 4: Clean up
](#get-started-create-workflow-cleanup)

## Prerequisites
<a name="get-started-create-workflow-prerequisites"></a>

Before you begin:
+ You need a CodeCatalyst **space**. For more information, see [Creating a space](spaces-create.md).
+ In your CodeCatalyst space, you need an empty project called:

  ```
  codecatalyst-project
  ```

   For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need a CodeCatalyst ** repository** called:

  ```
  codecatalyst-source-repository
  ```

  For more information, see [Creating a source repository](source-repositories-create.md).

**Note**  
If you have an existing project and source repository, you can use them; however, creating new ones makes cleanup easier at the end of this tutorial.

## Step 1: Create and configure your workflow
<a name="get-started-create-workflow-create"></a>

In this step, you create and configure a workflow that automatically builds and tests your source code when changes are made.

**To create your workflow**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

   The workflow definition file appears in the CodeCatalyst console's YAML editor.

**To configure your workflow**

You can configure your workflow in the **Visual** editor, or the **YAML** editor. Let's start with the YAML editor and then switch to the visual editor.

1. Choose **\$1 Actions** to see a list of workflow actions that you can add to your workflow.

1. In the **Build** action, choose **\$1** to add the action's YAML to your workflow definition file. Your workflow now looks similar to the following.

   ```
   Name: Workflow_fe47
   SchemaVersion: "1.0"
   
   # Optional - Set automatic triggers.
   Triggers:
     - Type: Push
       Branches:
         - main
   
   # Required - Define action configurations.
   Actions:
     Build_f0:
       Identifier: aws/build@v1
   
       Inputs:
         Sources:
           - WorkflowSource # This specifies that the action requires this workflow as a source
   
       Outputs:
         AutoDiscoverReports:
           Enabled: true
           # Use as prefix for the report files
           ReportNamePrefix: rpt
   
       Configuration:
         Steps:
           - Run: echo "Hello, World!"
           - Run: echo "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>" >> report.xml
           - Run: echo "<testsuite tests=\"1\" name=\"TestAgentJunit\" >" >> report.xml
           - Run: echo "<testcase classname=\"TestAgentJunit\" name=\"Dummy
               Test\"/></testsuite>" >> report.xml
   ```

   The workflow copies the files in the `WorkflowSource` source repository to the compute machine running the `Build_f0` action, prints `Hello, World!` to the logs, discovers test reports on the compute machine, and outputs them to the CodeCatalyst console's **Reports** page.

1. Choose **Visual** to view the workflow definition file in the visual editor. The fields in the visual editor let you configure the YAML properties shown in the YAML editor.

## Step 2: Save your workflow with a commit
<a name="get-started-create-workflow-commit"></a>

In this step, you save your changes. Because workflows are stored as `.yaml` files in your repository, you save your changes with commits.

**To commit your workflow changes**

1. (Optional) Choose **Validate** to make sure the workflow's YAML code is valid.

1. Choose **Commit**.

1. In **Workflow file name**, enter a name for your workflow configuration file, like **my-first-workflow**.

1. In **Commit message**, enter a message to identify your commit, like **create my-first-workflow.yaml**.

1. In **Repository**, choose the repository you want to save the workflow in (`codecatalyst-repository`).

1. In **Branch name**, choose the branch you want to save the workflow in (`main`).

1. Choose **Commit**.

Your new workflow appears in the list of workflows. It might take several moments to appear.

Because workflows are saved with commits, and because the workflow has a code push trigger configured, saving the workflow starts a workflow run automatically.

## Step 3: View run results
<a name="get-started-create-workflow-results"></a>

In this step, you navigate to the run that was started from your commit and view the results.

**To view run results**

1. Choose the name of your workflow, for example, `Workflow_fe47`.

   A workflow diagram showing the label of your source repository (**WorkflowSource**) and the build action (for example, **Build\$1f0**).

1. In the workflow run diagram, choose the build action (for example, **Build\$1f0**).

1. Review the contents of the **Logs**, **Reports**, **Configuration**, and **Variables** tabs. These tabs show you the results of your build action.

   For more information, see [Viewing the results of a build action](build-view-results.md).

## (Optional) Step 4: Clean up
<a name="get-started-create-workflow-cleanup"></a>

In this step, you clean up the resources that you created in this tutorial.

**To delete resources**
+ If you created a new project for this tutorial, delete it. For instructions, see [Deleting a project](projects-delete.md). Deleting the project also deletes the source repository and workflow. 

# Building with workflows
<a name="build-workflow-actions"></a>

Using [CodeCatalyst workflows](workflow.md), you can build applications and other resources. 

**Topics**
+ [

## How do I build an application?
](#build-how-to)
+ [

## Benefits of the build action
](#build-benefits)
+ [

## Alternatives to the build action
](#build-alternatives)
+ [

# Adding the build action
](build-add-action.md)
+ [

# Viewing the results of a build action
](build-view-results.md)
+ [

# Tutorial: Upload artifacts to Amazon S3
](build-deploy.md)
+ [

# Build and test actions YAML
](build-action-ref.md)

## How do I build an application?
<a name="build-how-to"></a>

To build an application or resource in CodeCatalyst, you first create a workflow, and then specify a build action inside it.

A *build action* is a workflow building block that compiles your source code, runs unit tests, and produces artifacts that are ready to deploy.

You add a build action to your workflow using the CodeCatalyst console's visual editor or YAML editor.

The high-level steps to build an application or resource are as follows.

**To build an application (high-level tasks)**

1. In CodeCatalyst, you **add source code** for an application you want to build. For more information, see [Storing source code in repositories for a project in CodeCatalyst](source-repositories.md).

1. In CodeCatalyst, you **create a workflow**. The workflow is where you define how to build, test, and deploy your application. For more information, see [Getting started with workflows](workflows-getting-started.md).

1. (Optional) In the workflow, you **add a trigger** that indicates the events that will cause the workflow to start automatically. For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md)

1. In the workflow, you add a **build action** that compiles and packages your application or resource source code. Optionally, you can also have the build action run unit tests, generate reports, and deploy your application if you don't want to use a test or deploy action for these purposes. For more on the test and deploy actions, see [Adding the build action](build-add-action.md).

1. (Optional) In the workflow, you **add a test action** and a **deploy action** to test and deploy your application or resource. You can choose from several pre-configured actions to deploy your application to different targets, such as Amazon ECS. For more information, see [Testing with workflowsTesting with workflows](test-workflow-actions.md), and [Deploying with workflowsDeploying with workflows](deploy.md).

1. You **start the workflow** either manually or automatically through a trigger. The workflow runs the build, test, and deploy actions in sequence to build, test, and deploy your application and resources to the target. For more information, see [Starting a workflow run manually](workflows-manually-start.md).

## Benefits of the build action
<a name="build-benefits"></a>

Using the build action within a workflow has the following benefits:
+ **Fully managed** – The build action eliminates the need to set up, patch, update, and manage your own build servers. 
+ **On demand** – The build action scales on demand to meet your build needs. You pay only for the number of build minutes you consume. For more information, see [Configuring compute and runtime images](workflows-working-compute.md).
+ **Out of the box** – CodeCatalyst includes prepackaged runtime environment Docker images that are used to run all your workflow actions, including build actions. These images come preconfigured with useful tools for building applications such as the AWS CLI and Node.js. You can configure CodeCatalyst to use a build image that you supply from a public or private registry. For more information, see [Specifying runtime environment images](build-images.md).

## Alternatives to the build action
<a name="build-alternatives"></a>

If you're using a build action to deploy your application, consider using a CodeCatalyst *deploy action* instead. Deploy actions perform behind-the-scenes configuration that you would otherwise have to write manually if you're using a build action. For more information on the available deploy actions, see [List of deploy actions](deploy.md#deploy-concepts-action-supported).

You can also use AWS CodeBuild to build your applications. For more information, see [What is CodeBuild?](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html).

# Adding the build action
<a name="build-add-action"></a>

Use the following procedure to add a build action to your CodeCatalyst workflow. 

------
#### [ Visual ]

**To add a build action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose **Actions**.

1. In **Actions**, choose **Build**. 

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the [Build and test actions YAML](build-action-ref.md). This reference provides detailed information on each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add a build action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Choose **Actions**.

1. In **Actions**, choose **Build**.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the [Build and test actions YAML](build-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## Build action definition
<a name="build-add-action-definition"></a>

The build action is defined as a set of YAML properties inside your workflow definition file. For information on these properties, see [Build and test actions YAML](build-action-ref.md) in the [Workflow YAML definition](workflow-reference.md).

# Viewing the results of a build action
<a name="build-view-results"></a>

Use the following instructions to view the results of a build action, including the generated logs, reports, and variables.

**To view the results of a build action**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. In the workflow diagram, choose the name of your build action, for example, **Build**.

1. To view the logs for the build run, choose **Logs**. The logs for the various build phases are displayed. You can expand or collapse the logs as needed.

1. To view the test reports produced by the build action, choose **Reports**, or in the navigation pane, choose **Reports**. For more information, see [Quality report types](test-workflow-actions.md#test-reporting).

1. To view the configuration used for the build action, choose **Configuration**. For more information, see [Adding the build action](build-add-action.md).

1. To view the variables used by the build action, choose **Variables**. For more information, see [Using variables in workflows](workflows-working-with-variables.md).

# Tutorial: Upload artifacts to Amazon S3
<a name="build-deploy"></a>

In this tutorial, you learn how to upload artifacts to an Amazon S3 bucket using an Amazon CodeCatalyst [workflow](workflows-concepts.md#workflows-concepts-workflows) that includes a couple of [build actions](workflows-concepts.md#workflows-concepts-actions). These actions run in series when the workflow starts. The first build action generates two files, `Hello.txt` and `Goodbye.txt`, and bundles them into a build artifact. The second build action uploads the artifact to Amazon S3. You'll configure the workflow to run every time you push a commit to your source repository.

**Topics**
+ [

## Prerequisites
](#build-deploy-tut-prereqs)
+ [

## Step 1: Create an AWS role
](#build-deploy-tut-role)
+ [

## Step 2: Create an Amazon S3 bucket
](#build-deploy-tut-artifact)
+ [

## Step 3: Create a source repository
](#deploy-tut-lambda-cfn-source)
+ [

## Step 4: Create a workflow
](#build-deploy-tut-workflow.title)
+ [

## Step 5: Verify the results
](#build-deploy.s3.verify)
+ [

## Clean up
](#deploy-tut-lambda-cfn-clean-up)

## Prerequisites
<a name="build-deploy-tut-prereqs"></a>

Before you begin, you need the following:
+ You need a CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ In your space, you need an empty project called:

  ```
  codecatalyst-artifact-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need a CodeCatalyst **environment** called:

  ```
  codecatalyst-artifact-environment
  ```

  Configure this environment as follows:
  + Choose any type, such as **Development**.
  + Connect your AWS account to it.
  + For the **Default IAM role**, choose any role. You'll specify a different role later.

  For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Step 1: Create an AWS role
<a name="build-deploy-tut-role"></a>

In this step, you create an AWS IAM role which you will later assign to the build action in your workflow. This role grants the CodeCatalyst build action permission to access your AWS account and write to Amazon S3 where your artifact will be stored. The role is called the **Build role**.

**Note**  
If you already have a build role that you created for another tutorial, you can use it for this tutorial too. Just make sure it has the permissions and trust policy shown in the following procedure.

For more information on IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS AWS Identity and Access Management User Guide*.

**To create a build role**

1. Create a policy for the role, as follows:

   1. Sign in to AWS.

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. In the navigation pane, choose **Policies**.

   1. Choose **Create policy**.

   1. Choose the **JSON** tab.

   1. Delete the existing code.

   1. Paste the following code:

------
#### [ JSON ]

****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Sid": "VisualEditor0",
                  "Effect": "Allow",
                  "Action": [
                      "s3:PutObject",
                      "s3:ListBucket"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Choose **Next: Tags**.

   1. Choose **Next: Review**.

   1. In **Name**, enter:

      ```
      codecatalyst-s3-build-policy
      ```

   1. Choose **Create policy**.

      You have now created a permissions policy.

1. Create the build role, as follows:

   1. In the navigation pane, choose **Roles**, and then choose **Create role**.

   1. Choose **Custom trust policy**.

   1. Delete the existing custom trust policy.

   1. Add the following custom trust policy:

   1. Choose **Next**.

   1. In **Permissions policies**, search for `codecatalyst-s3-build-policy` and select its check box.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-s3-build-role
      ```

   1. For **Role description**, enter:

      ```
      CodeCatalyst build role
      ```

   1. Choose **Create role**.

   You have now created a build role with a trust policy and permissions policy.

## Step 2: Create an Amazon S3 bucket
<a name="build-deploy-tut-artifact"></a>

In this step, you create an Amazon S3 bucket where the `Hello.txt` and `Goodbye.txt` artifacts will be uploaded.

**To create an Amazon S3 bucket**

1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. In the main pane, choose **Create bucket**.

1. For **Bucket name**, enter:

   ```
   codecatalyst-artifact-bucket
   ```

1. For **AWS Region**, choose a Region. This tutorial assumes you chose **US West (Oregon) us-west-2**. For information about Regions supported by Amazon S3, see [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html) in the *AWS General Reference*.

1. At the bottom of the page, choose **Create bucket**.

1. Copy the name of the bucket you just created, for example:

   ```
   codecatalyst-artifact-bucket
   ```

You have now created a bucket called **codecatalyst-artifact-bucket** in the US West (Oregon) us-west-2 Region.

## Step 3: Create a source repository
<a name="deploy-tut-lambda-cfn-source"></a>

In this step, you create a source repository in CodeCatalyst. This repository is used to store the tutorial's workflow definition file. 

For more information on source repositories, see [Creating a source repository](source-repositories-create.md).

**To create a source repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-artifact-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose **Add repository**, and then choose **Create repository**.

1. In **Repository name**, enter:

   ```
   codecatalyst-artifact-source-repository
   ```

1. Choose **Create**.

You have now created a repository called `codecatalyst-artifact-source-repository`.

## Step 4: Create a workflow
<a name="build-deploy-tut-workflow.title"></a>

In this step, you create a workflow that consists of the following building blocks that run sequentially:
+ A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information on triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A build action called `GenerateFiles` – On trigger, the `GenerateFiles` action creates two files, `Hello.txt` and `Goodbye.txt`, and packages them into an output artifact called `codecatalystArtifact`.
+ Another build action called `Upload` – On completion of the `GenerateFiles` action, the `Upload` action runs the AWS CLI command `aws s3 sync` to upload the files in the `codecatalystArtifact` and in your source repository to your Amazon S3 bucket. The AWS CLI comes pre-installed and pre-configured on the CodeCatalyst compute platform, so you don't need to install or configure it.

  For more information on the pre-packaged software on the CodeCatalyst compute platform, see [Specifying runtime environment images](build-images.md). For more information on the AWS CLI's `aws s3 sync` command, see [sync](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) in the *AWS CLI Command Reference*.

For more information on the build action, see [Building with workflows](build-workflow-actions.md).

**To create a workflow**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. Delete the YAML sample code.

1. Add the following YAML code:
**Note**  
In the YAML code that follows, you can omit the `Connections:` section if you want. If you omit this section, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies described in [Step 1: Create an AWS role](#build-deploy-tut-role). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md).

   ```
   Name: codecatalyst-artifact-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: Push
       Branches:
         - main   
   Actions:
     GenerateFiles:
       Identifier: aws/build@v1
       Configuration: 
         Steps:
           # Create the output files.
           - Run: echo "Hello, World!" > "Hello.txt"
           - Run: echo "Goodbye!" > "Goodbye.txt"
       Outputs:
         Artifacts:
           - Name: codecatalystArtifact
             Files:
               - "**/*"
     Upload:
       Identifier: aws/build@v1
       DependsOn: 
         - GenerateFiles
       Environment:
         Name: codecatalyst-artifact-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-s3-build-role
       Inputs:
         Artifacts:
           - codecatalystArtifact
       Configuration: 
         Steps:
           # Upload the output artifact to the S3 bucket.
           - Run: aws s3 sync . s3://codecatalyst-artifact-bucket
   ```

   In the code above, replace:
   + *codecatalyst-artifact-environment* with the name of the environment you created in [Prerequisites](#build-deploy-tut-prereqs).
   + *codecatalyst-account-connection* with the name of the account connection you created in [Prerequisites](#build-deploy-tut-prereqs).
   + *codecatalyst-s3-build-role* with the name of the build role that you created in [Step 1: Create an AWS role](#build-deploy-tut-role).
   + *codecatalyst-artifact-bucket* with the name of the Amazon S3 you created in [Step 2: Create an Amazon S3 bucket](#build-deploy-tut-artifact).

   For information about the properties in this file, see the [Build and test actions YAML](build-action-ref.md).

1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing.

1. Choose **Commit**.

1. On the **Commit workflow** dialog box, enter the following:

   1. For **Workflow file name**, leave the default, `codecatalyst-artifact-workflow`.

   1. For **Commit message**, enter:

      ```
      add initial workflow file
      ```

   1. For **Repository**, choose **codecatalyst-artifact-source-repository**.

   1. For **Branch name**, choose **main**.

   1. Choose **Commit**.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `codecatalyst-artifact-workflow.yaml` file to your source repository, the trigger started the workflow run.

**To view the workflow run in progress**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created: `codecatalyst-artifact-workflow`.

1. Choose **GenerateFiles** to see the first build action progress.

1. Choose **Upload** to see the second build action progress.

1. When the **Upload** action finishes, do the following:
   + If the workflow run succeeded, go to the next procedure.
   + If the workflow run failed, choose **Logs** to troubleshoot the issue.

## Step 5: Verify the results
<a name="build-deploy.s3.verify"></a>

After the workflow runs, go to the Amazon S3 service and look in your *codecatalyst-artifact-bucket* bucket. It should now include the following files and folders:

```
.
|— .aws/
|— .git/
|Goodbye.txt
|Hello.txt
|REAME.md
```

The `Goodbye.txt` and `Hello.txt` files were uploaded because they were part of the `codecatalystArtifact` artifact. The `.aws/`, `.git/`, and `README.md` files were uploaded because they were in your source repository.

## Clean up
<a name="deploy-tut-lambda-cfn-clean-up"></a>

Clean up in CodeCatalyst and AWS to avoid being charged for these services.

**To clean up in CodeCatalyst**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Delete the `codecatalyst-artifact-source-repository` source repository.

1. Delete the `codecatalyst-artifact-workflow` workflow.

**To clean up in AWS**

1. Clean up in Amazon S3, as follows:

   1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

   1. Delete the files in the `codecatalyst-artifact-bucket` bucket.

   1. Delete the `codecatalyst-artifact-bucket` bucket.

1. Clean up in IAM, as follows:

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. Delete the `codecatalyst-s3-build-policy`.

   1. Delete the `codecatalyst-s3-build-role`.

# Build and test actions YAML
<a name="build-action-ref"></a><a name="test-action-ref"></a>

The following is the YAML definition of the build and test actions. There is one reference for two actions because their YAML properties are very similar.

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

Choose a YAML property in the following code to see a description if it.

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.
  action-name:
    Identifier: aws/build@v1 | aws/managed-test@v1
    DependsOn:
      - dependent-action-name-1
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Caching:  
      FileCaching:
        key-name-1:
          Path: file1.txt
          RestoreKeys:
            - restore-key-1
    Inputs:
      Sources:
        - source-name-1
        - source-name-2
      Artifacts:
        - artifact-name
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2   
    Outputs:
      Artifacts:
        - Name: output-artifact-1
          Files: 
            - build-output/artifact-1.jar
            - "build-output/build*"
        - Name: output-artifact-2
          Files:
            - build-output/artifact-2.1.jar
            - build-output/artifact-2.2.jar
      Variables:
        - variable-name-1
        - variable-name-2
      AutoDiscoverReports:
        Enabled: true | false
        ReportNamePrefix: AutoDiscovered
        IncludePaths:
          - "**/*"
        ExcludePaths:
          - node_modules/cdk/junit.xml
        SuccessCriteria:
          PassRate: percent
          LineCoverage: percent
          BranchCoverage: percent
          Vulnerabilities:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisBug:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisSecurity:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisQuality:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisFinding:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
      Reports:
        report-name-1:
          Format: format
          IncludePaths:
            - "*.xml"
          ExcludePaths:
            - report2.xml
            - report3.xml
          SuccessCriteria:
            PassRate: percent
            LineCoverage: percent
            BranchCoverage: percent
            Vulnerabilities:
              Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
              Number: whole-number
            StaticAnalysisBug:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisSecurity:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisQuality:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisFinding:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
    Configuration:
      Container:
        Registry: registry
        Image: image
      Steps:
        - Run: "step 1"
        - Run: "step 2"
      Packages:
        NpmConfiguration:
          PackageRegistries:
            - PackagesRepository: package-repository
              Scopes:
                - "@scope"
        ExportAuthorizationToken: true | false
```

## action-name
<a name="build.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Corresponding UI: Configuration tab/**Action name**

## Identifier
<a name="build.identifier"></a>

(*action-name*/**Identifier**)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Use `aws/build@v1` for build actions.

Use `aws/managed-test@v1` for test actions.

Corresponding UI: Workflow diagram/Action-name/*aws/build@v1\$1aws/managed-test@v1* label

## DependsOn
<a name="build.depends-on"></a>

(*action-name*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="build.computename"></a>

(*action-name*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="build.computetype"></a>

(*action-name*/Compute/**Type**)

(Required if [Compute](#build.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/**Compute type**

## Fleet
<a name="build.computefleet"></a>

(*action-name*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/**Compute fleet**

## Timeout
<a name="build.timeout"></a>

(*action-name*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Environment
<a name="build.environment"></a>

(*action-name*/**Environment**)

(Optional)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="build.environment.name"></a>

(*action-name*/Environment/**Name**)

(Optional)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="build.environment.connections"></a>

(*action-name*/Environment/**Connections**)

(Optional)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Name
<a name="build.environment.connections.name"></a>

(*action-name*/Environment/Connections/**Name**)

(Required if [Connections](#build.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Role
<a name="build.environment.connections.role"></a>

(*action-name*/Environment/Connections/**Role**)

(Required if [Connections](#build.environment.connections) is included)

Specify the name of the IAM role that this action uses in order to access and operate in AWS services such as Amazon S3 and Amazon ECR. Make sure this role is added to your AWS account connection in your space. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

**Warning**  
Limit the permissions to those required by the build and test actions. Using a role with broader permissions might pose a security risk.

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Caching
<a name="build.caching"></a>

(*action-name*/**Caching**)

(Optional)

A section where you can specify a cache to save on-disk files and restore them from that cache in subsequent workflow runs.

For more information about file caching, see [Caching files between workflow runs](workflows-caching.md).

Corresponding UI: Configuration tab/**File caching - optional**

## FileCaching
<a name="build.caching.filecaching"></a>

(*action-name*/Caching/**FileCaching**)

(Optional)

A section that specifies the configuration for a sequence of caches.

Corresponding UI: Configuration tab/File caching - optional/**Add cache**

## key-name-1
<a name="build.caching.filecaching.key-name-1"></a>

(*action-name*/Caching/FileCaching/***key-name-1***)

(Optional)

Specify the name of your primary cache property name. Cache property names must be unique within your workflow. Each action can have up to five entries in `FileCaching`.

Corresponding UI: Configuration tab/File caching - optional/Add cache/**Key**

## Path
<a name="build.caching.filecaching.key-name-1.path"></a>

(*action-name*/Caching/FileCaching/*key-name-1*/**Path**)

(Optional)

Specify the associated path for your cache. 

Corresponding UI: Configuration tab/File caching - optional/Add cache/**Path**

## RestoreKeys
<a name="build.caching.filecaching.key-name-1.restorekeys"></a>

(*action-name*/Caching/FileCaching/*key-name-1*/**RestoreKeys**)

(Optional)

Specify the restore key to use as a fallback when the primary cache property can't be found. Restore key names must be unique within your workflow. Each cache can have up to five entries in `RestoreKeys`.

Corresponding UI: Configuration tab/File caching - optional/Add cache/**Restore keys - optional**

## Inputs
<a name="build.inputs"></a>

(*action-name*/**Inputs**)

(Optional)

The `Inputs` section defines the data that an action needs during a workflow run.

**Note**  
A maximum of four inputs (one source and three artifacts) are allowed per build action or test action. Variables do not count towards this total.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see [Example: Referencing files in multiple artifacts](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file).

Corresponding UI: **Inputs** tab

## Sources
<a name="build.inputs.sources"></a>

(*action-name*/Inputs/**Sources**)

(Optional)

Specify the labels that represent the source repositories that will be needed by the action. Currently, the only supported label is `WorkflowSource`, which represents the source repository where your workflow definition file is stored.

If you omit a source, then you must specify at least one input artifact under `action-name/Inputs/Artifacts`.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: *none*

## Artifacts - input
<a name="build.inputs.artifacts"></a>

(*action-name*/Inputs/**Artifacts**)

(Optional)

Specify artifacts from previous actions that you want to provide as input to this action. These artifacts must already be defined as output artifacts in previous actions.

If you do not specify any input artifacts, then you must specify at least one source repository under `action-name/Inputs/Sources`.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

**Note**  
If the **Artifacts - optional** drop-down list is unavailable (visual editor), or if you get errors in when you validate your YAML (YAML editor), it might be because the action only supports one input. In this case, try removing the source input.

Corresponding UI: Inputs tab/**Artifacts - optional**

## Variables - input
<a name="build.inputs.variables"></a>

(*action-name*/Inputs/**Variables**)

(Optional)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Inputs tab/**Variables - optional**

## Outputs
<a name="build.outputs"></a>

(*action-name*/**Outputs**)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts - output
<a name="build.outputs.artifacts"></a>

(*action-name*/Outputs/**Artifacts**)

(Optional)

Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (\$1). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/**Artifacts**

## Name
<a name="build.outputs.artifacts.name"></a>

(*action-name*/Outputs/Artifacts/**Name**)

(Required if [Artifacts - output](#build.outputs.artifacts) is included)

Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (\$1). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/Artifacts/New output/**Build artifact name**

## Files
<a name="build.outputs.artifacts.files"></a>

(*action-name*/Outputs/Artifacts/**Files**)

(Required if [Artifacts - output](#build.outputs.artifacts) is included)

Specify the files that CodeCatalyst includes in the artifact that is output by the action. These files are generated by the workflow action when it runs, and are also available in your source repository. File paths can reside in a source repository or an artifact from a previous action, and are relative to the source repository or artifact root. You can use glob patterns to specify paths. Examples:
+ To specify a single file that is in the root of your build location or source repository location, use `my-file.jar`.
+ To specify a single file in a subdirectory, use `directory/my-file.jar` or `directory/subdirectory/my-file.jar`.
+ To specify all files, use `"**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
+ To specify all files and directories in a directory named `directory`, use `"directory/**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
+ To specify all files in a directory named `directory`, but not any of its subdirectories, use `"directory/*"`. 

**Note**  
If your file path includes one or more asterisks (`*`) or other special character, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

**Note**  
You may need to add a prefix to the file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Outputs tab/Artifacts/New output/**Files produced by build**

## Variables - output
<a name="build.outputs.variables"></a>

(*action-name*/Outputs/**Variables**)

(Optional)

Specify the variables that you want the action to export so that they are available for use by subsequent actions.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Outputs tab/Variables/**Add variable**

## variable-name-1
<a name="build.outputs.variables.name"></a>

(*action-name*/Outputs/Variables/*variable-name-1*)

(Optional)

Specify the name of a variable that you want the action to export. This variable must already be defined in the `Inputs` or `Steps` section of the same action.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Outputs tab/Variables/Add variable/**Name**

## AutoDiscoverReports
<a name="build.outputs.autodiscover"></a>

(*action-name*/Outputs/**AutoDiscoverReports**)

(Optional)

Defines the configuration for the auto-discovery feature.

When you enable auto-discovery, CodeCatalyst searches all `Inputs` passed into the action as well as all files generated by the action itself, looking for test, code coverage, and software composition analysis (SCA) reports. For each report that is found, CodeCatalyst transforms it into a CodeCatalyst report. A *CodeCatalyst report* is a report that is fully integrated into the CodeCatalyst service and can be viewed and manipulated through the CodeCatalyst console.

**Note**  
By default, the auto-discover feature inspects all files. You can limit which files are inspected using the [IncludePaths](#build.reports.includepaths) or [ExcludePaths](#build.reports.excludepaths) properties. 

Corresponding UI: Outputs tab/Reports/**Auto-discover reports**

## Enabled
<a name="build.outputs.autodiscover.enabled"></a>

(*action-name*/Outputs/AutoDiscoverReports/**Enabled**)

(Optional)

Enable or disable the auto-discovery feature.

Valid values are `true` or `false`.

If `Enabled` is omitted, the default is `true`.

Corresponding UI: Outputs tab/Reports/**Auto-discover reports**

## ReportNamePrefix
<a name="build.outputs.autodiscover.reportnameprefix"></a>

(*action-name*/Outputs/AutoDiscoverReports/**ReportNamePrefix**)

(Required if [AutoDiscoverReports](#build.outputs.autodiscover) is included and enabled)

Specify a prefix that CodeCatalyst prepends to all the reports it finds in order to name their associated CodeCatalyst reports. For example, if you specify a prefix of `AutoDiscovered`, and CodeCatalyst auto-discovers two test reports, `TestSuiteOne.xml` and `TestSuiteTwo.xml`, then the associated CodeCatalyst reports will be named `AutoDiscoveredTestSuiteOne` and `AutoDiscoveredTestSuiteTwo`.

Corresponding UI: Outputs tab/Reports/**Prefix name**

## IncludePaths
<a name="build.reports.includepaths"></a>

(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)

(Required if [AutoDiscoverReports](#build.outputs.autodiscover) is included and enabled, or if [Reports](#test.configuration.reports) is included)

Specify the files and file paths that CodeCatalyst includes when searching for raw reports. For example, if you specify `"/test/report/*"`, CodeCatalyst searches the entire [build image](build-images.md) used by the action looking for the `/test/report/*` directory. When it finds that directory, CodeCatalyst then looks for reports in that directory.

**Note**  
If your file path includes one or more asterisks (`*`) or other special characters, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

If this property is omitted, the default is `"**/*"`, meaning the search includes all files at all paths.

**Note**  
For manually configured reports, `IncludePaths` must be a glob pattern that matches a single file.

Corresponding UI:
+ Outputs tab/Reports/Auto-discover reports/Include/exclude paths/**Include paths**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Include/exclude paths/**Include paths**

## ExcludePaths
<a name="build.reports.excludepaths"></a>

(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**ExcludePaths**)

(Optional)

Specify the files and file paths that CodeCatalyst excludes when searching for raw reports. For example, if you specify `"/test/my-reports/**/*"`, CodeCatalyst will not search for files in the `/test/my-reports/` directory. To ignore all files in a directory, use the `**/*` glob pattern.

**Note**  
If your file path includes one or more asterisks (`*`) or other special characters, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

Corresponding UI:
+ Outputs tab/Reports/Auto-discover reports/Include/exclude paths/**Exclude paths**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Include/exclude paths/**Exclude paths**

## SuccessCriteria
<a name="build.reports.successcriteria"></a>

(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**SuccessCriteria**)

(Optional)

Specify the success criteria for the test, code coverage, software composition analysis (SCA), and static analysis (SA) reports.

For more information, see [Configuring success criteria for reports](test-config-action.md#test.success-criteria).

Corresponding UI: Output tab/Reports/**Success criteria**

## PassRate
<a name="build.reports.successcriteria.passrate"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**PassRate**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)

(Optional)

Specify the percentage of tests in a test report that must pass for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. The pass rate criteria are applied only to test reports. For more information about test reports, see [Test reports](test-workflow-actions.md#test-reports).

Corresponding UI: Output tab/Reports/Success criteria/**Pass rate**

## LineCoverage
<a name="build.reports.successcriteria.linecoverage"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**LineCoverage**)

(Optional)

Specify the percentage of lines in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Line coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

Corresponding UI: Output tab/Reports/Success criteria/**Line coverage**

## BranchCoverage
<a name="build.reports.successcriteria.branchcoverage"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**BranchCoverage**)

(Optional)

Specify the percentage of branches in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Branch coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

Corresponding UI: Output tab/Reports/Success criteria/**Branch coverage**

## Vulnerabilities
<a name="build.reports.successcriteria.vulnerabilities"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)

(Optional)

Specify the maximum number and severity of vulnerabilities permitted in the SCA report for the associated CodeCatalyst report to be marked as passed. To specify vulnerabilities, you must specify:
+ The minimum severity of the vulnerabilities you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` vulnerabilities will be tallied.
+ The maximum number of vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Vulnerabilities criteria are applied only to SCA reports. For more information about SCA reports, see [Software composition analysis reports](test-workflow-actions.md#test-sca-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

Corresponding UI: Output tab/Reports/Success criteria/**Vulnerabilities**

## StaticAnalysisBug
<a name="build.reports.successcriteria.bugs"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisBug**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisBug**)

(Optional)

Specify the maximum number and severity of bugs permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify bugs, you must specify:
+ The minimum severity of the bugs you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` bugs will be tallied.
+ The maximum number of bugs of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Bugs criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

Corresponding UI: Output tab/Reports/Success criteria/**Bugs**

## StaticAnalysisSecurity
<a name="build.reports.successcriteria.securityvulnerabilities"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisSecurity**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisSecurity**)

(Optional)

Specify the maximum number and severity of security vulnerabilities permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify security vulnerabilities, you must specify:
+ The minimum severity of the security vulnerabilities you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` security vulnerabilities will be tallied.
+ The maximum number of security vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Security vulnerabilities criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

Corresponding UI: Output tab/Reports/Success criteria/**Security vulnerabilities**

## StaticAnalysisQuality
<a name="build.reports.successcriteria.qualityissues"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisQuality**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisQuality**)

(Optional)

Specify the maximum number and severity of quality issues permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify quality issues, you must specify:
+ The minimum severity of the quality issues you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` quality issues will be tallied.
+ The maximum number of quality issues of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Quality issues criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

Corresponding UI: Output tab/Reports/Success criteria/**Quality issues**

## StaticAnalysisFinding
<a name="build.reports.successcriteria.findings"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**StaticAnalysisFinding**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**StaticAnalysisFinding**)

(Optional)

Specify the maximum number and severity of findings permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify findings, you must specify:
+ The minimum severity of the findings you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` findings will be tallied.
+ The maximum number of findings of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Findings are applied only to SARIF SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

Corresponding UI: Output tab/Reports/Success criteria/**Findings**

## Reports
<a name="test.configuration.reports"></a>

(*action-name*/Outputs/**Reports** )

(Optional)

A section that specifies the configuration for test reports.

Corresponding UI: Outputs tab/**Reports**

## report-name-1
<a name="test.configuration.reports.report-name-1"></a>

(*action-name*/Outputs/Reports/**report-name-1** )

(Required if [Reports](#test.configuration.reports) is included)

The name you want to give to the CodeCatalyst report that will be generated from your raw reports.

Corresponding UI: Outputs tab/Reports/Manually configure reports/**Report name**

## Format
<a name="test.configuration.reports.name.testresults.format"></a>

(*action-name*/Outputs/Reports/*report-name-1*/**Format**)

(Required if [Reports](#test.configuration.reports) is included)

Specify the file format that you're using for your reports. Possible values are as follows.
+ For test reports:
  + For Cucumber JSON, specify **Cucumber** (visual editor) or `CUCUMBERJSON` (YAML editor).
  + For JUnit XML, specify **JUnit** (visual editor) or `JUNITXML` (YAML editor).
  + For NUnit XML, specify **NUnit** (visual editor) or `NUNITXML` (YAML editor).
  + For NUnit 3 XML, specify **NUnit3** (visual editor) or `NUNIT3XML` (YAML editor).
  + For Visual Studio TRX, specify **Visual Studio TRX** (visual editor) or `VISUALSTUDIOTRX` (YAML editor).
  + For TestNG XML, specify **TestNG** (visual editor) or `TESTNGXML` (YAML editor).
+ For code coverage reports:
  + For Clover XML, specify **Clover** (visual editor) or `CLOVERXML` (YAML editor).
  + For Cobertura XML, specify **Cobertura** (visual editor) or `COBERTURAXML` (YAML editor).
  + For JaCoCo XML, specify **JaCoCo** (visual editor) or `JACOCOXML` (YAML editor).
  + For SimpleCov JSON generated by [simplecov](https://github.com/simplecov-ruby/simplecov), not [simplecov-json](https://github.com/vicentllongo/simplecov-json), specify **Simplecov** (visual editor) or `SIMPLECOV` (YAML editor).
+ For software composition analysis (SCA) reports:
  + For SARIF, specify **SARIF** (visual editor) or `SARIFSCA` (YAML editor).

Corresponding UI: Outputs tab/Reports/Manually configure reports/Add/configure reports/*report-name-1*/**Report type** and **Report format**

## Configuration
<a name="build.configuration"></a>

(*action-name*/**Configuration**)

(Required) A section where you can define the configuration properties of the action. 

Corresponding UI: **Configuration** tab

## Container
<a name="build.configuration.container"></a>

(*action-name*/Configuration/**Container**)

(Optional)

Specify the Docker image, or *container*, that the action uses to complete its processing. You can specify one of the [active images](build-images.md#build-curated-images) that come with CodeCatalyst, or you can use your own image. If you choose to use your own image, it can reside in Amazon ECR, Docker Hub, or another registry. If you don't specify a Docker image, the action uses one of the active images for its processing. For information about which active image is used by default, see [Active images](build-images.md#build-curated-images).

For more information about specifying your own Docker image, see [Assigning a custom runtime environment Docker image to an action](build-images.md#build-images-specify).

Corresponding UI: **Runtime environment Docker image - optional**

## Registry
<a name="build.configuration.container.registry"></a>

(*action-name*/Configuration/Container/**Registry**)

(Required if `Container` is included)

Specify the registry where your image is stored. Valid values include:
+ `CODECATALYST` (YAML editor)

  The image is stored in the CodeCatalyst registry.
+ **Docker Hub** (visual editor) or `DockerHub` (YAML editor)

  The image is stored in the Docker Hub image registry.
+ **Other registry** (visual editor) or `Other` (YAML editor)

  The image is stored in a custom image registry. Any publicly available registry can be used.
+ **Amazon Elastic Container Registry** (visual editor) or `ECR` (YAML editor)

  The image is stored in an Amazon Elastic Container Registry image repository. To use an image in an Amazon ECR repository, this action needs access to Amazon ECR. To enable this access, you must create an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that includes the following permissions and custom trust policy. (You can modify an existing role to include the permissions and policy, if you want.)

  The IAM role must include the following permissions in its role policy:
  + `ecr:BatchCheckLayerAvailability`
  + `ecr:BatchGetImage`
  + `ecr:GetAuthorizationToken`
  + `ecr:GetDownloadUrlForLayer`

  The IAM role must include the following custom trust policy:

  For more information about creating IAM roles, see [Creating a role using custom trust policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) in the *IAM User Guide*.

  Once you have created the role, you must assign it to the action through an environment. For more information, see [Associating an environment with an action](deploy-environments-add-app-to-environment.md).

Corresponding UI: **Amazon Elastic Container Registry**, **Docker Hub**, and **Other registry** options

## Image
<a name="build.configuration.container.image"></a>

(*action-name*/Configuration/Container/**Image**)

(Required if `Container` is included)

Specify one of the following:
+ If you are using a `CODECATALYST` registry, set the image to one of the of the following [active images](build-images.md#build-curated-images):
  + `CodeCatalystLinux_x86_64:2024_03`
  + `CodeCatalystLinux_x86_64:2022_11`
  + `CodeCatalystLinux_Arm64:2024_03`
  + `CodeCatalystLinux_Arm64:2022_11`
  + `CodeCatalystLinuxLambda_x86_64:2024_03`
  + `CodeCatalystLinuxLambda_x86_64:2022_11`
  + `CodeCatalystLinuxLambda_Arm64:2024_03`
  + `CodeCatalystLinuxLambda_Arm64:2022_11`
  + `CodeCatalystWindows_x86_64:2022_11`
+ If you are using a Docker Hub registry, set the image to the Docker Hub image name and optional tag.

  Example: `postgres:latest`
+ If you are using an Amazon ECR registry, set the image to the Amazon ECR registry URI.

  Example: `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`
+ If you are using a custom registry, set the image to the value expected by the custom registry.

Corresponding UI: **Runtime environment docker image** (if the registry is `CODECATALYST`), **Docker Hub image** (if the registry is **Docker Hub**), **ECR image URL** (if the registry is **Amazon Elastic Container Registry**), and **Image URL** (if the registry is **Other registry**).

## Steps
<a name="build.configuration.steps"></a>

(*action-name*/Configuration/**Steps**)

(Required) 

Specify the shell commands that you want to run during the action to install, configure, and run your build tools.

Here is an example of how to build an npm project:

```
Steps:
  - Run: npm install
  - Run: npm run build
```

Here is an example of how to specify file paths:

```
Steps:
  - Run: cd $ACTION_BUILD_SOURCE_PATH_WorkflowSource/app  && cat file2.txt
  - Run: cd $ACTION_BUILD_SOURCE_PATH_MyBuildArtifact/build-output/  && cat file.txt
```

For more information about specifying file paths, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Configuration tab/**Shell commands**

## Packages
<a name="build.configuration.packages"></a>

(*action-name*/Configuration/**Packages**)

(Optional) 

A section where you can specify a package repository that the action uses to resolve dependencies. Packages allow you to securely store and share software packages used for application development.

For more information about packages, see [Publish and share software packages in CodeCatalyst](packages.md).

Corresponding UI: Configuration tab/**Packages**

## NpmConfiguration
<a name="build.configuration.packages.npm"></a>

(*action-name*/Configuration/Packages/**NpmConfiguration**)

(Required if [Packages](#build.configuration.packages) is included)

A section which defines the configuration for the npm package format. This configuration is used by an action during a workflow run.

For more information about the npm package configuration, see [Using npm](packages-npm.md).

Corresponding UI: Configuration tab/Packages/Add configuration/**npm**

## PackageRegistries
<a name="build.configuration.packages.registry"></a>

(*action-name*/Configuration/Packages/NpmConfiguration/**PackageRegistries**)

(Required if [Packages](#build.configuration.packages) is included)

A section where you can define the configuration properties of a sequence of package repositories.

Corresponding UI: Configuration tab/Packages/Add configuration/npm/**Add package repository**

## PackagesRepository
<a name="build.configuration.packages.repository"></a>

(*action-name*/Configuration/Packages/NpmConfiguration/PackageRegistries/**PackagesRepository**)

(Required if [Packages](#build.configuration.packages) is included)

Specify the name of your CodeCatalyst *package repository* that you want the action to use.

If you specify multiple default repositories, the last repository will take priority.

For more information about package repositories, see [Package repositories](packages-concepts.md#packages-concepts-repository).

Corresponding UI: Configuration tab/Packages/Add configuration/npm/Add package repository/**Package repository**

## Scopes
<a name="build.configuration.packages.scope"></a>

(*action-name*/Configuration/Packages/NpmConfiguration/PackageRegistries/**Scopes**)

(Optional) 

Specify a sequence of *scopes* that you want to define in your package registry. When defining scopes, the specified package repository is configured as the registry for all listed scopes. If a package with the scope is requested through the npm client, it will use that repository instead of the default. Each scope name must be prefixed with "@".

If you include overriding scopes, the last repository will take priority.

If `Scopes` is omitted, then the specified package repository is configured as the default registry for all packages used by the action.

For more information about scopes, see [Package namespaces](packages-concepts.md#packages-concepts-package-namespaces) and [Scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope).

Corresponding UI: Configuration tab/Packages/Add configuration/npm/Add package repository/**Scopes - optional**

## ExportAuthorizationToken
<a name="build.configuration.packages.exportauthtoken"></a>

(*action-name*/Configuration/Packages/**ExportAuthorizationToken**)

(Optional) 

Enable or disable the export authorization token feature. If enabled, exported authorization tokens can be used to manually configure a package manager to authenticate with CodeCatalyst package repositories. You can use the token as an environment variable that can be referenced in your actions.

Valid values are `true` or `false`.

If `ExportAuthorizationToken` is omitted, the default is `false`.

For more information about the export authorization token, see [Using authorization tokens in workflow actions](workflows-package-export-token.md).

Corresponding UI: Configuration tab/Packages/**Export authorization token**

# Testing with workflows
<a name="test-workflow-actions"></a>

In CodeCatalyst, you can run tests as part of different workflow actions, such as build and test. These workflow actions can all generate quality reports. A *test action* is a workflow action that produces test, code coverage, software composition analysis, and static analysis reports. These reports are displayed in the CodeCatalyst console.

**Topics**
+ [

## Quality report types
](#test-reporting)
+ [

# Adding the test action
](test-add-action.md)
+ [

# Viewing the results of a test action
](test-view-results.md)
+ [

# Skipping failed tests in an action
](test.error-handling.md)
+ [

# Integrating with universal-test-runner
](test.universal-test-runner.md)
+ [

# Configuring quality reports in an action
](test-config-action.md)
+ [

# Best practices for testing
](test-best-practices.md)
+ [

# Supported SARIF properties
](test.sarif.md)

## Quality report types
<a name="test-reporting"></a>

The Amazon CodeCatalyst test action supports the following types of quality reports. For an example on how to format these reports in your YAML, see [Quality reports YAML example](test-config-action.md#test.success-criteria-example).

**Topics**
+ [

### Test reports
](#test-reports)
+ [

### Code coverage reports
](#test-code-coverage-reports)
+ [

### Software composition analysis reports
](#test-sca-reports)
+ [

### Static analysis reports
](#test-static-analysis-reports)

### Test reports
<a name="test-reports"></a>

In CodeCatalyst, you can configure unit tests, integration tests, and system tests that run during builds. Then CodeCatalyst can create reports that contain the results of your tests.

You can use a test report to help troubleshoot problems with your tests. If you have many test reports from multiple builds, you can use your test reports to view failure rates to help you optimize your builds.

You can use the following test report file formats:
+ Cucumber JSON (.json)
+ JUnit XML (.xml)
+ NUnit XML (.xml)
+ NUnit3 XML (.xml)
+ TestNG XML (.xml)
+ Visual Studio TRX (.trx, .xml)

### Code coverage reports
<a name="test-code-coverage-reports"></a>

In CodeCatalyst, you can generate code coverage reports for your tests. CodeCatalyst provides the following code coverage metrics:

Line coverage  
Measures how many statements your tests cover. A statement is a single instruction, not including comments.  
`line coverage = (total lines covered)/(total number of lines)`

Branch coverage  
Measures how many branches your tests cover out of every possible branch of a control structure such as an `if` or `case` statement.  
`branch coverage = (total branches covered)/(total number of branches)`

The following code coverage report file formats are supported:
+ JaCoCo XML (.xml)
+ SimpleCov JSON (generated by [simplecov](https://github.com/simplecov-ruby/simplecov), not [simplecov-json](https://github.com/vicentllongo/simplecov-json), .json)
+ Clover XML (version 3, .xml)
+ Cobertura XML (.xml)
+ LCOV (.info)

### Software composition analysis reports
<a name="test-sca-reports"></a>

In CodeCatalyst, you can use software composition analysis (SCA) tools to analyze components of your application and check for known security vulnerabilities. You can discover and parse SARIF reports that detail vulnerabilities with varying severities and ways to fix them. Valid severity values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

The following SCA report file formats are supported:
+ SARIF (.sarif, .json)

### Static analysis reports
<a name="test-static-analysis-reports"></a>

You can use static analysis (SA) reports to identify source-level code defects. In CodeCatalyst, you can generate SA reports to help resolve issues in your code before you deploy it. These issues include bugs, security vulnerabilities, quality issues, and other vulnerabilities. Valid severity values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, and `INFORMATIONAL`.

CodeCatalyst provides the following SA metrics:

Bugs  
Identifies a number of possible bugs found in your source code. These bugs can include issues regarding memory safety. The following is an example of a bug.  

```
// The while loop will inadvertently index into array x out-of-bounds
int x[64];
while (int n = 0; n <= 64; n++) {
  x[n] = 0;
}
```

Security vulnerabilities  
Identifies a number of possible security vulnerabilities found in your source code. These security vulnerabilities can include issues such as storing your secret tokens in plaintext.

Quality issues  
Identifies a number of possible quality issues found in your source code. These quality issues can include issues regarding style conventions. The following is an example of a quality issue.  

```
// The function name doesn't adhere to the style convention of camelCase
int SUBTRACT(int x, int y) {
  return x-y
}
```

Other vulnerabilities  
Identifies a number of possible other vulnerabilities found in your source code.

CodeCatalyst supports the following SA report file formats:
+ PyLint (.py)
+ ESLint (.js, .jsx, .ts, .tsx)
+ SARIF (.sarif, .json)

# Adding the test action
<a name="test-add-action"></a>

Use the following procedure to add a test action to your CodeCatalyst workflow. 

------
#### [ Visual ]

**To add a test action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose **Actions**.

1. In **Actions**, choose **Test**. 

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the [Build and test actions YAML](build-action-ref.md). This reference provides detailed information on each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add a build action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Choose **Actions**.

1. In **Actions**, choose **Test**.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the [Build and test actions YAML](build-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## Test action definition
<a name="test-add-action-definition"></a>

The test action is defined as a set of YAML properties inside your workflow definition file. For information about these properties, see [Build and test actions YAML](build-action-ref.md) in the [Workflow YAML definition](workflow-reference.md).

# Viewing the results of a test action
<a name="test-view-results"></a>

Use the following instructions to view the results of a test action, including the generated logs, reports, and variables.

**To view the results of a test action**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. In the workflow diagram, choose the name of your test action, for example, **Test**.

1. To view the logs generated by an action, choose **Logs**. The logs for the various action phases are displayed. You can expand or collapse the logs as needed.

1. To view the test reports produced by the test action, choose **Reports**, or in the navigation pane, choose **Reports**. For more information, see [Quality report types](test-workflow-actions.md#test-reporting).

1. To view the configuration used for the test action, choose **Configuration**. For more information, see [Adding the test action](test-add-action.md).

1. To view the variables used by the test action, choose **Variables**. For more information, see [Using variables in workflows](workflows-working-with-variables.md).

# Skipping failed tests in an action
<a name="test.error-handling"></a>

If your action has more than one test command, you might want to allow subsequent test commands in the action to run even if a previous command fails. For example, in the following commands, you may want `test2` to run always, even if `test1` fails.

```
Steps:
- Run: npm install
- Run: npm run test1
- Run: npm run test2
```

Normally, when a step returns an error, Amazon CodeCatalyst stops the workflow action and marks it as failed. You can allow the action steps to continue to run by redirecting the error output to `null`. You can do this by adding `2>/dev/null` to the command. With this modification, the preceding example would look like the following.

```
Steps:
- Run: npm install
- Run: npm run test1 2>/dev/null
- Run: npm run test2
```

In the second code snippet, the status of the `npm install` command will be honored, but any error returned by the `npm run test1` command will be ignored. As a result the `npm run test2` command is run. By doing this, you're able to view both reports at once regardless of whether an error occurs.

# Integrating with universal-test-runner
<a name="test.universal-test-runner"></a>

Test actions integrate with the open-source command line tool `universal-test-runner`. `universal-test-runner` uses the [Test Execution Protocol](https://github.com/aws/universal-test-runner/blob/main/protocol/README.md) to run your tests for any language in a given framework. `universal-test-runner` supports the following frameworks:
+ [Gradle](https://gradle.org/)
+ [Jest](https://jestjs.io/)
+ [Maven](https://maven.apache.org/)
+ [pytest](https://pytest.org)
+ [.NET](https://learn.microsoft.com/en-us/dotnet/core/tools/)

`universal-test-runner` is installed only on the curated images for test actions. If you configure a test action to use a custom Docker Hub or Amazon ECR, you must manually install `universal-test-runner` to enable advanced testing features. To do so, install Node.js (14 or higher) on the image, then install `universal-test-runner` through `npm` using the shell command `- Run: npm install -g @aws/universal-test-runner`. For more information about installing Node.js in your container through shell commands, see [Installing and Updating Node Version Manager](https://github.com/nvm-sh/nvm#install--update-script).

For more information about `universal-test-runner`, see [What is universal-test-runner?](https://github.com/aws/universal-test-runner#-what-is-universal-test-runner)

------
#### [ Visual ]

**To use universal-test-runner in the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose **Actions**.

1. In **Actions**, choose **Test**. 

1. On the **Configuration** tab, complete the **Shell commands** field by updating the sample code with your choice of the supported frameworks. For example, to use a supported framework, you would use a `Run` command similar to the following.

   ```
   - Run: run-tests <framework>
   ```

   If the framework you want is not supported, consider contributing a custom adapter or runner. For a description of the **Shell commands** field, see [Steps](build-action-ref.md#build.configuration.steps).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To use universal-test-runner in the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow.

1. Choose **Edit**.

1. Choose **YAML**.

1. Choose **Actions**.

1. In **Actions**, choose **Test**.

1. Modify the YAML code according to your needs. For example, to use a supported framework, you would use a `Run` command similar to the following.

   ```
   Configuration:
     Steps:
       - Run: run-tests <framework>
   ```

   If the framework you want is not supported, consider contributing a custom adapter or runner. For a description of the **Steps** property, see [Steps](build-action-ref.md#build.configuration.steps).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Configuring quality reports in an action
<a name="test-config-action"></a>

This section describes how to configure a quality report in an action.

**Topics**
+ [

## Auto-discovery and manual reports
](#test.auto-discovery)
+ [

## Configuring success criteria for reports
](#test.success-criteria)
+ [

## Quality reports YAML example
](#test.success-criteria-example)

## Auto-discovery and manual reports
<a name="test.auto-discovery"></a>

When auto-discovery is enabled, CodeCatalyst searches all inputs passed into the action, and all files generated by the action itself, looking for test, code coverage, software composition analysis (SCA), and static analysis (SA) reports. You can view and manipulate each of these reports in CodeCatalyst.

You can also manually configure which reports are generated. You can specify the type of report you'd like to generate as well as the file format. For more information, see [Quality report types](test-workflow-actions.md#test-reporting).

## Configuring success criteria for reports
<a name="test.success-criteria"></a>

You can set the values that determine the success criteria for a test, code coverage, software composition analysis (SCA), or static analysis (SA) report.

Success criteria are thresholds that determine whether a report passes or fails. CodeCatalyst first generates your report, which can be a test, code coverage, SCA, or SA report, and then applies the success criteria to the generated reports. It then shows whether the success criteria were met, and to what extent. If any report does not meet the specified success criteria, the CodeCatalyst action that specified the success criteria fails.

For example, when you set the success criteria for your SCA report, the valid vulnerability values ranging from most to least severe are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`. If you set the criteria to scan for one vulnerability at `HIGH` severity, the report will fail if there is either at least one vulnerability at `HIGH` severity or no vulnerabilities at `HIGH` severity, but at least one vulnerability at a higher severity level, such as one vulnerability at `CRITICAL` severity.

If you do not specify success criteria, then:
+ The CodeCatalyst report that is generated based on your raw reports will not display success criteria.
+ Success criteria will not be used to determine whether the associated workflow action passes or fails.

------
#### [ Visual ]

**To configure success criteria**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose a workflow containing an action that generates a report. This is the report for which you want to apply success criteria. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that you have configured to generate CodeCatalyst reports.

1. Choose the **Outputs** tab.

1. Under **Auto-discover reports** or under **Manually configure reports**, choose **Success criteria**.

   Success criteria appear. Depending on your previous selections, you may see any or all of these options:

   **Pass rate**

   Specify the percentage of tests in a test report that must pass for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. The pass rate criteria are applied only to test reports. For more information about test reports, see [Test reports](test-workflow-actions.md#test-reports).

   **Line coverage**

   Specify the percentage of lines in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Line coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

   **Branch coverage**

   Specify the percentage of branches in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Branch coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

   **Vulnerabilities (SCA)**

   Specify the maximum number and severity of vulnerabilities permitted in the SCA report for the associated CodeCatalyst report to be marked as passed. To specify vulnerabilities, you must specify:
   + The minimum severity of the vulnerabilities you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

     For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` vulnerabilities will be tallied.
   + The maximum number of vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

   Vulnerabilities criteria are applied only to SCA reports. For more information about SCA reports, see [Software composition analysis reports](test-workflow-actions.md#test-sca-reports).

   **Bugs**

   Specify the maximum number and severity of bugs permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify bugs, you must specify:
   + The minimum severity of the bugs you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

     For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` bugs will be tallied.
   + The maximum number of bugs of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

   Bugs criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

   **Security vulnerabilities**

   Specify the maximum number and severity of security vulnerabilities permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify security vulnerabilities, you must specify:
   + The minimum severity of the security vulnerabilities you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

     For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` security vulnerabilities will be tallied.
   + The maximum number of security vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

   Security vulnerabilities criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

   **Quality issues**

   Specify the maximum number and severity of quality issues permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify quality issues, you must specify:
   + The minimum severity of the quality issues you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

     For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` quality issues will be tallied.
   + The maximum number of quality issues of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

   Quality issues criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see [Static analysis reports](test-workflow-actions.md#test-static-analysis-reports).

1. Choose **Commit**.

1. Run your workflow to have CodeCatalyst apply success criteria to your raw reports, and regenerate the associated CodeCatalyst reports with success criteria information included. For more information, see [Starting a workflow run manually](workflows-manually-start.md).

------
#### [ YAML ]

**To configure success criteria**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose a workflow containing an action that generates a report. This is the report for which you want to apply success criteria. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the workflow diagram, choose the action that you have configured to generate CodeCatalyst reports.

1. In the details pane, choose the **Outputs** tab.

1. In the action, in `AutoDiscoverReports` section, or in the `Reports` section, add a **SuccessCriteria** property, along with `PassRate`, `LineCoverage`, `BranchCoverage`, `Vulnerabilities`, `StaticAnalysisBug`, `StaticAnalysisSecurity`, and `StaticAnalysisQuality` properties.

   For an explanation of each of these properties, consult the [Build and test actions YAML](build-action-ref.md).

1. Choose **Commit**.

1. Run your workflow to have CodeCatalyst apply success criteria to your raw reports, and regenerate the associated CodeCatalyst reports with the success criteria information included. For more information on starting a workflow, see [Starting a workflow run manually](workflows-manually-start.md).

------

## Quality reports YAML example
<a name="test.success-criteria-example"></a>

 The following example shows how to manually configure four reports: a test report, a code coverage report, a software composition analysis report, and a static analysis report.

```
Reports:
  MyTestReport:
    Format: JUNITXML
    IncludePaths:
      - "*.xml"
    ExcludePaths:
      - report1.xml
      SuccessCriteria:
        PassRate: 90
  MyCoverageReport:
    Format: CLOVERXML
    IncludePaths:
      - output/coverage/jest/clover.xml
      SuccessCriteria:
        LineCoverage: 75
        BranchCoverage: 75
  MySCAReport:
    Format: SARIFSCA
    IncludePaths:
      - output/sca/reports.xml
      SuccessCriteria:
        Vulnerabilities:
          Number: 5
          Severity: HIGH
  MySAReport:
    Format: ESLINTJSON
    IncludePaths:
      - output/static/eslint.xml
      SuccessCriteria:
        StaticAnalysisBug:
          Number: 10
          Severity: MEDIUM
        StaticAnalysisSecurity:
          Number: 5
          Severity: CRITICAL
        StaticAnalysisQuality:
          Number: 0
          Severity: INFORMATIONAL
```

# Best practices for testing
<a name="test-best-practices"></a>

When using the testing features provided by CodeCatalyst, we recommend that you follow these best practices.

**Topics**
+ [

## Auto-discovery
](#test.best-auto-discovery)
+ [

## Success criteria
](#test.best-success-criteria)
+ [

## Include/exclude paths
](#test.best-include-exclude)

## Auto-discovery
<a name="test.best-auto-discovery"></a>

When configuring actions in CodeCatalyst, auto-discovery lets you automatically discover outputs of various tools, such as JUnit test reports, and generate relevant CodeCatalyst reports from them. Auto-discovery helps ensure that reports continue to be generated even if names or paths to discovered outputs change. When new files are added, CodeCatalyst automatically discovers them and produces relevant reports. However, if you use auto-discovery, it is important to factor in some of the following aspects of this feature:
+ When you activate auto-discovery in your action, all automatically discovered reports of the same type will share the same success criteria. For example, a shared criteria such as minimum pass rate would apply to all auto-discovered test reports. If you need different criteria for reports of the same type, you must explicitly configure each of these reports.
+ Auto-discovery can also find reports that are produced by your dependencies and, if success criteria are configured, might fail the action on these reports. This issue can be addressed by updating the exclude path configuration.
+ Auto-discovery is not guaranteed to produce the same list of reports every time, because it scans the action at runtime. In the case where you want a particular report to always be produced, you should configure reports explicitly. For example, if tests were to stop running as part of your build, the test framework would not produce any outputs and, as a result, no test report would be produced and the action might succeed. If you want the success of your action to depend on that particular test, then you must explicitly configure that report.

**Tip**  
When getting started on a new or existing project, use auto-discovery for the entire project directory (include `**/*`). This invokes report generation across all files in your project, including those within subdirectories.

For more information, see [Configuring quality reports in an action](test-config-action.md).

## Success criteria
<a name="test.best-success-criteria"></a>

You can enforce quality thresholds on your reports by configuring success criteria. For example, if two code coverage reports were auto-discovered, one with a line coverage of 80% and the other with a line coverage of 60%, you have the following options:
+ Set the auto-discovery success criteria for line coverage at 80%. This would cause the first report to pass and the second report to fail, which would result in the overall action failing. To unblock the workflow, add new tests to your project until the line coverage for the second report exceeds 80%.
+ Set the auto-discovery success criteria for line coverage at 60%. This would cause both reports to pass, which would result in the action succeeding. You could then work on increasing the code coverage in the second report. However, with this approach, you cannot guarantee that the coverage in the first report is not dropping below 80%.
+ Explicitly configure one or both of the reports by using the visual editor or adding an explicit YAML section and path for each report. This would allow you to configure separate success criteria and custom names for each report. However, with this approach, the action could fail if the report paths change.

For more information, see [Configuring success criteria for reports](test-config-action.md#test.success-criteria).

## Include/exclude paths
<a name="test.best-include-exclude"></a>

When reviewing action results, you can adjust the list of reports that are generated by CodeCatalyst by configuring `IncludePaths` and `ExcludePaths`.
+ Use `IncludePaths` to specify the files and file paths you want CodeCatalyst to include when searching for reports. For example, if you specify `"/test/report/*"`, CodeCatalyst searches the entire build image used by the action looking for the `/test/report/` directory. When it finds that directory, CodeCatalyst then looks for reports in that directory.
**Note**  
For manually configured reports, `IncludePaths` must be a glob pattern that matches a single file.
+ Use `ExcludePaths` to specify the files and file paths you want CodeCatalyst to exclude when searching for reports. For example, if you specify `"/test/reports/**/*"`, CodeCatalyst will not search for files in the `/test/reports/` directory. To ignore all files in a directory, use the `**/*` glob pattern.

The following are examples of possible glob patterns.


| Pattern | Description | 
| --- | --- | 
|  `*.*`  |  Matches all object names in the current directory that contain a dot  | 
|  `*.xml`  |  Matches all object names in the current directory ending with `.xml`  | 
|  `*.{xml,txt}`  |  Matches all object names in the current directory ending with `.xml` or `.txt`  | 
|  `**/*.xml`  |  Matches object names across all directories ending with `.xml`  | 
|  `testFolder`  |  Matches an object called `testFolder`, treating it as a file  | 
|  `testFolder/*`  |  Matches objects in one level of the subfolder from `testFolder`, such as `testFolder/file.xml`  | 
|  `testFolder/*/*`  |  Matches objects in two levels of the subfolder from `testFolder`, such as `testFolder/reportsFolder/file.xml`  | 
|  `testFolder/**`  |  Matches subfolder `testFolder` as well as files below `testFolder`, such as `testFolder/file.xml` and `testFolder/otherFolder/file.xml`  | 

CodeCatalyst interprets the glob patterns as follows:
+ The slash (`/`) character separates directories in file paths.
+ The asterisk (`*`) character matches zero or more characters of a name component without crossing folder boundaries.
+ A double asterisk (`**`) matches zero or more characters of a name component across all directories.

**Note**  
`ExcludePaths` takes precedence over `IncludePaths`. If both `IncludePaths` and `ExcludePaths` include the same folder, that folder is not scanned for reports.

# Supported SARIF properties
<a name="test.sarif"></a>

Static Analysis Results Interchange Format (SARIF) is an output file format which is available in software composition analysis (SCA) and static analysis reports in Amazon CodeCatalyst. The following example shows how to manually configure SARIF in a static analysis report:

```
Reports:
MySAReport:
Format: SARIFSA
IncludePaths:
    - output/sa_report.json
SuccessCriteria:
    StaticAnalysisFinding:
    Number: 25
    Severity: HIGH
```

CodeCatalyst supports the following SARIF properties which can be used to optimize how the analysis results will appear in your reports.

**Topics**
+ [

## `sarifLog` object
](#test.sarif.sarifLog)
+ [

## `run` object
](#test.sarif.run)
+ [

## `toolComponent` object
](#test.sarif.toolComponent)
+ [

## `reportingDescriptor` object
](#test.sarif.reportingDescriptor)
+ [

## `result` object
](#test.sarif.result)
+ [

## `location` object
](#test.sarif.location)
+ [

## `physicalLocation` object
](#test.sarif.physicalLocation)
+ [

## `logicalLocation` object
](#test.sarif.logicalLocation)
+ [

## `fix` object
](#test.sarif.fix)

## `sarifLog` object
<a name="test.sarif.sarifLog"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `$schema`  |  Yes  |  The URI of the SARIF JSON schema for version [2.1.0](https://json.schemastore.org/sarif-2.1.0.json).  | 
|  `version`  |  Yes  |  CodeCatalyst only supports SARIF version 2.1.0.  | 
|  `runs[]`  |  Yes  |  A SARIF file contains an array of one or more runs, each of which represents a single run of the analysis tool.  | 

## `run` object
<a name="test.sarif.run"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `tool.driver`  |  Yes  |  A `toolComponent` object that describes the analysis tool.  | 
|  `tool.name`  |  No  |  A property that indicates the name of the tool used to perform analysis.  | 
|  `results[]`  |  Yes  |  The results of the analysis tool that are displayed on CodeCatalyst.  | 

## `toolComponent` object
<a name="test.sarif.toolComponent"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `name`  |  Yes  |  The name of the analysis tool.  | 
|  `properties.artifactScanned`  |  No  |  A total number of artifacts analyzed by the tool.  | 
|  `rules[]`  |  Yes  |  An array of `reportingDescriptor` objects that represent rules. Based on these rules, the analysis tool finds problems in the code that is analyzed.  | 

## `reportingDescriptor` object
<a name="test.sarif.reportingDescriptor"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `id`  |  Yes  |  The unique identifier for the rule that is used to reference a finding. Maximum length: 1,024 characters  | 
|  `name`  |  No  |  The display name of the rule. Maximum length: 1,024 characters  | 
|  `shortDescription.text`  |  No  |  A shortened description of the rule. Maximum length: 3,000 characters  | 
|  `fullDescription.text`  |  No  |  A complete description of the rule. Maximum length: 3,000 characters  | 
|  `helpUri`  |  No  |  A string that can be localized to contain the absolute URI of the primary documentation for the rule. Maximum length: 3,000 characters  | 
|  `properties.unscore`  |  No  |  A flag that indicates if the scan finding has been scored.  | 
|  `properties.score.severity`  |  No  |  A fixed set of strings that specify the severity level of the finding. Maximum length: 1,024 characters  | 
|  `properties.cvssv3_baseSeverity`  |  No  |  A qualitative severity rating of [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document).  | 
|  `properties.cvssv3_baseScore`  |  No  |  A CVSS v3 Base Score ranging from [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss).  | 
|  `properties.cvssv2_severity`  |  No  |  If CVSS v3 values are not available, CodeCatalyst searches for CVSS v2 values.  | 
|  `properties.cvssv2_score`  |  No  |  A CVSS v2 Base Score ranging from [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss).  | 
|  `properties.severity`  |  No  |  A fixed set of strings that specify the severity level of the finding. Maximum length: 1,024 characters  | 
|  `defaultConfiguration.level`  |  No  |  The default severity of a rule.  | 

## `result` object
<a name="test.sarif.result"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `ruleId`  |  Yes  |  The unique identifier for the rule that is used to reference a finding. Maximum length: 1,024 characters  | 
|  `ruleIndex`  |  Yes  |  The index of the associated rule in the tool component `rules[]`.  | 
|  `message.text`  |  Yes  |  A message that describes the result and displays the message for each finding. Maximum length: 3,000 characters  | 
|  `rank`  |  No  |  A value between 0.0 to 100.0 inclusive that represents the priority or importance of the result. This scale values 0.0 being the lowest priority and 100.0 being the highest priority.  | 
|  `level`  |  No  |  The severity of the result. Maximum length: 1,024 characters  | 
|  `properties.unscore`  |  No  |  A flag that indicates if the scan finding has been scored.  | 
|  `properties.score.severity`  |  No  |  A fixed set of strings that specify the severity level of the finding. Maximum length: 1,024 characters  | 
|  `properties.cvssv3_baseSeverity`  |  No  |  A qualitative severity rating of [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document).  | 
|  `properties.cvssv3_baseScore`  |  No  |  A CVSS v3 Base Score ranging from [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss).  | 
|  `properties.cvssv2_severity`  |  No  |  If CVSS v3 values are not available, CodeCatalyst searches for CVSS v2 values.  | 
|  `properties.cvssv2_score`  |  No  |  A CVSS v2 Base Score ranging from [0.0 - 10.0](https://nvd.nist.gov/vuln-metrics/cvss).  | 
|  `properties.severity`  |  No  |  A fixed set of strings that specify the severity level of the finding. Maximum length: 1,024 characters  | 
|  `locations[]`  |  Yes  |  The set of locations where the result was detected. Only one location should be included unless the problem can only be corrected by making a change at every specified location. CodeCatalyst uses the first value in the location array to annotate the result. Maximum number of `location` objects: 10  | 
|  `relatedLocations[]`  |  No  |  A list of additional locations references in the finding. Maximum number of `location` objects: 50  | 
|  `fixes[]`  |  No  |  An array of `fix` objects that represent the recommendation provided by the scanning tool. CodeCatalyst uses the first recommendation in the `fixes` array.  | 

## `location` object
<a name="test.sarif.location"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `physicalLocation`  |  Yes  |  Identifies the artifact and region.  | 
|  `logicalLocations[]`  |  No  |  The set of locations described by name without reference to the artifact.  | 

## `physicalLocation` object
<a name="test.sarif.physicalLocation"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `artifactLocation.uri`  |  Yes  |  The URI indicating the location of an artifact, usually a file either in the repository or generated during a build.  | 
|  `fileLocation.uri`  |  No  |  The fall back URI indicating the location of the file. This is used if `artifactLocation.uri` returns empty.  | 
|  `region.startLine`  |  Yes  |  The line number of the first character in the region.  | 
|  `region.startColumn`  |  Yes  |  The column number of the first character in the region.  | 
|  `region.endLine`  |  Yes  |  The line number of the last character in the region.  | 
|  `region.endColumn`  |  Yes  |  The column number of the last character in the region.  | 

## `logicalLocation` object
<a name="test.sarif.logicalLocation"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `fullyQualifiedName`  |  No  |  Additional information that describes the location of the result. Maximum length: 1,024 characters  | 

## `fix` object
<a name="test.sarif.fix"></a>


| Name | Required | Description | 
| --- | --- | --- | 
|  `description.text`  |  No  |  A message that displays a recommendation for each finding. Maximum length: 3,000 characters  | 
|  `artifactChanges.[0].artifactLocation.uri`  |  No  |  The URI indicating the location of the artifact that needs to be updated.  | 

# Deploying with workflows
<a name="deploy"></a>



Using [CodeCatalyst workflows](workflow.md), you can deploy applications and other resources to various targets such as Amazon ECS, AWS Lambda, and more. 

## How do I deploy an application?
<a name="deploy-concepts"></a>

To deploy an application or resource through CodeCatalyst, you first create a workflow, and then specify a deploy action inside of it. A *deploy action* is a workflow building block that defines *what* you want to deploy, *where* you want to deploy it, and *how* you want to deploy it (for example, using a blue/green scheme). You add a deploy action to your workflow using the CodeCatalyst console's visual editor, or YAML editor.

The high-level steps to deploy an application or resource are as follows.

**To deploy an application (high-level tasks)**

1. In your CodeCatalyst project, you **add source code** for an application you want to deploy. For more information, see [Storing source code in repositories for a project in CodeCatalyst](source-repositories.md).

1. In your CodeCatalyst project, you **add an environment** that defines the target AWS account and optional Amazon Virtual Private Cloud (VPC) that you want to deploy to. For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

1. In your CodeCatalyst project, you **create a workflow**. The workflow is where you define how to build, test, and deploy your application. For more information, see [Getting started with workflows](workflows-getting-started.md).

1. In the workflow, you **add a trigger**, a **build action**, and optionally, a **test action**. For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md), [Adding the build action](build-add-action.md), and [Adding the test action](test-add-action.md).

1. In the workflow, you **add a deploy action**. You can choose from several CodeCatalyst-provided deploy actions to your application to different targets, such as Amazon ECS. (You can also use a build action or a GitHub Action to deploy your application. For more information about the build action and GitHub Actions, see [Alternatives to deploy actions](#deploy-concepts-alternatives).)

1. You **start the workflow** either manually or automatically through a trigger. The workflow runs the build, test, and deploy actions in sequence to deploy your application and resources to the target. For more information, see [Starting a workflow run manually](workflows-manually-start.md).

## List of deploy actions
<a name="deploy-concepts-action-supported"></a>

The following deploy actions are available:
+ Deploy CloudFormation stack – This action creates a CloudFormation stack in AWS based on an [CloudFormation template](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) or [AWS Serverless Application Model template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html) that you provide. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md).
+ Deploy to Amazon ECS – This action registers a [task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions) file that you provide. For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md).
+ Deploy to Kubernetes cluster – This action deploys an application to an Amazon Elastic Kubernetes Service cluster. For more information, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md).
+ AWS CDK deploy – This action deploys an [AWS CDK app](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_concepts) into AWS. For more information, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md).

**Note**  
There are other CodeCatalyst actions that can deploy resources; however, they are not considered *deploy* actions because their deployment information doesn't appear on the **Environments** page. To learn more about the **Environments** page and viewing deployments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Viewing deployment information](deploy-view-deployment-info.md).

## Benefits of deploy actions
<a name="deploy-concepts-why-use"></a>

Using deploy actions within a workflow has the following benefits:
+ **Deployment history** – View a history of your deployments to help manage and communicate changes in your deployed software. 
+ **Traceability** – Track the status of your deployments through the CodeCatalyst console, and see when and where each application revision was deployed.
+ **Rollbacks** – Roll back deployments automatically if there are errors. You can also configure alarms to activate deployment rollbacks.
+ **Monitoring** – Watch your deployment as it progresses through the various stages of your workflow.
+ **Integration with other CodeCatalyst features** – Store source code and then build, test, and deploy it, all from one application.

## Alternatives to deploy actions
<a name="deploy-concepts-alternatives"></a>

You don't have to use deploy actions, although they are recommended because they offer the benefits outlined in the preceding section. Instead, you can use the following [CodeCatalyst actions](workflows-actions.md#workflows-actions-types-cc) :
+ A **build** action.

  Typically, you use build actions if you want to deploy to a target for which a corresponding deploy action does not exist, or if you want more control over the deployment procedure. For more information about using build actions to deploy resources, see [Building with workflows](build-workflow-actions.md).
+ A **GitHub Action**.

  You can use a [GitHub Action](workflows-actions.md#workflows-actions-types-github) inside a CodeCatalyst workflow to deploy applications and resources (instead of a CodeCatalyst action). For information about how to use GitHub Actions inside a CodeCatalyst workflow, see [Integrating with GitHub Actions](integrations-github-actions.md)

You can also use the following AWS services to deploy your application, if you don't want to use a CodeCatalyst workflow to do so:
+ AWS CodeDeploy – see [What is CodeDeploy?](https://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html)
+ AWS CodeBuild and AWS CodePipeline – see [What is AWS CodeBuild?](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html) and [What is AWS CodePipeline?](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html)
+ CloudFormation – see [What is CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)

Use CodeDeploy, CodeBuild, CodePipeline, and CloudFormation services for complex, enterprise deployments.

**Topics**
+ [

## How do I deploy an application?
](#deploy-concepts)
+ [

## List of deploy actions
](#deploy-concepts-action-supported)
+ [

## Benefits of deploy actions
](#deploy-concepts-why-use)
+ [

## Alternatives to deploy actions
](#deploy-concepts-alternatives)
+ [

# Deploying to Amazon ECS with a workflow
](deploy-action-ecs.md)
+ [

# Deploying to Amazon EKS with a workflow
](deploy-action-eks.md)
+ [

# Deploying an CloudFormation stack
](deploy-action-cfn.md)
+ [

# Deploying an AWS CDK app with a workflow
](cdk-dep-action.md)
+ [

# Bootstrapping an AWS CDK app with a workflow
](cdk-boot-action.md)
+ [

# Publishing files to Amazon S3 with a workflow
](s3-pub-action.md)
+ [

# Deploying into AWS accounts and VPCs
](deploy-environments.md)
+ [

# Displaying the app URL in the workflow diagram
](deploy-app-url.md)
+ [

# Removing a deployment target
](deploy-remove-target.md)
+ [

# Tracking deployment status by commit
](track-changes.md)
+ [

# Viewing the deployment logs
](deploy-deployment-logs.md)
+ [

# Viewing deployment information
](deploy-view-deployment-info.md)

# Deploying to Amazon ECS with a workflow
<a name="deploy-action-ecs"></a>

This section describes how to deploy a containerized application into an Amazon Elastic Container Service cluster using a CodeCatalyst workflow. To accomplish this, you must add the **Deploy to Amazon ECS** action to your workflow. This action registers a [task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions) file that you provide. Upon registration, the task definition is instantiated by your [Amazon ECS service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) running in your [Amazon ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters). "Instantiating a task definition" is equivalent to deploying an application into Amazon ECS.

To use this action, you must have an Amazon ECS cluster, service, and task definition file ready.

For more information about Amazon ECS, see the *Amazon Elastic Container Service Developer Guide*.

**Tip**  
For a tutorial that shows you how to use the **Deploy to Amazon ECS ** action, see [Tutorial: Deploy an application to Amazon ECS](deploy-tut-ecs.md).

**Tip**  
For a working example of the **Deploy to Amazon ECS** action, create a project with either the **Node.js API with AWS Fargate** or **Java API with AWS Fargate** blueprint. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).

**Topics**
+ [

## Runtime image used by the 'Deploy to Amazon ECS' action
](#deploy-action-ecs-runtime)
+ [

# Tutorial: Deploy an application to Amazon ECS
](deploy-tut-ecs.md)
+ [

# Adding the 'Deploy to Amazon ECS' action
](deploy-action-ecs-adding.md)
+ [

# 'Deploy to Amazon ECS' variables
](deploy-action-ecs-variables.md)
+ [

# 'Deploy to Amazon ECS' action YAML
](deploy-action-ref-ecs.md)

## Runtime image used by the 'Deploy to Amazon ECS' action
<a name="deploy-action-ecs-runtime"></a>

The **Deploy to Amazon ECS** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Tutorial: Deploy an application to Amazon ECS
<a name="deploy-tut-ecs"></a>

In this tutorial, you learn how to deploy a serverless application into Amazon Elastic Container Service (Amazon ECS) using a workflow, Amazon ECS, and a few other AWS services. The deployed application is a simple Hello World website built on an Apache web server Docker image. The tutorial walks you through the required preparation work such as setting up a cluster, and then describes how to create a workflow to build and deploy the application.

**Tip**  
Instead of working your way through this tutorial, you can use a blueprint that does a complete Amazon ECS setup for you. You'll need to use either the **Node.js API with AWS Fargate** or **Java API with AWS Fargate** blueprint. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).

**Topics**
+ [

## Prerequisites
](#deploy-tut-ecs-prereqs)
+ [

## Step 1: Set up an AWS user and AWS CloudShell
](#deploy-tut-ecs-user-cloudshell)
+ [

## Step 2: Deploy a placeholder application into Amazon ECS
](#deploy-tut-ecs-placeholder)
+ [

## Step 3: Create an Amazon ECR image repository
](#deploy-tut-ecs-ecr)
+ [

## Step 4: Create AWS roles
](#deploy-tut-ecs-build-deploy-roles)
+ [

## Step 5: Add AWS roles to CodeCatalyst
](#deploy-tut-ecs-import-roles)
+ [

## Step 6: Create a source repository
](#deploy-tut-ecs-source-repo)
+ [

## Step 7: Add source files
](#deploy-tut-ecs-source-files)
+ [

## Step 8: Create and run a workflow
](#deploy-tut-ecs-workflow)
+ [

## Step 9: Make a change to your source files
](#deploy-tut-ecs-change)
+ [

## Clean up
](#deploy-tut-ecs-cleanup)

## Prerequisites
<a name="deploy-tut-ecs-prereqs"></a>

Before you begin:
+ You need a CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ In your space, you need an empty project called:

  ```
  codecatalyst-ecs-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need a CodeCatalyst **environment** called:

  ```
  codecatalyst-ecs-environment
  ```

  Configure this environment as follows:
  + Choose any type, such as **Non-production**.
  + Connect your AWS account to it.
  + For the **Default IAM role**, choose any role. You'll specify a different role later.

  For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Step 1: Set up an AWS user and AWS CloudShell
<a name="deploy-tut-ecs-user-cloudshell"></a>

The first step in this tutorial is to create a user in AWS IAM Identity Center, and launch an AWS CloudShell instance as this user. For the duration of this tutorial, CloudShell is your development computer and is where you configure AWS resources and services. Delete this user after completing the tutorial.

**Note**  
Do not use your root user for this tutorial. You must create a separate user or else you may experience problems when performing actions in the AWS Command Line Interface (CLI) later on.

For more information about IAM Identity Center users and CloudShell, see the *AWS IAM Identity Center User Guide* and *AWS CloudShell User Guide*. 

**To create an IAM Identity Center user**

1. Sign in to the AWS Management Console and open the AWS IAM Identity Center console at [https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/).
**Note**  
Make sure you sign in using the AWS account that is connected to your CodeCatalyst space. You can verify which account is connected by navigating to your space and choosing the **AWS accounts** tab. For more information, see [Creating a space](spaces-create.md).

1. In the navigation pane, choose **Users**, and then choose **Add user**.

1. In **Username**, enter:

   ```
   CodeCatalystECSUser
   ```

1. Under **Password**, choose **Generate a one-time password that you can share with this user**.

1. In **Email address** and **Confirm email address**, enter an email address that doesn't already exist in IAM Identity Center.

1. In **First name** and **Last name**, enter:

   ```
   CodeCatalystECSUser
   ```

1. In **Display name**, keep the automatically generated name:

   ```
   CodeCatalystECSUser CodeCatalystECSUser
   ```

1. Choose **Next**.

1. On the **Add user to groups** page, choose **Next**.

1. On the **Review and add user** page, review the information and choose **Add user**.

   A **One-time password** dialog box appears.

1. Choose **Copy** and then paste the sign-in information, including the AWS access portal URL and the one-time password.

1. Choose **Close**.

**To create a permission set**

You'll assign this permission set to `CodeCatalystECSUser` later.

1. In the navigation pane, choose **Permission sets**, and then choose **Create permission set**.

1. Choose **Predefined permission set** and then select **AdministratorAccess**. This policy provides full permissions to all AWS services. 

1. Choose **Next**.

1. In **Permission set name**, enter:

   ```
   CodeCatalystECSPermissionSet
   ```

1. Choose **Next**.

1. On the **Review and create** page, review the information and choose **Create**.

**To assign the permission set to CodeCatalystECSUser**

1. In the navigation pane, choose **AWS accounts**, and then select the check box next to the AWS account that you're currently signed in to.

1. Choose **Assign users or groups**.

1. Choose the **Users** tab.

1. Select the check box next to `CodeCatalystECSUser`.

1. Choose **Next**.

1. Select the check box next to `CodeCatalystECSPermissionSet`.

1. Choose **Next**.

1. Review the information and choose **Submit**.

   You have now assigned `CodeCatalystECSUser` and `CodeCatalystECSPermissionSet` to your AWS account, binding them together.

**To sign out and sign back in as CodeCatalystECSUser**

1. Before you sign out, make sure you have the AWS access portal URL and the username and one-time password for `CodeCatalystECSUser`. You should have copied this information to a text editor earlier.
**Note**  
If you do not have this information, go to the `CodeCatalystECSUser` details page in IAM Identity Center, choose **Reset password**, **Generate a one-time password [...]**, and **Reset password** again to display the information on the screen.

1. Sign out of AWS.

1. Paste the AWS access portal URL into your browser's address bar.

1. Sign in with the username and one-time password for `CodeCatalystECSUser`.

1. In **New password**, enter a password, and choose **Set new password**.

   An **AWS account** box appears on the screen.

1. Choose **AWS account**, and then choose the name of the AWS account to which you assigned the `CodeCatalystECSUser` user and permission set.

1. Next to the `CodeCatalystECSPermissionSet`, choose **Management console**.

   The AWS Management Console appears. You are now signed in as `CodeCatalystECSUser` with the appropriate permissions.

**To launch an AWS CloudShell instance**

1. As `CodeCatalystECSUser`, in the top navigation bar, choose the AWS icon (![\[AWS icon\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/deploy/aws-logo.png)).

   The main page of the AWS Management Console appears.

1. In the top navigation bar, choose the AWS CloudShell icon (![\[CloudShell icon\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/deploy/CloudShell.png)).

   CloudShell opens. Wait while the CloudShell environment is created.
**Note**  
If you don't see the CloudShell icon, make sure that you're in a [Region supported by CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/faq-list.html#regions-available). This tutorial assumes you are in the US West (Oregon) Region.

**To verify that the AWS CLI is installed**

1. In the CloudShell terminal, enter:

   ```
   aws --version
   ```

1. Check that a version appears.

   The AWS CLI is already configured for the current user, `CodeCatalystECSUser`, so there is no need to configure AWS CLI keys and credentials, as is normally the case.

## Step 2: Deploy a placeholder application into Amazon ECS
<a name="deploy-tut-ecs-placeholder"></a>

In this section, you manually deploy a placeholder application into Amazon ECS. This placeholder application will be replaced by the Hello World application deployed by your workflow. The placeholder application is Apache Web Server.

For more information about Amazon ECS, see the *Amazon Elastic Container Service Developer Guide*.

Complete the following series of procedures to deploy the placeholder application.<a name="deploy-tut-ecs-create-task-execution-role"></a>

**To create the task execution role**

This role grants Amazon ECS and AWS Fargate permission to make API calls on your behalf. 

1. Create a trust policy:

   1. In AWS CloudShell, enter the following command:

      ```
      cat > codecatalyst-ecs-trust-policy.json
      ```

      A blinking prompt appears in the CloudShell terminal.

   1. Enter the following code at the prompt:

------
#### [ JSON ]

****  

      ```
      {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
          {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
              "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
          }
        ]
      }
      ```

------

   1. Place your cursor after the last curly bracket (`}`).

   1. Press **Enter** and then **Ctrl\$1d** to save the file and exit cat.

1. Create a task execution role:

   ```
   aws iam create-role \
         --role-name codecatalyst-ecs-task-execution-role \
         --assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
   ```

1. Attach the AWS managed `AmazonECSTaskExecutionRolePolicy` policy to the role:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-ecs-task-execution-role \
         --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
   ```

1. Display the role’s details:

   ```
   aws iam get-role \
         --role-name codecatalyst-ecs-task-execution-role
   ```

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role`. You will need this Amazon Resource Name (ARN) later.

**To create an Amazon ECS cluster**

This cluster will contain the Apache placeholder application, and later, the Hello World application. 

1. As `CodeCatalystECSUser`, in AWS CloudShell, create an empty cluster:

   ```
   aws ecs create-cluster --cluster-name codecatalyst-ecs-cluster
   ```

1. (Optional) Verify that the cluster was created successfully:

   ```
   aws ecs list-clusters
   ```

   The ARN of the `codecatalyst-ecs-cluster` cluster should appear in the list, indicating a successful creation.

**To create a task definition file**

The task definition file indicates to run the [Apache 2.4 Web server](https://hub.docker.com/_/httpd) Docker image (`httpd:2.4`) which is pulled from DockerHub.

1. As `CodeCatalystECSUser`, in AWS CloudShell, create a task definition file:

   ```
   cat > taskdef.json
   ```

1. Paste the following code at the prompt:

   ```
   {
       "executionRoleArn": "arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role",
       "containerDefinitions": [
           {
               "name": "codecatalyst-ecs-container",
               "image": "httpd:2.4",
               "essential": true,
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ]
           }
       ],
       "requiresCompatibilities": [
           "FARGATE"
       ],
       "cpu": "256",
       "family": "codecatalyst-ecs-task-def",
       "memory": "512",
       "networkMode": "awsvpc"
   }
   ```

   In the preceding code, replace *arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role*

   with the ARN of the task execution role that you noted in [To create the task execution role](#deploy-tut-ecs-create-task-execution-role).

1. Place your cursor after the last curly bracket (`}`).

1. Press **Enter** and then **Ctrl\$1d** to save the file and exit cat.

**To register the task definition file with Amazon ECS**

1. As `CodeCatalystECSUser`, in AWS CloudShell, register the task definition:

   ```
   aws ecs register-task-definition \
       --cli-input-json file://taskdef.json
   ```

1. (Optional) Verify that the task definition was registered:

   ```
   aws ecs list-task-definitions
   ```

   The `codecatalyst-ecs-task-def` task definition should appear in the list.

**To create the Amazon ECS service**

The Amazon ECS service runs the tasks (and associated Docker containers) of the Apache placeholder application, and later, the Hello World application.

1. As `CodeCatalystECSUser`, switch to the Amazon Elastic Container Service console if you haven't done so already.

1. Choose the cluster you created earlier, `codecatalyst-ecs-cluster`.

1. In the **Services** tab, choose **Create**.

1. In the **Create** page, do the following:

   1. Keep all default settings except for those listed next.

   1. For **Launch type**, choose **FARGATE**.

   1. Under **Task definition**, in the **Family** drop-down list, choose:

      `codecatalyst-ecs-task-def`

   1. For **Service name**, enter:

      ```
      codecatalyst-ecs-service
      ```

   1. For **Desired tasks**, enter:

      ```
      3
      ```

      In this tutorial, each task launches a single Docker container.

   1. Expand the **Networking** section.

   1. For **VPC**, choose any VPC.

   1. For **Subnets**, choose any subnet.
**Note**  
Only specify one subnet. That's all that is needed for this tutorial.
**Note**  
If you don’t have a VPC and subnet, create them. See [Create a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC), and [Create a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet) in the *Amazon VPC User Guide*.

   1. For **Security group**, choose **Create a new security group**, and then do the following:

      1. For **Security group name**, enter:

         ```
         codecatalyst-ecs-security-group
         ```

      1. For **Security group description**, enter:

         ```
         CodeCatalyst ECS security group
         ```

      1. Choose **Add rule**. For **Type**, choose **HTTP**, and for **Source**, choose **Anywhere**.

   1. At the bottom, choose **Create**.

   1. Wait while the service is created. This may take a few minutes.

1. Choose the **Tasks** tab, and then choose the refresh button. Verify that all three tasks have their **Last Status** column set to **Running**.

**(Optional) To verify that your Apache placeholder application is running**

1. In the **Tasks** tab, choose any one of the three tasks.

1. In the **Public IP** field, choose **open address**.

   An `It Works!` page appears. This indicates that the Amazon ECS service successfully started a task that launched a Docker container with the Apache image.

   At this point in the tutorial, you have manually deployed an Amazon ECS cluster, service, and task definition, as well as an Apache placeholder application. With all these items in place, you are now ready to create a workflow that will replace the Apache placeholder application with the tutorial’s Hello World application.

## Step 3: Create an Amazon ECR image repository
<a name="deploy-tut-ecs-ecr"></a>

In this section, you create a private image repository in Amazon Elastic Container Registry (Amazon ECR). This repository stores the tutorial’s Docker image that will replace the Apache placeholder image you deployed previously. 

For more information about Amazon ECR, see the *Amazon Elastic Container Registry User Guide*.

**To create an image repository in Amazon ECR**

1. As `CodeCatalystECSUser`, in AWS CloudShell, create an empty repository in Amazon ECR:

   ```
   aws ecr create-repository --repository-name codecatalyst-ecs-image-repo
   ```

1. Display the Amazon ECR repository’s details:

   ```
   aws ecr describe-repositories \
         --repository-names codecatalyst-ecs-image-repo
   ```

1. Note the `“repositoryUri”:` value, for example, `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`.

   You need it later when adding the repository to your workflow. 

## Step 4: Create AWS roles
<a name="deploy-tut-ecs-build-deploy-roles"></a>

In this section, you create AWS IAM roles that your CodeCatalyst workflow will need in order to function. These roles are:
+ **Build role** – Grants the CodeCatalyst build action (in the workflow) permission to access your AWS account and write to Amazon ECR and Amazon EC2.
+ **Deploy role** – Grants the CodeCatalyst **Deploy to ECS** action (in the workflow) permission to access your AWS account, Amazon ECS, and a few other AWS services.

For more information about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.

**Note**  
To save time, you can create a single role, called the `CodeCatalystWorkflowDevelopmentRole-spaceName` role, instead of the two roles listed previously. For more information, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has very broad permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. This tutorial assumes you are creating the two roles listed previously.

To create the build and deploy roles, you can use either the AWS Management Console or the AWS CLI.

------
#### [ AWS Management Console ]

To create the build and deploy roles, complete the following series of procedures.

**To create a build role**

1. Create a policy for the role, as follows:

   1. Sign in to AWS.

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. In the navigation pane, choose **Policies**.

   1. Choose **Create policy**.

   1. Choose the **JSON** tab.

   1. Delete the existing code.

   1. Paste the following code:

------
#### [ JSON ]

****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ecr:*",
                      "ec2:*"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Choose **Next: Tags**.

   1. Choose **Next: Review**.

   1. In **Name**, enter:

      ```
      codecatalyst-ecs-build-policy
      ```

   1. Choose **Create policy**.

      You have now created a permissions policy.

1. Create the build role, as follows:

   1. In the navigation pane, choose **Roles**, and then choose **Create role**.

   1. Choose **Custom trust policy**.

   1. Delete the existing custom trust policy.

   1. Add the following custom trust policy:

   1. Choose **Next**.

   1. In **Permissions policies**, search for `codecatalyst-ecs-build-policy`, select its check box.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-ecs-build-role
      ```

   1. For **Role description**, enter:

      ```
      CodeCatalyst ECS build role
      ```

   1. Choose **Create role**.

   You have now created a build role with a permissions policy and a trust policy.

1. Obtain the build role ARN, as follows:

   1. In the navigation pane, choose **Roles**.

   1. In the search box, enter the name of the role you just created (`codecatalyst-ecs-build-role`).

   1. Choose the role from the list.

      The role's **Summary** page appears.

   1. At the top, copy the **ARN** value. You need it later.

**To create a deploy role**

1. Create a policy for the role, as follows:

   1. Sign in to AWS.

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. In the navigation pane, choose **Policies**.

   1. Choose **Create Policy**.

   1. Choose the **JSON** tab.

   1. Delete the existing code.

   1. Paste the following code:

------
#### [ JSON ]

****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [{
          "Action":[
            "ecs:DescribeServices",
            "ecs:CreateTaskSet",
            "ecs:DeleteTaskSet",
            "ecs:ListClusters",
            "ecs:RegisterTaskDefinition",
            "ecs:UpdateServicePrimaryTaskSet",
            "ecs:UpdateService",
            "elasticloadbalancing:DescribeTargetGroups",
            "elasticloadbalancing:DescribeListeners",
            "elasticloadbalancing:ModifyListener",
            "elasticloadbalancing:DescribeRules",
            "elasticloadbalancing:ModifyRule",
            "lambda:InvokeFunction",
            "lambda:ListFunctions",
            "cloudwatch:DescribeAlarms",
            "sns:Publish",
            "sns:ListTopics", 
            "s3:GetObject",
            "s3:GetObjectVersion",
            "codedeploy:CreateApplication", 
            "codedeploy:CreateDeployment", 
            "codedeploy:CreateDeploymentGroup", 
            "codedeploy:GetApplication", 
            "codedeploy:GetDeployment", 
            "codedeploy:GetDeploymentGroup", 
            "codedeploy:ListApplications", 
            "codedeploy:ListDeploymentGroups", 
            "codedeploy:ListDeployments", 
            "codedeploy:StopDeployment", 
            "codedeploy:GetDeploymentTarget", 
            "codedeploy:ListDeploymentTargets", 
            "codedeploy:GetDeploymentConfig", 
            "codedeploy:GetApplicationRevision", 
            "codedeploy:RegisterApplicationRevision", 
            "codedeploy:BatchGetApplicationRevisions", 
            "codedeploy:BatchGetDeploymentGroups", 
            "codedeploy:BatchGetDeployments", 
            "codedeploy:BatchGetApplications", 
            "codedeploy:ListApplicationRevisions", 
            "codedeploy:ListDeploymentConfigs", 
            "codedeploy:ContinueDeployment"           
         ],
         "Resource":"*",
         "Effect":"Allow"
      },{"Action":[
            "iam:PassRole"
         ],
         "Effect":"Allow",
         "Resource":"*",
         "Condition":{"StringLike":{"iam:PassedToService":[
                  "ecs-tasks.amazonaws.com",
                  "codedeploy.amazonaws.com"
               ]
            }
         }
      }]
      }
      ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement. You can then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Choose **Next: Tags**.

   1. Choose **Next: Review**.

   1. In **Name**, enter:

      ```
      codecatalyst-ecs-deploy-policy
      ```

   1. Choose **Create policy**.

      You have now created a permissions policy.

1. Create the deploy role, as follows:

   1. In the navigation pane, choose **Roles**, and then choose **Create role**.

   1. Choose **Custom trust policy**.

   1. Delete the existing custom trust policy.

   1. Add the following custom trust policy:

   1. Choose **Next**.

   1. In **Permissions policies**, search for `codecatalyst-ecs-deploy-policy`, select its check box.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-ecs-deploy-role
      ```

   1. For **Role description**, enter:

      ```
      CodeCatalyst ECS deploy role
      ```

   1. Choose **Create role**.

   You have now created a deploy role with a trust policy.

1. Obtain the deploy role ARN, as follows:

   1. In the navigation pane, choose **Roles**.

   1. In the search box, enter the name of the role you just created (`codecatalyst-ecs-deploy-role`).

   1. Choose the role from the list.

      The role's **Summary** page appears.

   1. At the top, copy the **ARN** value. You need it later.

------
#### [ AWS CLI ]

To create the build and deploy roles, complete the following series of procedures.

**To create a trust policy for both roles**

As `CodeCatalystECSUser`, in AWS CloudShell, create a trust policy file:

1. Create the file:

   ```
   cat > codecatalyst-ecs-trust-policy.json
   ```

1. At the terminal prompt, paste the following code:

1. Place your cursor after the last curly bracket (`}`).

1. Press **Enter** and then **Ctrl\$1d** to save the file and exit cat.

**To create the build policy and build role**

1. Create the build policy:

   1. As `CodeCatalystECSUser`, in AWS CloudShell, create a build policy file:

      ```
      cat > codecatalyst-ecs-build-policy.json
      ```

   1. At the prompt, enter the following code:

------
#### [ JSON ]

****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ecr:*",
                      "ec2:*"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

------

   1. Place your cursor after the last curly bracket (`}`).

   1. Press **Enter** and then **Ctrl\$1d** to save the file and exit cat.

1. Add the build policy to AWS:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-ecs-build-policy \
       --policy-document file://codecatalyst-ecs-build-policy.json
   ```

1. In the command output, note the `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-ecs-build-policy`. You need this ARN later.

1. Create the build role and attach the trust policy to it:

   ```
   aws iam create-role \
         --role-name codecatalyst-ecs-build-role \
         --assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
   ```

1. Attach the build policy to the build role:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-ecs-build-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-ecs-build-policy
   ```

   Where *arn:aws:iam::111122223333:policy/codecatalyst-ecs-build-policy* is replaced with the ARN of the build policy you noted earlier.

1. Display the build role’s details:

   ```
   aws iam get-role \
         --role-name codecatalyst-ecs-build-role
   ```

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-ecs-build-role`. You need this ARN later.

**To create the deploy policy and deploy role**

1. Create a deploy policy:

   1. In AWS CloudShell, create a deploy policy file:

      ```
      cat > codecatalyst-ecs-deploy-policy.json
      ```

   1. At the prompt, enter the following code:

------
#### [ JSON ]

****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [{
          "Action":[
            "ecs:DescribeServices",
            "ecs:CreateTaskSet",
            "ecs:DeleteTaskSet",
            "ecs:ListClusters",
            "ecs:RegisterTaskDefinition",
            "ecs:UpdateServicePrimaryTaskSet",
            "ecs:UpdateService",
            "elasticloadbalancing:DescribeTargetGroups",
            "elasticloadbalancing:DescribeListeners",
            "elasticloadbalancing:ModifyListener",
            "elasticloadbalancing:DescribeRules",
            "elasticloadbalancing:ModifyRule",
            "lambda:InvokeFunction",
            "lambda:ListFunctions",
            "cloudwatch:DescribeAlarms",
            "sns:Publish",
            "sns:ListTopics", 
            "s3:GetObject",
            "s3:GetObjectVersion",
            "codedeploy:CreateApplication", 
            "codedeploy:CreateDeployment", 
            "codedeploy:CreateDeploymentGroup", 
            "codedeploy:GetApplication", 
            "codedeploy:GetDeployment", 
            "codedeploy:GetDeploymentGroup", 
            "codedeploy:ListApplications", 
            "codedeploy:ListDeploymentGroups", 
            "codedeploy:ListDeployments", 
            "codedeploy:StopDeployment", 
            "codedeploy:GetDeploymentTarget", 
            "codedeploy:ListDeploymentTargets", 
            "codedeploy:GetDeploymentConfig", 
            "codedeploy:GetApplicationRevision", 
            "codedeploy:RegisterApplicationRevision", 
            "codedeploy:BatchGetApplicationRevisions", 
            "codedeploy:BatchGetDeploymentGroups", 
            "codedeploy:BatchGetDeployments", 
            "codedeploy:BatchGetApplications", 
            "codedeploy:ListApplicationRevisions", 
            "codedeploy:ListDeploymentConfigs", 
            "codedeploy:ContinueDeployment"           
         ],
         "Resource":"*",
         "Effect":"Allow"
      },{"Action":[
            "iam:PassRole"
         ],
         "Effect":"Allow",
         "Resource":"*",
         "Condition":{"StringLike":{"iam:PassedToService":[
                  "ecs-tasks.amazonaws.com",
                  "codedeploy.amazonaws.com"
               ]
            }
         }
      }]
      }
      ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Place your cursor after the last curly bracket (`}`).

   1. Press **Enter** and then **Ctrl\$1d** to save the file and exit cat.

1. Add the deploy policy to AWS:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-ecs-deploy-policy \
       --policy-document file://codecatalyst-ecs-deploy-policy.json
   ```

1. In the command output, note the deploy policy's `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-ecs-deploy-policy`. You need this ARN later.

1. Create the deploy role and attach the trust policy to it:

   ```
   aws iam create-role \
         --role-name codecatalyst-ecs-deploy-role \
         --assume-role-policy-document file://codecatalyst-ecs-trust-policy.json
   ```

1. Attach the deploy policy to the deploy role, where *arn:aws:iam::111122223333:policy/codecatalyst-ecs-deploy-policy* is replaced with the ARN of the deploy policy you noted earlier.

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-ecs-deploy-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-ecs-deploy-policy
   ```

1. Display the deploy role’s details:

   ```
   aws iam get-role \
         --role-name codecatalyst-ecs-deploy-role
   ```

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-ecs-deploy-role`. You need this ARN later.

------

## Step 5: Add AWS roles to CodeCatalyst
<a name="deploy-tut-ecs-import-roles"></a>

In this step, you add the build role (`codecatalyst-ecs-build-role`) and deploy role (`codecatalyst-ecs-deploy-role`) to the CodeCatalyst account connection in your space.

**To add build and deploy roles to your account connection**

1. In CodeCatalyst, navigate to your space.

1. Choose **AWS accounts**. A list of account connections appears.

1. Choose the account connection that represents the AWS account where you created your build and deploy roles.

1. Choose **Manage roles from AWS management console**.

   The **Add IAM role to Amazon CodeCatalyst space** page appears. You might need to sign in to access the page.

1. Select **Add an existing role you have created in IAM**.

   A drop-down list appears. The list displays all IAM roles with a trust policy that includes the `codecatalyst-runner.amazonaws.com` and `codecatalyst.amazonaws.com` service principals.

1. In the drop-down list, choose `codecatalyst-ecs-build-role`, and choose **Add role**.
**Note**  
If you see `The security token included in the request is invalid`, it might be because you do not have the right permissions. To fix this issue, sign out of AWS as sign back in with the AWS account that you used when you created your CodeCatalyst space.

1. Choose **Add IAM role**, choose **Add an existing role you have created in IAM**, and in the drop-down list, choose `codecatalyst-ecs-deploy-role`. Choose **Add role**.

   You have now added the build and deploy roles to your space.

1. Copy the value of the **Amazon CodeCatalyst display name**. You'll need this value later, when creating your workflow.

## Step 6: Create a source repository
<a name="deploy-tut-ecs-source-repo"></a>

In this step, you create a source repository in CodeCatalyst. This repository stores the tutorial's source files, such as the task definition file.

For more information about source repositories, see [Creating a source repository](source-repositories-create.md).

**To create a source repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-ecs-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose **Add repository**, and then choose **Create repository**.

1. In **Repository name**, enter:

   ```
   codecatalyst-ecs-source-repository
   ```

1. Choose **Create**.

## Step 7: Add source files
<a name="deploy-tut-ecs-source-files"></a>

In this section, you add the Hello World source files to your CodeCatalyst repository, `codecatalyst-ecs-source-repository`. They consist of:
+ An `index.html` file – Displays a Hello World message in the browser. 
+ A Dockerfile – Describes the base image to use for your Docker image and the Docker commands to apply to it. 
+ A `taskdef.json` file – Defines the Docker image to use when launching tasks into your cluster.

The folder structure is as follows:

```
.
|— public-html
|  |— index.html
|— Dockerfile
|— taskdef.json
```

**Note**  
The following instructions show you how to add the files using the CodeCatalyst console but you can use Git if you prefer. For details, see [Cloning a source repository](source-repositories-clone.md). 

**Topics**
+ [

### index.html
](#deploy-tut-ecs-source-files-index)
+ [

### Dockerfile
](#deploy-tut-ecs-source-files-dockerfile)
+ [

### taskdef.json
](#deploy-tut-ecs-source-files-taskdef)

### index.html
<a name="deploy-tut-ecs-source-files-index"></a>

The `index.html` file displays a Hello World message in the browser. 

**To add the index.html file**

1. In the CodeCatalyst console, go to your source repository, `codecatalyst-ecs-source-repository`.

1. In **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   public-html/index.html
   ```
**Important**  
Make sure to include the `public-html/` prefix to create a folder of the same name. The `index.html` is expected to be in this folder.

1. In the text box, enter the following code:

   ```
   <html>
     <head>
       <title>Hello World</title>
       <style>
         body {
         background-color: black;
         text-align: center;
         color: white;
         font-family: Arial, Helvetica, sans-serif;
         }  
       </style>
     </head>
     <body>
       <h1>Hello World</h1>
     </body>
   </html>
   ```

1. Choose **Commit**, and then choose **Commit** again.

   The `index.html` is added to your repository in a `public-html` folder. 

### Dockerfile
<a name="deploy-tut-ecs-source-files-dockerfile"></a>

The Dockerfile describes the base Docker image to use and the Docker commands to apply to it. For more information about the Dockerfile, see the [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/).

The Dockerfile specified here indicates to use the Apache 2.4 base image (`httpd`). It also includes instructions for copying a source file called `index.html` to a folder on the Apache server that serves webpages. The `EXPOSE` instruction in the Dockerfile tells Docker that the container is listening on port 80.

**To add the Dockerfile**

1. In your source repository, choose **Create file**.

1. For **File name**, enter:

   ```
   Dockerfile
   ```

   Do not include a file extension.
**Important**  
The Dockerfile must reside in your repository’s root folder. The workflow’s `Docker build` command expects it to be there.

1. In the text box, enter the following code:

   ```
   FROM httpd:2.4
   COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
   EXPOSE 80
   ```

1. Choose **Commit**, and then choose **Commit** again.

   The Dockerfile is added to your repository. 

### taskdef.json
<a name="deploy-tut-ecs-source-files-taskdef"></a>

The `taskdef.json` file that you add in this step is the same as the one you already specified in [Step 2: Deploy a placeholder application into Amazon ECS](#deploy-tut-ecs-placeholder) with the following difference:

Instead of specifying a hardcoded Docker image name in the `image:` field (`httpd:2.4`), the task definition here uses a couple of variables to denote the image: `$REPOSITORY_URI` and `$IMAGE_TAG`. These variables will be replaced with real values generated by the workflow’s build action when you run the workflow in a later step.

For details on the task definition parameters, see [Task definition parameters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) in the *Amazon Elastic Container Service Developer Guide*.

**To add the taskdef.json file**

1. In your source repository, choose **Create file**.

1. For **File name**, enter:

   ```
   taskdef.json
   ```

1. In the text box, enter the following code:

   ```
   {
       "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
       "containerDefinitions": [
           {
               "name": "codecatalyst-ecs-container",
               # The $REPOSITORY_URI and $IMAGE_TAG variables will be replaced 
               # by the workflow at build time (see the build action in the 
               # workflow)
               "image": $REPOSITORY_URI:$IMAGE_TAG,
               "essential": true,
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ]
           }
       ],
       "requiresCompatibilities": [
           "FARGATE"
       ],
       "networkMode": "awsvpc",
       "cpu": "256",
       "memory": "512",
       "family": "codecatalyst-ecs-task-def"
   }
   ```

   In the preceding code, replace

   *arn:aws:iam::account\$1ID:role/codecatalyst-ecs-task-execution-role*

   with the ARN of the task execution role that you noted in [To create the task execution role](#deploy-tut-ecs-create-task-execution-role).

1. Choose **Commit**, and then choose **Commit** again.

   The `taskdef.json` file is added to your repository. 

## Step 8: Create and run a workflow
<a name="deploy-tut-ecs-workflow"></a>

In this step, you create a workflow that takes your source files, builds them into a Docker image, and then deploys the image to your Amazon ECS cluster. This deployment replaces the existing Apache placeholder application.

The workflow consists of the following building blocks that run sequentially:
+ A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A build action (`BuildBackend`) – On trigger, the action builds the Docker image using the Dockerfile and pushes the image to Amazon ECR. The build action also updates the `taskdef.json` with the correct `image` field value, and then creates an output artifact of this file. This artifact is used as the input for the deploy action, which is next.

  For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ A deploy action (`DeployToECS`) – On completion of the build action, the deploy action looks for the output artifact generated by the build action (`TaskDefArtifact`), finds the `taskdef.json` inside of it, and registers it with your Amazon ECS service. The service then follows the instructions in the `taskdef.json` file to run three Amazon ECS tasks—and associated Hello World Docker containers—inside your Amazon ECS cluster. 

**To create a workflow**

1. In the CodeCatalyst console, in the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. For **Source repository**, choose `codecatalyst-ecs-source-repository`.

1. For **Branch**, choose `main`.

1. Choose **Create**.

1. Delete the YAML sample code.

1. Add the following YAML code:
**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies of both roles described in [Step 5: Add AWS roles to CodeCatalyst](#deploy-tut-ecs-import-roles). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md).

   ```
   Name: codecatalyst-ecs-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     BuildBackend:
       Identifier: aws/build@v1
       Environment:
         Name: codecatalyst-ecs-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-ecs-build-role
       Inputs:
         Sources:
           - WorkflowSource
         Variables:
           - Name: REPOSITORY_URI
             Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo
           - Name: IMAGE_TAG
             Value: ${WorkflowSource.CommitId}
       Configuration:
         Steps:
           #pre_build:
           - Run: echo Logging in to Amazon ECR...
           - Run: aws --version
           - Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
           #build:
           - Run: echo Build started on `date`
           - Run: echo Building the Docker image...
           - Run: docker build -t $REPOSITORY_URI:latest .
           - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
           #post_build:
           - Run: echo Build completed on `date`
           - Run: echo Pushing the Docker images...
           - Run: docker push $REPOSITORY_URI:latest
           - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
           # Replace the variables in taskdef.json
           - Run: find taskdef.json -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
           - Run: find taskdef.json -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
           - Run: cat taskdef.json
           # The output artifact will be a zip file that contains a task definition file.
       Outputs:
         Artifacts:
           - Name: TaskDefArtifact
             Files: 
               - taskdef.json
     DeployToECS:
       DependsOn: 
         - BuildBackend
       Identifier: aws/ecs-deploy@v1
       Environment:
         Name: codecatalyst-ecs-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-ecs-deploy-role
       Inputs:
         Sources: []
         Artifacts:
           - TaskDefArtifact
       Configuration:
         region: us-west-2
         cluster: codecatalyst-ecs-cluster
         service: codecatalyst-ecs-service
         task-definition: taskdef.json
   ```

   In the preceding code, replace:
   + Both instances of *codecatalyst-ecs-environment* with the name of the environment you created in [Prerequisites](#deploy-tut-ecs-prereqs).
   + Both instances of *codecatalyst-account-connection* with the display name of your account connection. The display name might be a number. For more information, see [Step 5: Add AWS roles to CodeCatalyst](#deploy-tut-ecs-import-roles).
   + *codecatalyst-ecs-build-role* with the name of the build role you created in [Step 4: Create AWS roles](#deploy-tut-ecs-build-deploy-roles).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo* (in the `Value:` property) with the URI of the Amazon ECR repository you created in [Step 3: Create an Amazon ECR image repository](#deploy-tut-ecs-ecr).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com* (in the `Run: aws ecr` command) with the URI of the Amazon ECR repository without the image suffix (`/codecatalyst-ecs-image-repo`).
   + *codecatalyst-ecs-deploy-role* with the name of the deploy role you created in [Step 4: Create AWS roles](#deploy-tut-ecs-build-deploy-roles).
   + Both instances of *us-west-2* with your AWS Region code. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the *AWS General Reference*.
**Note**  
If you decided not to create build and deploy roles, replace *codecatalyst-ecs-build-role* and *codecatalyst-ecs-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 4: Create AWS roles](#deploy-tut-ecs-build-deploy-roles).
**Tip**  
Instead of using the `find` and `sed` commands shown in the previous workflow code to update the repository and image name, you can use the **Render Amazon ECS task definition** action for this purpose. For more information, see [Modifying an Amazon ECS task definition](render-ecs-action.md).

1. (Optional) Choose **Validate** to make sure that the YAML code is valid before committing.

1. Choose **Commit**.

1. In the **Commit workflow** dialog box, enter the following:

   1. For **Commit message**, remove the text and enter:

      ```
      Add first workflow
      ```

   1. For **Repository**, choose `codecatalyst-ecs-source-repository`.

   1. For **Branch name**, choose main.

   1. Choose **Commit**.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `workflow.yaml` file to your source repository, the trigger started the workflow run.

**To view the workflow run progress**

1. In the navigation pane of the CodeCatalyst console, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created, `codecatalyst-ecs-workflow`.

1. Choose **BuildBackend** to see the build progress.

1. Choose **DeployToECS** to see the deployment progress.

   For more information about viewing run details, see [Viewing workflow run status and details](workflows-view-run.md).

**To verify the deployment**

1. Open the Amazon ECS classic console at [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/).

1. Choose your cluster, `codecatalyst-ecs-cluster`.

1. Choose the **Tasks** tab. 

1. Choose any one of the three tasks.

1. In the **Public IP** field, choose **open address**.

   A "Hello World" page appears in the browser, indicating that the Amazon ECS service successfully deployed your application.

## Step 9: Make a change to your source files
<a name="deploy-tut-ecs-change"></a>

In this section, you make a change to the `index.html` file in your source repository. This change causes the workflow to build a new Docker image, tag it with a commit ID, push it to Amazon ECR, and deploy it to Amazon ECS. 

**To change the index.html**

1. In the CodeCatalyst console, in the navigation pane, choose **Code**, then choose **Source repositories**, and then choose your repository, `codecatalyst-ecs-source-repository`.

1. Choose `public-html`, and then choose `index.html`.

   The contents of `index.html` appear.

1. Choose **Edit**. 

1. On line 14, change the `Hello World` text to `Tutorial complete!`.

1. Choose **Commit**, and then choose **Commit** again.

   The commit causes a new workflow run to start. 

1. (Optional) Go to your source repository's main page, choose **View commits**, and then note the commit ID for the `index.html` change.

1. Watch the deployment progress:

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose `codecatalyst-ecs-workflow` to view the latest run.

   1. Choose **BuildBackend**, and **DeployToECS** to see the workflow run progress.

1. Verify that your application was updated, as follows:

   1. Open the Amazon ECS classic console at [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/).

   1. Choose your cluster, `codecatalyst-ecs-cluster`.

   1. Choose the **Tasks** tab. 

   1. Choose any one of the three tasks.

   1. In the **Public IP** field, choose **open address**.

      A `Tutorial complete!` page appears.

1. (Optional) In AWS, switch to the Amazon ECR console and verify that the new Docker image was tagged with the commit ID from step 6.

## Clean up
<a name="deploy-tut-ecs-cleanup"></a>

Clean up the files and services used in this tutorial to avoid being charged for them.

In the AWS Management Console, clean up in this order:

1. In Amazon ECS, do the following:

   1. Delete `codecatalyst-ecs-service`.

   1. Delete `codecatalyst-ecs-cluster`.

   1. Deregister `codecatalyst-ecs-task-definition`.

1. In Amazon ECR, delete `codecatalyst-ecs-image-repo`.

1. In Amazon EC2, delete `codecatalyst-ecs-security-group`.

1. In IAM Identity Center, delete:

   1. `CodeCatalystECSUser`

   1. `CodeCatalystECSPermissionSet`

In the CodeCatalyst console, clean up as follows:

1. Delete `codecatalyst-ecs-workflow`.

1. Delete `codecatalyst-ecs-environment`.

1. Delete `codecatalyst-ecs-source-repository`.

1. Delete `codecatalyst-ecs-project`.

In this tutorial, you learned how to deploy an application to an Amazon ECS service using a CodeCatalyst workflow and a **Deploy to Amazon ECS** action.

# Adding the 'Deploy to Amazon ECS' action
<a name="deploy-action-ecs-adding"></a>

Use the following instructions to add the **Deploy to Amazon ECS** action to your workflow. 

------
#### [ Visual ]

**To add the 'Deploy to Amazon ECS' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Amazon ECS** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Amazon ECS**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Deploy to Amazon ECS' action YAML](deploy-action-ref-ecs.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'Deploy to Amazon ECS' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Amazon ECS** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Amazon ECS**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Deploy to Amazon ECS' action YAML](deploy-action-ref-ecs.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# 'Deploy to Amazon ECS' variables
<a name="deploy-action-ecs-variables"></a>

The **Deploy to Amazon ECS** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  cluster  |  The name of the Amazon ECS cluster that was deployed to during the workflow run. Example: `codecatalyst-ecs-cluster`  | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:ECS`.  | 
|  service  |  The name of the Amazon ECS service that was deployed to during the workflow run. Example: `codecatalyst-ecs-service`  | 
|  task-definition-arn  |  The Amazon Resource Name (ARN) of the task definition that was registered during the workflow run. Example: `arn:aws:ecs:us-west-2:111122223333:task-definition/codecatalyst-task-def:8`The `:8` in the preceding example indicates the revision that was registered.  | 
|  deployment-url  |  A link to the Amazon ECS console's **Events** tab, where you can view details of the Amazon ECS deployment associated with the workflow run. Example: `https://console.aws.amazon.com/ecs/home?region=us-west-2#/clusters/codecatalyst-ecs-cluster/services/codecatalyst-ecs-service/events`  | 
|  region  |  The region code of the AWS Region that was deployed to during the workflow run. Example: `us-west-2`  | 

# 'Deploy to Amazon ECS' action YAML
<a name="deploy-action-ref-ecs"></a>

The following is the YAML definition of the **Deploy to Amazon ECS** action. To learn how to use this action, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  ECSDeployAction\$1nn: 
    Identifier: aws/ecs-deploy@v1
    DependsOn:
      - build-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - task-definition-artifact
    Configuration: 
      region: us-east-1 
      cluster: ecs-cluster
      service: ecs-service
      task-definition: task-definition-path
      force-new-deployment: false|true
      codedeploy-appspec: app-spec-file-path
      codedeploy-application: application-name
      codedeploy-deployment-group: deployment-group-name
      codedeploy-deployment-description: deployment-description
```

## ECSDeployAction
<a name="deploy.action.ecs.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `ECSDeployAction_nn`.

Corresponding UI: Configuration tab/**Action display name**

## Identifier
<a name="deploy.action.ecs.identifier"></a>

(*ECSDeployAction*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/ecs-deploy@v1`.

Corresponding UI: Workflow diagram/ECSDeployAction\$1nn/**aws/ecs-deploy@v1** label

## DependsOn
<a name="deploy.action.ecs.dependson"></a>

(*ECSDeployAction*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="deploy.action.ecs.computename"></a>

(*ECSDeployAction*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="deploy.action.ecs.computetype"></a>

(*ECSDeployAction*/Compute/**Type**)

(Required if [Compute](#deploy.action.ecs.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="deploy.action.ecs.computefleet"></a>

(*ECSDeployAction*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="deploy.action.ecs.timeout"></a>

(*ECSDeployAction*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Environment
<a name="deploy.action.ecs.environment"></a>

(*ECSDeployAction*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="deploy.action.ecs.environment.name"></a>

(*ECSDeployAction*/Environment/**Name**)

(Required if [Environment](#deploy.action.ecs.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="deploy.action.ecs.environment.connections"></a>

(*ECSDeployAction*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="deploy.action.ecs.environment.connections.name"></a>

(*ECSDeployAction*/Environment/Connections/**Name**)

(Required if [Connections](#deploy.action.ecs.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="deploy.action.ecs.environment.connections.role"></a>

(*ECSDeployAction*/Environment/Connections/**Role**)

(Required if [Connections](#deploy.action.ecs.environment.connections) is included)

Specify the name of the IAM role that the **Deploy to Amazon ECS** action uses to access AWS. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [{
      "Action":[
        "ecs:DescribeServices",
        "ecs:CreateTaskSet",
        "ecs:DeleteTaskSet",
        "ecs:ListClusters",
        "ecs:RegisterTaskDefinition",
        "ecs:UpdateServicePrimaryTaskSet",
        "ecs:UpdateService",
        "elasticloadbalancing:DescribeTargetGroups",
        "elasticloadbalancing:DescribeListeners",
        "elasticloadbalancing:ModifyListener",
        "elasticloadbalancing:DescribeRules",
        "elasticloadbalancing:ModifyRule",
        "lambda:InvokeFunction",
        "lambda:ListFunctions",
        "cloudwatch:DescribeAlarms",
        "sns:Publish",
        "sns:ListTopics", 
        "s3:GetObject",
        "s3:GetObjectVersion",
        "codedeploy:CreateApplication", 
        "codedeploy:CreateDeployment", 
        "codedeploy:CreateDeploymentGroup", 
        "codedeploy:GetApplication", 
        "codedeploy:GetDeployment", 
        "codedeploy:GetDeploymentGroup", 
        "codedeploy:ListApplications", 
        "codedeploy:ListDeploymentGroups", 
        "codedeploy:ListDeployments", 
        "codedeploy:StopDeployment", 
        "codedeploy:GetDeploymentTarget", 
        "codedeploy:ListDeploymentTargets", 
        "codedeploy:GetDeploymentConfig", 
        "codedeploy:GetApplicationRevision", 
        "codedeploy:RegisterApplicationRevision", 
        "codedeploy:BatchGetApplicationRevisions", 
        "codedeploy:BatchGetDeploymentGroups", 
        "codedeploy:BatchGetDeployments", 
        "codedeploy:BatchGetApplications", 
        "codedeploy:ListApplicationRevisions", 
        "codedeploy:ListDeploymentConfigs", 
        "codedeploy:ContinueDeployment"           
     ],
     "Resource":"*",
     "Effect":"Allow"
  },{"Action":[
        "iam:PassRole"
     ],
     "Effect":"Allow",
     "Resource":"*",
     "Condition":{"StringLike":{"iam:PassedToService":[
              "ecs-tasks.amazonaws.com",
              "codedeploy.amazonaws.com"
           ]
        }
     }
  }]
  }
  ```

------
**Note**  
The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```
+ The following custom trust policy:

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Inputs
<a name="deploy.action.ecs.inputs"></a>

(*ECSDeployAction*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the `ECSDeployAction` needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed per **Deploy to Amazon ECS** action.

Corresponding UI: **Inputs** tab

## Sources
<a name="deploy.action.ecs.inputs.sources"></a>

(*ECSDeployAction*/Inputs/**Sources**)

(Required if your task definition file is stored in a source repository)

If your task definition file is stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your task definition file is not contained within a source repository, it must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="deploy.action.ecs.inputs.artifacts"></a>

(*ECSDeployAction*/Inputs/**Artifacts**)

(Required if your task definition file is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the task definition file that you want to deploy is contained in an artifact generated by a previous action, specify that artifact here. If your task definition file is not contained within an artifact, it must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Configuration
<a name="deploy.action.ecs.configuration"></a>

(*ECSDeployAction*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## region
<a name="deploy.action.ecs.region"></a>

(Configuration/**region**)

(Required)

Specify the AWS Region where your Amazon ECS cluster and service reside. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the *AWS General Reference*.

Corresponding UI: Configuration tab/**Region**

## cluster
<a name="deploy.action.ecs.cluster"></a>

(*ECSDeployAction*/Configuration/**cluster**)

(Required)

Specify the name of an existing Amazon ECS cluster. The **Deploy to Amazon ECS** action will deploy your containerized application as a task into this cluster. For more information about Amazon ECS clusters, see [Clusters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-clusters) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Cluster**

## service
<a name="deploy.action.ecs.service"></a>

(*ECSDeployAction*/Configuration/**service**)

(Required)

Specify the name of an existing Amazon ECS service that will instantiate the task definition file. This service must reside under the cluster specified in the `cluster` field. For more information about Amazon ECS services, see [Amazon ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Service**

## task-definition
<a name="deploy.action.ecs.task.definition"></a>

(*ECSDeployAction*/Configuration/**task-definition**)

(Required)

Specify the path to an existing task definition file. If the file resides in your source repository, the path is relative to the source repository root folder. If your file resides in an artifact from a previous workflow action, the path is relative to the artifact root folder. For more information about task definition files, see [Task definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Task definition**

## force-new-deployment
<a name="deploy.action.ecs.forcenewdeployment"></a>

(*ECSDeployAction*/Configuration/**force-new-deployment**)

(Required)

If enabled, the Amazon ECS service is able to start new deployments without service definition changes. Forcing a deployment causes the service to stop all currently running tasks and launch new tasks. For more information about forcing new deployments, see [Updating a service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service.html) in the *Amazon Elastic Container Service Developer Guide*.

Default: `false`

Corresponding UI: Configuration tab/**Force a new deployment of the service**

## codedeploy-appspec
<a name="deploy.action.ecs.codedeploy.appspec"></a>

(*ECSDeployAction*/Configuration/**codedeploy-appspec**)

(Required if you have configured your Amazon ECS service to use blue/green deployments, otherwise, omit)

Specify the name and path to an existing CodeDeploy application specification (AppSpec) file. This file must reside in the root of your CodeCatalyst source repository. For more information about AppSpec files, see [CodeDeploy application specification (AppSpec) files](https://docs.aws.amazon.com/codedeploy/latest/userguide/application-specification-files.html) in the *AWS CodeDeploy User Guide*.

**Note**  
Only supply CodeDeploy information if you have configured your Amazon ECS service to perform blue/green deployments. For rolling update deployments (the default), omit CodeDeploy information. For more information about Amazon ECS deployments, see [Amazon ECS deployment types](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-types.html) in the *Amazon Elastic Container Service Developer Guide*.

**Note**  
The **CodeDeploy** fields may be hidden in the visual editor. To get them to appear, see [Why are CodeDeploy fields missing from the visual editor?](troubleshooting-workflows.md#troubleshooting-workflows-codedeploy).

Corresponding UI: Configuration tab/**CodeDeploy AppSpec**

## codedeploy-application
<a name="deploy.action.ecs.codedeploy.application"></a>

(*ECSDeployAction*/Configuration/**codedeploy-application**)

(Required if `codedeploy-appspec` is included)

Specify the name of an existing CodeDeploy application. For more information about CodeDeploy applications, see [Working with applications in CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/applications.html) in the *AWS CodeDeploy User Guide*.

Corresponding UI: Configuration tab/**CodeDeploy application**

## codedeploy-deployment-group
<a name="deploy.action.ecs.codedeploy.deploymentgroup"></a>

(*ECSDeployAction*/Configuration/**codedeploy-deployment-group**)

(Required if `codedeploy-appspec` is included)

Specify the name of an existing CodeDeploy deployment group. For more information about CodeDeploy deployment groups, see [Working with deployment groups in CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-groups.html) in the *AWS CodeDeploy User Guide*.

Corresponding UI: Configuration tab/**CodeDeploy deployment group**

## codedeploy-deployment-description
<a name="deploy.action.ecs.codedeploy.deploymentdescription"></a>

(*ECSDeployAction*/Configuration/**codedeploy-deployment-description**)

(Optional)

Specify a description of the deployment that this action will create. For more information, see [Working with deployments in CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployments.html) in the *AWS CodeDeploy User Guide*.

Corresponding UI: Configuration tab/**CodeDeploy deployment description**

# Deploying to Amazon EKS with a workflow
<a name="deploy-action-eks"></a>

**Tip**  
For a tutorial that shows you how to use the **Deploy to Kubernetes cluster ** action, see [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).

This section describes how to deploy a containerized application into a Kubernetes cluster using a CodeCatalyst workflow. To accomplish this, you must add the **Deploy to Kubernetes cluster** action to your workflow. This action deploys your application to a Kubernetes cluster that you have set up in Amazon Elastic Kubernetes Service (EKS) using one or more Kubernetes manifest files. For a sample manifest, see [deployment.yaml](deploy-tut-eks.md#deploy-tut-eks-source-files-deployment-yml) in [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).

For more information about Kubernetes, see the [Kubernetes Documentation](https://kubernetes.io/docs/home/).

For more information about Amazon EKS, see [What is Amazon EKS?](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) in the *Amazon EKS User Guide*.

**Topics**
+ [

## How the 'Deploy to Kubernetes cluster' action works
](#deploy-action-eks-howitworks)
+ [

## Runtime image used by the 'Deploy to Amazon EKS' action
](#deploy-action-eks-runtime)
+ [

# Tutorial: Deploy an application to Amazon EKS
](deploy-tut-eks.md)
+ [

# Adding the 'Deploy to Kubernetes cluster' action
](deploy-action-eks-adding.md)
+ [

# 'Deploy to Kubernetes cluster' variables
](deploy-action-eks-variables.md)
+ [

# 'Deploy to Kubernetes cluster' action YAML
](deploy-action-ref-eks.md)

## How the 'Deploy to Kubernetes cluster' action works
<a name="deploy-action-eks-howitworks"></a>

The **Deploy to Kubernetes cluster** works as follows:

1. At runtime, the action installs the Kubernetes `kubectl` utility to the CodeCatalyst compute machine where the action is running. The action configures `kubectl` to point to the Amazon EKS cluster you provided when you configured the action. The `kubectl` utility is necessary to run the `kubectl apply` command, next.

1. The action runs the `kubectl apply -f my-manifest.yaml` command, which carries out the instructions in *my-manifest.yaml* to deploy your application as a set of containers and pods into the configured cluster. For more information on this command, see the [kubectl apply](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply) topic in the *Kubernetes Reference Documentation*.

## Runtime image used by the 'Deploy to Amazon EKS' action
<a name="deploy-action-eks-runtime"></a>

The **Deploy to Amazon EKS** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Tutorial: Deploy an application to Amazon EKS
<a name="deploy-tut-eks"></a>

In this tutorial, you learn how to deploy a containerized application into Amazon Elastic Kubernetes Service using an Amazon CodeCatalyst workflow, Amazon EKS, and a few other AWS services. The deployed application is a simple 'Hello, World\$1' website built on an Apache web server Docker image. The tutorial walks you through the required preparation work such as setting up a development machine and an Amazon EKS cluster, and then describes how to create a workflow to build the application and deploy it into the cluster.

After the initial deployment is complete, the tutorial instructs you to make a change to your application source. This change causes a new Docker image to be built and pushed to your Docker image repository with new revision information. The new revision of the Docker image is then deployed into Amazon EKS.

**Tip**  
Instead of working your way through this tutorial, you can use a blueprint that does a complete Amazon EKS setup for you. You'll need to use the **EKS App Deployment** blueprint. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).

**Topics**
+ [

## Prerequisites
](#deploy-tut-eks-prereqs)
+ [

## Step 1: Set up your development machine
](#deploy-tut-eks-dev-env-create)
+ [

## Step 2: Create an Amazon EKS cluster
](#deploy-tut-eks-cluster)
+ [

## Step 3: Create an Amazon ECR image repository
](#deploy-tut-eks-ecr)
+ [

## Step 4: Add source files
](#deploy-tut-eks-source-files)
+ [

## Step 5: Create AWS roles
](#deploy-tut-eks-roles)
+ [

## Step 6: Add AWS roles to CodeCatalyst
](#deploy-tut-eks-import-roles)
+ [

## Step 7: Update the ConfigMap
](#deploy-tut-eks-configmap)
+ [

## Step 8: Create and run a workflow
](#deploy-tut-eks-workflow)
+ [

## Step 9: Make a change to your source files
](#deploy-tut-eks-change)
+ [

## Clean up
](#deploy-tut-eks-cleanup)

## Prerequisites
<a name="deploy-tut-eks-prereqs"></a>

Before you begin this tutorial:
+ You need an Amazon CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ In your space, you need an empty project called:

  ```
  codecatalyst-eks-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need an empty CodeCatalyst **source repository** called:

  ```
  codecatalyst-eks-source-repository
  ```

  For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).
+ In your project, you need a CodeCatalyst CI/CD **environment** (not a Dev Environment) called:

  ```
  codecatalyst-eks-environment
  ```

  Configure this environment as follows:
  + Choose any type, such as **Non-production**.
  + Connect your AWS account to it. 
  + For the **Default IAM role**, choose any role. You'll specify a different role later.

  For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Step 1: Set up your development machine
<a name="deploy-tut-eks-dev-env-create"></a>

The first step in this tutorial is to configure a development machine with a few tools that you'll use throughout this tutorial. These tools are:
+ the `eksctl` utility – for cluster creation
+ the `kubectl` utility – a prerequisite for `eksctl`
+ the AWS CLI – also a prerequisite for `eksctl`

You can install these tools on your existing development machine if you have one, or you can use a CodeCatalyst Dev Environment, which is Cloud-based. The benefit of a CodeCatalyst Dev Environment is that it's easy to spin up and take down, and is integrated with other CodeCatalyst services, allowing you to work through this tutorial in fewer steps.

This tutorial assumes you'll be using a CodeCatalyst Dev Environment.

The following instructions describe a quick way to launch a CodeCatalyst Dev Environment and configure it with the required tools, but if you want detailed instructions, see:
+ [Creating a Dev Environment](devenvironment-create.md) in this guide.
+ [Installing kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) in the **Amazon EKS User Guide**.
+ [Installing or upgrading eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) in the **Amazon EKS User Guide**.
+ [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the *AWS Command Line Interface User Guide*.

**To launch a Dev Environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-eks-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose the name of your source repository, `codecatalyst-eks-source-repository`.

1. Near the top choose **Create Dev Environment**, and then choose **AWS Cloud9 (in browser)**.

1. Make sure that **Work in existing branch** and **main** are selected, and then choose **Create**.

   Your Dev Environment launches in a new browser tab, and your repository (`codecatalyst-eks-source-repository`) is cloned into it.

**To install and configure kubectl**

1. In the Dev Environment terminal, enter:

   ```
   curl -o kubectl https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.9/2020-11-02/bin/linux/amd64/kubectl
   ```

1. Enter:

   ```
   chmod +x ./kubectl
   ```

1. Enter:

   ```
   mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$PATH:$HOME/bin
   ```

1. Enter:

   ```
   echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
   ```

1. Enter:

   ```
   kubectl version --short --client
   ```

1. Check that a version appears.

   You have now installed `kubectl`.

**To install and configure eksctl**
**Note**  
`eksctl` is not strictly required because you can use `kubectl` instead. However, `eksctl` has the benefit of automating much of the cluster configuration, and is therefore the tool recommended for this tutorial.

1. In the Dev Environment terminal, enter:

   ```
   curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
   ```

1. Enter:

   ```
   sudo cp /tmp/eksctl /usr/bin
   ```

1. Enter:

   ```
   eksctl version
   ```

1. Check that a version appears.

   You have now installed `eksctl`.

**To verify that the AWS CLI is installed**

1. In the Dev Environment terminal, enter:

   ```
   aws --version
   ```

1. Check that a version appears to verify that the AWS CLI is installed.

   Complete the remaining procedures to configure the AWS CLI with the necessary permissions to access AWS.

**To configure the AWS CLI**

You must configure the AWS CLI with access keys and a session token to give it access to AWS services. The following instructions provide a quick way to configure the keys and token, but if you want detailed instructions, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.

1. Create an IAM Identity Center user, as follows:

   1. Sign in to the AWS Management Console and open the AWS IAM Identity Center console at [https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/).

      (You might need to choose **Enable** if you've never signed in to IAM Identity Center before.)
**Note**  
Make sure you sign in using the AWS account that is connected to your CodeCatalyst space. You can verify which account is connected by navigating to your space and choosing the **AWS accounts** tab. For more information, see [Creating a space](spaces-create.md).

   1. In the navigation pane, choose **Users**, and then choose **Add user**.

   1. In **Username**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. Under **Password**, choose **Generate a one-time password that you can share with this user**.

   1. In **Email address** and **Confirm email address**, enter an email address that doesn't already exist in IAM Identity Center.

   1. In **First name**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. In **Last name**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. In **Display name**, keep:

      ```
      codecatalyst-eks-user codecatalyst-eks-user
      ```

   1. Choose **Next**.

   1. On the **Add user to groups** page, choose **Next**.

   1. On the **Review and add user** page, review the information and choose **Add user**.

      A **One-time password** dialog box appears.

   1. Choose **Copy** and then paste the sign-in information to a text file. The sign-in information consists of the AWS access portal URL, a user name, and a one-time password.

   1. Choose **Close**.

1. Create a permission set, as follows:

   1. In the navigation pane, choose **Permission sets**, and then choose **Create permission set**.

   1. Choose **Predefined permission set** and then select **AdministratorAccess**. This policy provides full permissions to all AWS services. 

   1. Choose **Next**.

   1. In **Permission set name**, remove `AdministratorAccess` and enter:

      ```
      codecatalyst-eks-permission-set
      ```

   1. Choose **Next**.

   1. On the **Review and create** page, review the information and choose **Create**.

1. Assign the permission set to `codecatalyst-eks-user`, as follows:

   1. In the navigation pane, choose **AWS accounts**, and then select the check box next to the AWS account that you're currently signed in to.

   1. Choose **Assign users or groups**.

   1. Choose the **Users** tab.

   1. Select the check box next to `codecatalyst-eks-user`.

   1. Choose **Next**.

   1. Select the check box next to `codecatalyst-eks-permission-set`.

   1. Choose **Next**.

   1. Review the information and choose **Submit**.

      You have now assigned `codecatalyst-eks-user` and `codecatalyst-eks-permission-set` to your AWS account, binding them together.

1. Obtain `codecatalyst-eks-user`'s access keys and session token, as follows:

   1. Make sure you have the AWS access portal URL and the username and one-time password for `codecatalyst-eks-user`. You should have copied this information to a text editor earlier.
**Note**  
If you do not have this information, go to the `codecatalyst-eks-user` details page in IAM Identity Center, choose **Reset password**, **Generate a one-time password [...]**, and **Reset password** again to display the information on the screen.

   1. Sign out of AWS.

   1. Paste the AWS access portal URL into your browser's address bar.

   1. Sign in with:
      + **Username**:

        ```
        codecatalyst-eks-user
        ```
      + **Password**:

        *one-time-password*

   1. In **Set new password**, enter a new password and choose **Set new password**.

      An **AWS account** box appears on the screen.

   1. Choose **AWS account**, and then choose the name of the AWS account to which you assigned the `codecatalyst-eks-user` user and permission set.

   1. Next to `codecatalyst-eks-permission-set`, choose **Command line or programmatic access**.

   1. Copy the commands in the middle of the page. They look similar to the following:

      ```
      export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" 
      export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" 
      export AWS_SESSION_TOKEN="session-token"
      ```

      ...where *session-token* is a long random string.

1. Add the access keys and session token to the AWS CLI, as follows:

   1. Return to your CodeCatalyst Dev Environment.

   1. At the terminal prompt, paste the commands you copied. Press Enter.

      You have now configured the AWS CLI with access keys and a session token. You can now use AWS CLI to complete the tasks required by this tutorial.
**Important**  
If at any time during this tutorial you see messages similar to:  
`Unable to locate credentials. You can configure credentials by running "aws configure".`  
Or:  
`ExpiredToken: The security token included in the request is expired`  
...it's because your AWS CLI session has expired. In this case, do *not* run the `aws configure` command. Instead, use the instructions in step 4 of this procedure that starts with `Obtain codecatalyst-eks-user's access key and session token` to refresh your session.

## Step 2: Create an Amazon EKS cluster
<a name="deploy-tut-eks-cluster"></a>

In this section, you create a cluster in Amazon EKS. The instructions below describe a quick way to create the cluster using `eksctl`, but if you want detailed instructions, see:
+ [Getting started with eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) in the **Amazon EKS User Guide**

  or
+ [Getting started with the console and AWS CLI](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html) in the **Amazon EKS User Guide** (this topic provides `kubectl` instructions for creating the cluster) 

**Note**  
[Private clusters](https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html) are not supported by the CodeCatalyst integration with Amazon EKS.

**Before you begin**

Make sure you have completed the following tasks on your development machine:
+ Installed the `eksctl` utility.
+ Installed the `kubectl` utility.
+ Installed the AWS CLI and configured it with access keys and a session token.

For information on how to complete these tasks, see [Step 1: Set up your development machine](#deploy-tut-eks-dev-env-create).

**To create a cluster**
**Important**  
Do not use the Amazon EKS service's user interface to create the cluster because the cluster won't be configured correctly. Use the `eksctl` utility, as described in the following steps.

1. Go to your Dev Environment.

1. Create a cluster and nodes:

   ```
   eksctl create cluster --name codecatalyst-eks-cluster --region us-west-2
   ```

   Where:
   + *codecatalyst-eks-cluster* is replaced with the name you want to give your cluster.
   + *us-west-2* is replaced with your Region.

   After 10-20 minutes, a message similar to the following appears: 

   `EKS cluster "codecatalyst-eks-cluster" in "us-west-2" region is ready`
**Note**  
You will see multiple `waiting for CloudFormation stack` messages while AWS creates your cluster. This is expected.

1. Verify that your cluster was created successfully:

   ```
   kubectl cluster-info
   ```

   You will see a message similar to the following, indicating a sucessful cluster creation:

   ```
   Kubernetes master is running at https://long-string.gr7.us-west-2.eks.amazonaws.com
   CoreDNS is running at https://long-string.gr7.us-west-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
   ```

## Step 3: Create an Amazon ECR image repository
<a name="deploy-tut-eks-ecr"></a>

In this section, you create a private image repository in Amazon Elastic Container Registry (Amazon ECR). This repository stores the Docker image for the tutorial.

For more information about Amazon ECR, see the *Amazon Elastic Container Registry User Guide*.

**To create an image repository in Amazon ECR**

1. Go to your Dev Environment.

1. Create an empty repository in Amazon ECR:

   ```
   aws ecr create-repository --repository-name codecatalyst-eks-image-repo
   ```

   Replace *codecatalyst-eks-image-repo* with the name you want to give the Amazon ECR repository.

   This tutorial assumes you named your repository `codecatalyst-eks-image-repo`.

1. Display the Amazon ECR repository’s details:

   ```
   aws ecr describe-repositories \
         --repository-names codecatalyst-eks-image-repo
   ```

1. Note the `“repositoryUri”:` value, for example, `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo`.

   You need it later when adding the repository to your workflow. 

## Step 4: Add source files
<a name="deploy-tut-eks-source-files"></a>

In this section, you add application source files to your source repository (`codecatalyst-eks-source-repository`). They consist of:
+ An `index.html` file – Displays a 'Hello, World\$1' message in the browser.
+ A Dockerfile – Describes the base image to use for your Docker image and the Docker commands to apply to it.
+ A `deployment.yaml` file – The Kubernetes manifest that defines the Kubernetes service and deployment. 

The folder structure is as follows:

```
|— codecatalyst-eks-source-repository
   |— Kubernetes
      |— deployment.yaml
   |— public-html
   |  |— index.html
   |— Dockerfile
```

**Topics**
+ [

### index.html
](#deploy-tut-eks-source-files-index)
+ [

### Dockerfile
](#deploy-tut-eks-source-files-dockerfile)
+ [

### deployment.yaml
](#deploy-tut-eks-source-files-deployment-yml)

### index.html
<a name="deploy-tut-eks-source-files-index"></a>

The `index.html` file displays a 'Hello, World\$1' message in the browser. 

**To add the index.html file**

1. Go to your Dev Environment.

1. In `codecatalyst-eks-source-repository`, create a folder called `public-html`.

1. In `/public-html`, create a file called `index.html` with the following contents:

   ```
   <html>
     <head>
       <title>Hello World</title>
       <style>
         body {
         background-color: black;
         text-align: center;
         color: white;
         font-family: Arial, Helvetica, sans-serif;
         }  
       </style>
     </head>
     <body>
       <h1>Hello, World!</h1>
     </body>
   </html>
   ```

1. At the terminal prompt, enter:

   ```
   cd /projects/codecatalyst-eks-source-repository
   ```

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add public-html/index.html"
   git push
   ```

   The `index.html` is added to your repository in a `public-html` folder. 

### Dockerfile
<a name="deploy-tut-eks-source-files-dockerfile"></a>

The Dockerfile describes the base Docker image to use and the Docker commands to apply to it. For more information about the Dockerfile, see the [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/).

The Dockerfile specified here indicates to use the Apache 2.4 base image (`httpd`). It also includes instructions for copying a source file called `index.html` to a folder on the Apache server that serves webpages. The `EXPOSE` instruction in the Dockerfile tells Docker that the container is listening on port 80.

**To add the Dockerfile**

1. In `codecatalyst-eks-source-repository`, create a file called `Dockerfile` with the following contents:

   ```
   FROM httpd:2.4
   COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
   EXPOSE 80
   ```

   Do not include a file extension.
**Important**  
The Dockerfile must reside in your repository’s root folder. The workflow’s `Docker build` command expects it to be there.

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add Dockerfile"
   git push
   ```

   The Dockerfile is added to your repository.

### deployment.yaml
<a name="deploy-tut-eks-source-files-deployment-yml"></a>

In this section, you add a `deployment.yaml` file to your repository. The `deployment.yaml` file is a Kubernetes manifest that defines two Kubernetes resources types or *kinds* to run: a 'service' and a 'deployment'.
+ The 'service' deploys a load balancer into Amazon EC2. The load balancer provides you with an Internet-facing public URL and standard port (port 80) that you can use to browse to the 'Hello, World\$1' application. 
+ The 'deployment' deploys three pods, and each pod will contain a Docker container with the 'Hello, World\$1' application. The three pods are deployed onto the nodes that were created when you created the cluster.

The manifest in this tutorial is short; however, a manifest can include any number of Kubernetes resource types, such as pods, jobs, ingresses, and network policies. Further, you can use multiple manifest files if your deployment is complex.

**To add a deployment.yaml file**

1. In `codecatalyst-eks-source-repository`, create a folder called `Kubernetes`.

1. In `/Kubernetes`, create a file called `deployment.yaml` with the following contents:

   ```
   apiVersion: v1
   kind: Service
   metadata:
     name: my-service
     labels:
       app: my-app
   spec:
     type: LoadBalancer
     selector:
       app: my-app
     ports:
       - protocol: TCP
         port: 80
         targetPort: 80
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-deployment
     labels:
       app: my-app
   spec:
     replicas: 3
     selector:
       matchLabels:
         app: my-app
     template:
       metadata:
         labels:
           app: my-app
       spec:
         containers:
         - name: codecatalyst-eks-container
           # The $REPOSITORY_URI and $IMAGE_TAG placeholders will be replaced by actual values supplied by the build action in your workflow
           image: $REPOSITORY_URI:$IMAGE_TAG
           ports:
           - containerPort: 80
   ```

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add Kubernetes/deployment.yaml"
   git push
   ```

   The `deployment.yaml` file is added to your repository in a folder called `Kubernetes`. 

You have now added all your source files.

Take a moment to double-check your work and make sure you placed all the files in the correct folders. The folder structure is as follows:

```
|— codecatalyst-eks-source-repository
   |— Kubernetes
      |— deployment.yaml
   |— public-html
   |  |— index.html
   |— Dockerfile
```

## Step 5: Create AWS roles
<a name="deploy-tut-eks-roles"></a>

In this section, you create AWS IAM roles that your CodeCatalyst workflow will need in order to function. These roles are:
+ **Build role** – Grants the CodeCatalyst build action (in the workflow) permission to access your AWS account and write to Amazon ECR and Amazon EC2.
+ **Deploy role** – Grants the CodeCatalyst **Deploy to Kubernetes cluster** action (in the workflow) permission to access your AWS account and Amazon EKS.

For more information about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.

**Note**  
To save time, you can create a single role, called the `CodeCatalystWorkflowDevelopmentRole-spaceName` role, instead of the two roles listed previously. For more information, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has very broad permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. This tutorial assumes you are creating the two roles listed previously.

To create the build and deploy roles, complete the following series of procedures.

**1. To create a trust policy for both roles**

1. Go to your Dev Environment.

1. In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-trust-policy.json` with the following contents:

**2. To create the build policy for the build role**
+ In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-build-policy.json` with the following contents:

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "ecr:*",
                  "ec2:*"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```

**3. To create the deploy policy for the deploy role**
+ In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-deploy-policy.json` with the following contents:

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "eks:DescribeCluster",
                  "eks:ListClusters"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```

You have now added three policy documents to your Dev Environment. Your directory structure now looks like this:

```
|— Cloud9-long-string
   |— .c9
   |— codecatalyst-eks-source-repository
      |— Kubernetes
      |— public-html
      |— Dockerfile
   codecatalyst-eks-build-policy.json
   codecatalyst-eks-deploy-policy.json
   codecatalyst-eks-trust-policy.json
```

**4. To add the build policy to AWS**

1. In the Dev Environment terminal, enter:

   ```
   cd /projects
   ```

1. Enter:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-eks-build-policy \
       --policy-document file://codecatalyst-eks-build-policy.json
   ```

1. Press **Enter**.

1. In the command output, note the `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy`. You need this ARN later.

**5. To add the deploy policy to AWS**

1. Enter:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-eks-deploy-policy \
       --policy-document file://codecatalyst-eks-deploy-policy.json
   ```

1. Press **Enter**.

1. In the command output, note the deploy policy's `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy`. You need this ARN later.

**6. To create the build role**

1. Enter: 

   ```
   aws iam create-role \
         --role-name codecatalyst-eks-build-role \
         --assume-role-policy-document file://codecatalyst-eks-trust-policy.json
   ```

1. Press **Enter**.

1. Enter:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-eks-build-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy
   ```

   Where *arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy* is replaced with the ARN of the build policy you noted earlier.

1. Press **Enter**.

1. At the terminal prompt, enter:

   ```
   aws iam get-role \
         --role-name codecatalyst-eks-build-role
   ```

1. Press **Enter**.

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-eks-build-role`. You need this ARN later.

**7. To create the deploy role**

1. Enter:

   ```
   aws iam create-role \
         --role-name codecatalyst-eks-deploy-role \
         --assume-role-policy-document file://codecatalyst-eks-trust-policy.json
   ```

1. Press **Enter**.

1. Enter:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-eks-deploy-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy
   ```

   Where *arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy* is replaced with the ARN of the deploy policy you noted earlier.

1. Press **Enter**.

1. Enter:

   ```
   aws iam get-role \
         --role-name codecatalyst-eks-deploy-role
   ```

1. Press **Enter**.

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role`. You need this ARN later.

You have now created build and deploy roles and noted their ARNs.

## Step 6: Add AWS roles to CodeCatalyst
<a name="deploy-tut-eks-import-roles"></a>

In this step, you add the build role (`codecatalyst-eks-build-role`) and deploy role (`codecatalyst-eks-deploy-role`) to the AWS account that you connected to your space. This makes the roles available for use in your workflow.

**To add build and deploy roles to your AWS account**

1. In the CodeCatalyst console, navigate to your space.

1. At the top, choose **Settings**.

1. In the navigation pane, choose **AWS accounts**. A list of accounts appears.

1. In the **Amazon CodeCatalyst display name** column, copy the display name of the AWS account where you created your build and deploy roles. (It might be a number.) You'll need this value later, when creating your workflow.

1. Choose the display name.

1. Choose **Manage roles from AWS management console**.

   The **Add IAM role to Amazon CodeCatalyst space** page appears. You might need to sign in to access the page.

1. Select **Add an existing role you have created in IAM**.

   A drop-down list appears. The list displays the build and deploy roles, and any other IAM roles with a trust policy that includes the `codecatalyst-runner.amazonaws.com` and `codecatalyst.amazonaws.com` service principals.

1. From the drop-down list, add:
   + `codecatalyst-eks-build-role`
   + `codecatalyst-eks-deploy-role`
**Note**  
If you see `The security token included in the request is invalid`, it might be because you do not have the right permissions. To fix this issue, sign out of AWS as sign back in with the AWS account that you used when you created your CodeCatalyst space.

1. Return to the CodeCatalyst console and refresh the page.

   The build and deploy roles should now appear under **IAM roles**.

   These roles are now available for use in CodeCatalyst workflows.

## Step 7: Update the ConfigMap
<a name="deploy-tut-eks-configmap"></a>

You must add the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles) to the Kubernetes `ConfigMap` file to give the **Deploy to Kubernetes cluster** action (in your workflow) the ability to access and interact with your cluster. You can use `eksctl` or `kubectl` to perform this task.

**To configure the Kubernetes ConfigMap file using eksctl**
+ In the Dev Environment terminal, enter: 

  ```
  eksctl create iamidentitymapping --cluster codecatalyst-eks-cluster --arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role --group system:masters --username codecatalyst-eks-deploy-role --region us-west-2
  ```

  Where:
  + *codecatalyst-eks-cluster* is replaced with the cluster name of the Amazon EKS cluster.
  +  *arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role* is replaced with the ARN of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
  +  *codecatalyst-eks-deploy-role* (next to `--username`) is replaced with the name of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
**Note**  
If you decided not to create a deploy role, replace *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).
  +  *us-west-2* is replaced with your Region.

  For details on this command, see [Manage IAM users and roles](https://eksctl.io/usage/iam-identity-mappings/).

  A message similar to the following appears:

  ```
  2023-06-09 00:58:29 [ℹ]  checking arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role against entries in the auth ConfigMap
  2023-06-09 00:58:29 [ℹ]  adding identity "arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role" to auth ConfigMap
  ```

**To configure the Kubernetes ConfigMap file using kubectl**

1. In the Dev Environment terminal, enter:

   ```
   kubectl edit configmap -n kube-system aws-auth
   ```

   The ConfigMap file appears on the screen.

1. Add the text in red italics:

   ```
   # Please edit the object below. Lines beginning with a '#' will be ignored,
   # and an empty file will abort the edit. If an error occurs while saving this file will be
   # reopened with the relevant failures.
   #
   apiVersion: v1
   data:
     mapRoles: |
       - groups:
         - system:bootstrappers
         - system:nodes
         rolearn: arn:aws:iam::111122223333:role/eksctl-codecatalyst-eks-cluster-n-NodeInstanceRole-16BC456ME6YR5
         username: system:node:{{EC2PrivateDNSName}}
       - groups:
         - system:masters
         rolearn: arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role
         username: codecatalyst-eks-deploy-role
     mapUsers: |
       []
   kind: ConfigMap
   metadata:
     creationTimestamp: "2023-06-08T19:04:39Z"
     managedFields:
     ...
   ```

   Where:
   +  *arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role* is replaced with the ARN of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles). 
   +  *codecatalyst-eks-deploy-role* (next to `username:`)is replaced with the name of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
**Note**  
If you decided not to create a deploy role, replace *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).

   For details, see [Enabling IAM principal access to your cluster](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) in the **Amazon EKS User Guide**.

You have now given the deploy role, and by extension the **Deploy to Amazon EKS** action, `system:masters` permissions to your Kubernetes cluster.

## Step 8: Create and run a workflow
<a name="deploy-tut-eks-workflow"></a>

In this step, you create a workflow that takes your source files, builds them into a Docker image, and then deploys the image into tree pods in your Amazon EKS cluster.

The workflow consists of the following building blocks that run sequentially:
+ A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A build action (`BuildBackend`) – On trigger, the action builds the Docker image using the Dockerfile and pushes the image to Amazon ECR. The build action also updates the `$REPOSITORY_URI` and `$IMAGE_TAG` variables in the `deployment.yaml` file with the correct values, and then creates an output artifact of this file and any others in the `Kubernetes` folder. In this tutorial, the only file in the `Kubernetes` folder is `deployment.yaml` but you could include more files. The artifact is used as the input for the deploy action, which is next.

  For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ A deploy action (`DeployToEKS`) – On completion of the build action, the deploy action looks for the output artifact generated by the build action (`Manifests`), and finds the `deployment.yaml` file inside of it. The action then follows the instructions in the `deployment.yaml` file to run three pods—each containing a single 'Hello, World\$1' Docker container—inside your Amazon EKS cluster. 

**To create a workflow**

1. Go to the CodeCatalyst console.

1. Navigate to your project (`codecatalyst-eks-project`).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. For **Source repository**, choose `codecatalyst-eks-source-repository`.

1. For **Branch**, choose `main`.

1. Choose **Create**.

1. Delete the YAML sample code.

1. Add the following YAML code to create a new workflow definition file:
**Note**  
For more information about the workflow definition file, see [Workflow YAML definition](workflow-reference.md).
**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies of both roles described in [Step 6: Add AWS roles to CodeCatalyst](#deploy-tut-eks-import-roles). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md).

   ```
   Name: codecatalyst-eks-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     BuildBackend:
       Identifier: aws/build@v1
       Environment:
         Name: codecatalyst-eks-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-eks-build-role
       Inputs:
         Sources:
           - WorkflowSource
         Variables:
           - Name: REPOSITORY_URI
             Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo
           - Name: IMAGE_TAG
             Value: ${WorkflowSource.CommitId}
       Configuration:
         Steps:
           #pre_build:
           - Run: echo Logging in to Amazon ECR...
           - Run: aws --version
           - Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
           #build:
           - Run: echo Build started on `date`
           - Run: echo Building the Docker image...
           - Run: docker build -t $REPOSITORY_URI:latest .
           - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
           #post_build:
           - Run: echo Build completed on `date`
           - Run: echo Pushing the Docker images...
           - Run: docker push $REPOSITORY_URI:latest
           - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
           # Replace the variables in deployment.yaml
           - Run: find Kubernetes/ -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
           - Run: find Kubernetes/ -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
           - Run: cat Kubernetes/*
           # The output artifact will be a zip file that contains Kubernetes manifest files.
       Outputs:
         Artifacts:
           - Name: Manifests
             Files: 
               - "Kubernetes/*"
     DeployToEKS:
       DependsOn: 
         - BuildBackend
       Identifier: aws/kubernetes-deploy@v1
       Environment:
         Name: codecatalyst-eks-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-eks-deploy-role
       Inputs:
         Artifacts:
           - Manifests
       Configuration:
         Namespace: default
         Region: us-west-2
         Cluster: codecatalyst-eks-cluster
         Manifests: Kubernetes/
   ```

   In the preceding code, replace:
   + Both instances of *codecatalyst-eks-environment* with the name of the environment you created in [Prerequisites](#deploy-tut-eks-prereqs).
   + Both instances of *codecatalyst-account-connection* with the display name of your account connection. The display name might be a number. For more information, see [Step 6: Add AWS roles to CodeCatalyst](#deploy-tut-eks-import-roles).
   + *codecatalyst-eks-build-role* with the name of the build role you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo* (in the `Value:` property) with the URI of the Amazon ECR repository you created in [Step 3: Create an Amazon ECR image repository](#deploy-tut-eks-ecr).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com* (in the `Run: aws ecr` command) with the URI of the Amazon ECR repository without the image suffix (`/codecatalyst-eks-image-repo`).
   + *codecatalyst-eks-deploy-role* with the name of the deploy role you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
   + Both instances of *us-west-2* with your AWS Region code. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the *AWS General Reference*.
**Note**  
If you decided not to create build and deploy roles, replace *codecatalyst-eks-build-role* and *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).

1. (Optional) Choose **Validate** to make sure that the YAML code is valid before committing.

1. Choose **Commit**.

1. In the **Commit workflow** dialog box, enter the following:

   1. For **Commit message**, remove the text and enter:

      ```
      Add first workflow
      ```

   1. For **Repository**, choose `codecatalyst-eks-source-repository`.

   1. For **Branch name**, choose main.

   1. Choose **Commit**.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `workflow.yaml` file to your source repository, the trigger started the workflow run.

**To view the workflow run progress**

1. In the navigation pane of the CodeCatalyst console, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created, `codecatalyst-eks-workflow`.

1. Choose **BuildBackend** to see the build progress.

1. Choose **DeployToEKS** to see the deployment progress.

   For more information about viewing run details, see [Viewing workflow run status and details](workflows-view-run.md).

**To verify the deployment**

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. On the left, near the bottom, choose **Load Balancers**.

1. Select the load balancer that was created as part of your Kubernetes deployment. If you're not sure which load balancer to choose, look for the following tags under the **Tags** tab:
   + `kubernetes.io/service-name`
   + `kubernetes.io/cluster/ekstutorialcluster`

1. With the correct load balancer selected, choose the **Description** tab.

1. Copy and paste the **DNS name** value into your browser's address bar.

   The 'Hello, World\$1' webpage appears in your browser, indicating that you successfully deployed your application.

## Step 9: Make a change to your source files
<a name="deploy-tut-eks-change"></a>

In this section, you make a change to the `index.html` file in your source repository. This change causes the workflow to build a new Docker image, tag it with a commit ID, push it to Amazon ECR, and deploy it to Amazon ECS. 

**To change the index.html**

1. Go to your Dev Environment.

1. At the terminal prompt, change to your source repository:

   ```
   cd /projects/codecatalyst-eks-source-repository
   ```

1.  Pull the latest workflow changes:

   ```
   git pull
   ```

1. Open `codecatalyst-eks-source-repository/public-html/index.html`.

1. On line 14, change the `Hello, World!` text to `Tutorial complete!`.

1. Add, commit, and push:

   ```
   git add .
   git commit -m "update index.html title"
   git push
   ```

   A workflow run starts automatically.

1. (Optional) Enter:

   ```
   git show HEAD
   ```

   Note the commit ID for the `index.html` change. This commit ID will be tagged to the Docker image that will be deployed by the workflow run that you just started.

1. Watch the deployment progress:

   1. In the CodeCatalyst console, in the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose `codecatalyst-eks-workflow` to view the latest run.

   1. Choose **BuildBackend**, and **DeployToEKS** to see the workflow run progress.

1. Verify that your application was updated, as follows:

   1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

   1. On the left, near the bottom, choose **Load Balancers**.

   1. Select the load balancer that was created as part of your Kubernetes deployment.

   1. Copy and paste the **DNS name** value into your browser's address bar.

      The 'Tutorial Complete\$1' webpage appears in your browser, indicating that you successfully deployed a new revision of your application.

1. (Optional) In AWS, switch to the Amazon ECR console and verify that the new Docker image was tagged with the commit ID from step 7 of this procedure.

## Clean up
<a name="deploy-tut-eks-cleanup"></a>

You should clean up your environment so that you're not charged unnecessarily for the storage and compute resources used by this tutorial.

**To clean up**

1. Delete your cluster:

   1. In the Dev Environment terminal, enter:

     ```
     eksctl delete cluster --region=us-west-2 --name=codecatalyst-eks-cluster
     ```

     Where:
     + *us-west-2* is replaced with your Region.
     + *codecatalyst-eks-cluster* is replaced with the name of the cluster you created.

     After 5-10 minutes, the cluster and associated resources are deleted, including but not limited to CloudFormation stacks, nodes groups (in Amazon EC2), and load balancers.
**Important**  
If the `eksctl delete cluster` command doesn't work, you may need to refresh your AWS credentials or your `kubectl` credentials. If you're not sure which credentials to refresh, refresh the AWS credentials first. To refresh your AWS credentials, see [How do I fix "Unable to locate credentials" and "ExpiredToken" errors?](troubleshooting-workflows.md#troubleshooting-workflows-auth-errors-eks). To refresh your `kubectl` credentials, see [How do I fix "Unable to connect to the server" errors?](troubleshooting-workflows.md#troubleshooting-workflows-unable-connect-eks).

1. In the AWS console, clean up as follows:

   1. In Amazon ECR, delete `codecatalyst-eks-image-repo`.

   1. In IAM Identity Center, delete:

      1. `codecatalyst-eks-user`

      1. `codecatalyst-eks-permission-set`

   1. In IAM, delete:
      + `codecatalyst-eks-build-role`
      + `codecatalyst-eks-deploy-role`
      + `codecatalyst-eks-build-policy`
      + `codecatalyst-eks-deploy-policy`

1. In the CodeCatalyst console, clean up as follows:

   1. Delete `codecatalyst-eks-workflow`.

   1. Delete `codecatalyst-eks-environment`.

   1. Delete `codecatalyst-eks-source-repository`.

   1. Delete your Dev Environment.

   1. Delete `codecatalyst-eks-project`.

In this tutorial, you learned how to deploy an application to an Amazon EKS service using a CodeCatalyst workflow and a **Deploy to Kubernetes cluster** action.

# Adding the 'Deploy to Kubernetes cluster' action
<a name="deploy-action-eks-adding"></a>

Use the following instructions to add the **Deploy to Kubernetes cluster** action to your workflow. 

**Before you begin**

Before you add the **Deploy to Kubernetes cluster** action to your workflow, you must have the following prepared:

**Tip**  
To set up these prerequisites quickly, follow the instructions in [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).
+ A Kubernetes cluster in Amazon EKS. For information about clusters, see [Amazon EKS clusters](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) in the **Amazon EKS User Guide**.
+ At least one Dockerfile that describes how to assemble your application into a Docker image. For more information about Dockerfiles, see the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
+ At least one Kubernetes manifest file, which is called a *configuration file* or *configuration* in the Kubernetes documentation. For more information, see [Managing resources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) in the Kubernetes documentation.
+ An IAM role that gives the **Deploy to Kubernetes cluster** action the ability to access and interact with your Amazon EKS cluster. For more information, see the [Role](deploy-action-ref-eks.md#deploy.action.eks.environment.connections.role) topic in the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md).

  After creating this role, you must add it to:
  + Your Kubernetes ConfigMap file. To learn how to add a role to a ConfigMap file, see [Enabling IAM principal access to your cluster](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) in the **Amazon EKS User Guide**.
  + CodeCatalyst. To learn how to add an IAM role to CodeCatalyst, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
+ A CodeCatalyst space, project, and environment. The space and environment must both be connected to the AWS account into which you will be deploying your application. For more information, see [Creating a space](spaces-create.md), [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty), and [Deploying into AWS accounts and VPCs](deploy-environments.md).
+ A source repository supported by CodeCatalyst. The repository stores your application source files, Dockerfiles, and Kubernetes manifests. For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).

------
#### [ Visual ]

**To add the 'Deploy to Kubernetes cluster' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Kubernetes cluster** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Kubernetes cluster**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'Deploy to Kubernetes cluster' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Kubernetes cluster** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Kubernetes cluster**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# 'Deploy to Kubernetes cluster' variables
<a name="deploy-action-eks-variables"></a>

The **Deploy to Kubernetes cluster** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  cluster  |  The Amazon.com Resource Name (ARN) of the of the Amazon EKS cluster that was deployed to during the workflow run. Example: `arn:aws:eks:us-west-2:111122223333:cluster/codecatalyst-eks-cluster`  | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:EKS`.  | 
|  metadata  |  Reserved. JSON-formatted metadata related to the cluster deployed during the workflow run.  | 
|  namespace  |  The Kubernetes namespace into which the cluster was deployed. Example: `default`  | 
|  resources  |  Reserved. JSON-formatted metadata related to the resources deployed during the workflow run.  | 
|  server  |  The name of the API server endpoint that you can use to communicate with your cluster using management tools such as `kubectl`. For more information about the API service endpoint, see [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) in the **Amazon EKS User Guide**. Example: `https://random-string.gr7.us-west-2.eks.amazonaws.com`  | 

# 'Deploy to Kubernetes cluster' action YAML
<a name="deploy-action-ref-eks"></a>

The following is the YAML definition of the **Deploy to Kubernetes cluster** action. To learn how to use this action, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  DeployToKubernetesCluster\$1nn: 
    Identifier: aws/kubernetes-deploy@v1
    DependsOn:
      - build-action
    Compute:  
        - Type: EC2 | Lambda
        - Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: DeployToEKS
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - manifest-artifact
    Configuration:
      Namespace: namespace
      Region: us-east-1 
      Cluster: eks-cluster
      Manifests: manifest-path
```

## DeployToKubernetesCluster
<a name="deploy.action.eks.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `DeployToKubernetesCluster_nn`.

Corresponding UI: Configuration tab/**Action display name**

## Identifier
<a name="deploy.action.eks.identifier"></a>

(*DeployToKubernetesCluster*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/kubernetes-deploy@v1`.

Corresponding UI: Workflow diagram/DeployToKubernetesCluster\$1nn/**aws/kubernetes-deploy@v1** label

## DependsOn
<a name="deploy.action.eks.dependson"></a>

(*DeployToKubernetesCluster*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="deploy.action.eks.computename"></a>

(*DeployToKubernetesCluster*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="deploy.action.eks.computetype"></a>

(*DeployToKubernetesCluster*/Compute/**Type**)

(Required if [Compute](#deploy.action.eks.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="deploy.action.eks.computefleet"></a>

(*DeployToKubernetesCluster*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="deploy.action.eks.timeout"></a>

(*DeployToKubernetesCluster*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Environment
<a name="deploy.action.eks.environment"></a>

(*DeployToKubernetesCluster*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="deploy.action.eks.environment.name"></a>

(*DeployToKubernetesCluster*/Environment/**Name**)

(Required if [Environment](#deploy.action.eks.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="deploy.action.eks.environment.connections"></a>

(*DeployToKubernetesCluster*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="deploy.action.eks.environment.connections.name"></a>

(*DeployToKubernetesCluster*/Environment/Connections/**Name**)

(Optional)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="deploy.action.eks.environment.connections.role"></a>

(*DeployToKubernetesCluster*/Environment/Connections/**Role**)

(Required if [Connections](#deploy.action.eks.environment.connections) is included)

Specify the name of the IAM role that the **Deploy to Kubernetes cluster ** action uses to access AWS. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "eks:DescribeCluster",
                  "eks:ListClusters"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```
+ The following custom trust policy:

Make sure that this role is added to:
+ Your account connection. To learn more about adding an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
+ Your Kubernetes ConfigMap. To learn more about adding an IAM role to a ConfigMap, see [Manage IAM users and roles](https://eksctl.io/usage/iam-identity-mappings/) in the `eksctl` documentation.

**Tip**  
See also [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md) for instructions on adding am IAM role to an account connection and ConfigMap.

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Inputs
<a name="deploy.action.eks.inputs"></a>

(*DeployToKubernetesCluster*/**Inputs**)

(Required if [Connections](#deploy.action.eks.environment.connections) is included)

The `Inputs` section defines the data that the `DeployToKubernetesCluster` needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed per **Deploy to Amazon EKS** action.

Corresponding UI: **Inputs** tab

## Sources
<a name="deploy.action.eks.inputs.sources"></a>

(*DeployToKubernetesCluster*/Inputs/**Sources**)

(Required if your manifest file is stored in a source repository)

If your Kubernetes manifest file or files are stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your manifest files are not contained within a source repository, they must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="deploy.action.eks.inputs.artifacts"></a>

(*DeployToKubernetesCluster*/Inputs/**Artifacts**)

(Required if your manifest file is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the Kubernetes manifest file or files are contained in an artifact generated by a previous action, specify that artifact here. If your manifest files are not contained within an artifact, they must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Configuration
<a name="deploy.action.eks.configuration"></a>

(*DeployToKubernetesCluster*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## Namespace
<a name="deploy.action.eks.namespace"></a>

(*DeployToKubernetesCluster*/Configuration/**Namespace**)

(Optional)

Specify the Kubernetes namespace into which your Kubernetes application will be deployed. Use `default` if you are not using namespaces with your cluster. For more information on namespaces, see [Subdividing your cluster using Kubernetes namespaces](https://kubernetes.io/docs/tasks/administer-cluster/namespaces/#subdividing-your-cluster-using-kubernetes-namespaces) in the Kubernetes documentation.

If you omit the namespace, a value of `default` is used.

Corresponding UI: Configuration tab/**Namespace**

## Region
<a name="deploy.action.eks.region"></a>

(*DeployToKubernetesCluster*/Configuration/**Region**)

(Required)

Specify the AWS Region where your Amazon EKS cluster and service reside. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes) in the *AWS General Reference*.

Corresponding UI: Configuration tab/**Region**

## Cluster
<a name="deploy.action.eks.cluster"></a>

(*DeployToKubernetesCluster*/Configuration/**Cluster**)

(Required)

Specify the name of an existing Amazon EKS cluster. The **Deploy to Kubernetes cluster** action will deploy your containerized application into this cluster. For more information about Amazon EKS clusters, see [Clusters](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) in the **Amazon EKS User Guide**.

Corresponding UI: Configuration tab/**Cluster**

## Manifests
<a name="deploy.action.eks.manifest"></a>

(*DeployToKubernetesCluster*/Configuration/**Manifests**)

(Required)

Specify the path to your YAML-formatted Kubernetes manifest file(s), which are called *configuration files*, *config files*, or simply, *configurations* in the Kubernetes documentation.

If you're using multiple manifest files, place them in a single folder and reference that folder. Manifest files are processed alphanumerically by Kubernetes, so make sure to prefix file names with increasing numbers or letters to control the processing order. For example:

`00-namespace.yaml`

`01-deployment.yaml`

If your manifest files reside in your source repository, the path is relative to the source repository root folder. If the files reside in an artifact from a previous workflow action, the path is relative to the artifact root folder. 

Examples:

`Manifests/`

`deployment.yaml`

`my-deployment.yml`

Do not use wildcards (`*`).

**Note**  
[Helm charts](https://helm.sh/docs/topics/charts/) and [kustomization files](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/) are not supported.

For more information about manifest files, see [Organizing resource configurations](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#organizing-resource-configurations) in the Kubernetes documentation.

Corresponding UI: Configuration tab/**Manifests**

# Deploying an CloudFormation stack
<a name="deploy-action-cfn"></a>

This section describes how to deploy a AWS CloudFormation stack using a CodeCatalyst workflow. To accomplish this, you must add the **Deploy CloudFormation stack** action to your workflow. The action deploys a CloudFormation stack of resources into AWS based on a template that you provide. The template can be a:
+ CloudFormation template – For more information, see [Working with CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html).
+ AWS SAM template – For more information, see [AWS Serverless Application Model (AWS SAM) specification](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html).
**Note**  
To use a AWS SAM template, you must first package your AWS SAM application using the `[sam package](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html)` operation. For a tutorial that shows you how to do this packaging automatically as part of a Amazon CodeCatalyst workflow, see [Tutorial: Deploy a serverless application](deploy-tut-lambda.md).

If the stack already exists, the action runs the CloudFormation `[CreateChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateChangeSet.html)` operation, and then the `[ExecuteChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_ExecuteChangeSet.html)` operation. The action then waits for the changes to be deployed and marks itself as either succeeded for failed, depending on the results.

Use the **Deploy CloudFormation stack** action if you already have an CloudFormation or AWS SAM template that contains resources you'd like to deploy, or you plan on generating one automatically as part of a workflow [build action](build-add-action.md) using tools like AWS SAM and [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html).

There are no restrictions on the template you can use—whatever you can author in CloudFormation or AWS SAM you can use with the **Deploy CloudFormation stack** action.

**Tip**  
For a tutorial that shows you how to deploy a serverless application using the **Deploy CloudFormation stack** action, see [Tutorial: Deploy a serverless application](deploy-tut-lambda.md).

**Topics**
+ [

## Runtime image used by the 'Deploy CloudFormation stack' action
](#deploy-action-cfn-runtime)
+ [

# Tutorial: Deploy a serverless application
](deploy-tut-lambda.md)
+ [

# Adding the 'Deploy CloudFormation stack' action
](deploy-action-cfn-adding.md)
+ [

# Configuring rollbacks
](deploy-consumption-enable-alarms.md)
+ [

# 'Deploy CloudFormation stack' variables
](deploy-action-cfn-variables.md)
+ [

# 'Deploy CloudFormation stack' action YAML
](deploy-action-ref-cfn.md)

## Runtime image used by the 'Deploy CloudFormation stack' action
<a name="deploy-action-cfn-runtime"></a>

The **Deploy CloudFormation stack** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Tutorial: Deploy a serverless application
<a name="deploy-tut-lambda"></a>

In this tutorial, you learn how to build, test, and deploy a serverless application as a CloudFormation stack using a workflow.

The application in this tutorial is a simple web application that outputs a 'Hello World' message. It consists of an AWS Lambda function and an Amazon API Gateway, and you build it using the [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html), which is an extension of [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

**Topics**
+ [

## Prerequisites
](#deploy-tut-lambda-cfn-prereqs)
+ [

## Step 1: Create a source repository
](#deploy-tut-lambda-cfn-source)
+ [

## Step 2: Create AWS roles
](#deploy-tut-lambda-cfn-roles)
+ [

## Step 3: Add AWS roles to CodeCatalyst
](#deploy-tut-lambda-cfn-roles-add)
+ [

## Step 4: Create an Amazon S3 bucket
](#deploy-tut-lambda-cfn-s3)
+ [

## Step 5: Add source files
](#deploy-tut-lambda-cfn-files)
+ [

## Step 6: Create and run a workflow
](#deploy-tut-lambda-cfn-workflow)
+ [

## Step 7: Make a change
](#deploy-tut-lambda-cfn-change)
+ [

## Clean up
](#deploy-tut-lambda-cfn-clean-up)

## Prerequisites
<a name="deploy-tut-lambda-cfn-prereqs"></a>

Before you begin:
+ You need a CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ In your space, you need an empty project called:

  ```
  codecatalyst-cfn-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need a CodeCatalyst **environment** called:

  ```
  codecatalyst-cfn-environment
  ```

  Configure this environment as follows:
  + Choose any type, such as **Non-production**.
  + Connect your AWS account to it.
  + For the **Default IAM role**, choose any role. You'll specify a different role later.

  For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Step 1: Create a source repository
<a name="deploy-tut-lambda-cfn-source"></a>

In this step, you create a source repository in CodeCatalyst. This repository is used to store the tutorial's source files, such as the Lambda function file. 

For more information about source repositories, see [Creating a source repository](source-repositories-create.md).

**To create a source repository**

1. In CodeCatalyst, in the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose **Add repository**, and then choose **Create repository**.

1. In **Repository name**, enter:

   ```
   codecatalyst-cfn-source-repository
   ```

1. Choose **Create**.

You have now created a repository called `codecatalyst-cfn-source-repository`.

## Step 2: Create AWS roles
<a name="deploy-tut-lambda-cfn-roles"></a>

In this step, you create the following AWS IAM roles:
+ **Deploy role** – Grants the CodeCatalyst **Deploy CloudFormation stack** action permission to access your AWS account and CloudFormation service where you’ll deploy your serverless application. The **Deploy CloudFormation stack** action is part of your workflow.
+ **Build role** – Grants the CodeCatalyst build action permission to access your AWS account and write to Amazon S3 where your serverless application package will be stored. The build action is part of your workflow.
+ **Stack role** – Grants CloudFormation permission to read and modify the resources specified in the AWS SAM template that you will provide later. Also grants permission to CloudWatch.

For more information about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.

**Note**  
To save time, you can create a single role, called the `CodeCatalystWorkflowDevelopmentRole-spaceName` role, instead of the three roles listed previously. For more information, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has very broad permissions that may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. This tutorial assumes you are creating the three roles listed previously.

**Note**  
A [Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) is also required, but you don't need to create it now because the `sam-template.yml` file creates it for you when you run the workflow in step 5.



**To create a deploy role**

1. Create a policy for the role, as follows:

   1. Sign in to AWS.

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. In the navigation pane, choose **Policies**.

   1. Choose **Create policy**.

   1. Choose the **JSON** tab.

   1. Delete the existing code.

   1. Paste the following code:
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Choose **Next: Tags**.

   1. Choose **Next: Review**.

   1. In **Name**, enter:

      ```
      codecatalyst-deploy-policy
      ```

   1. Choose **Create policy**.

      You have now created a permissions policy.

1. Create the deploy role, as follows:

   1. In the navigation pane, choose **Roles**, and then choose **Create role**.

   1. Choose **Custom trust policy**.

   1. Delete the existing custom trust policy.

   1. Add the following custom trust policy:

   1. Choose **Next**.

   1. In **Permissions policies**, search for `codecatalyst-deploy-policy` and select its check box.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-deploy-role
      ```

   1. For **Role description**, enter:

      ```
      CodeCatalyst deploy role
      ```

   1. Choose **Create role**.

   You have now created a deploy role with a trust policy and permissions policy.

1. Obtain the deploy role ARN, as follows:

   1. In the navigation pane, choose **Roles**.

   1. In the search box, enter the name of the role you just created (`codecatalyst-deploy-role`).

   1. Choose the role from the list.

      The role's **Summary** page appears.

   1. At the top, copy the **ARN** value.

   You have now created the deploy role with the appropriate permissions, and obtained its ARN.

**To create a build role**

1. Create a policy for the role, as follows:

   1. Sign in to AWS.

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. In the navigation pane, choose **Policies**.

   1. Choose **Create policy**.

   1. Choose the **JSON** tab.

   1. Delete the existing code.

   1. Paste the following code:
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

      ```
      "Resource": "*"
      ```

   1. Choose **Next: Tags**.

   1. Choose **Next: Review**.

   1. In **Name**, enter:

      ```
      codecatalyst-build-policy
      ```

   1. Choose **Create policy**.

      You have now created a permissions policy.

1. Create the build role, as follows:

   1. In the navigation pane, choose **Roles**, and then choose **Create role**.

   1. Choose **Custom trust policy**.

   1. Delete the existing custom trust policy.

   1. Add the following custom trust policy:

   1. Choose **Next**.

   1. In **Permissions policies**, search for `codecatalyst-build-policy` and select its check box.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-build-role
      ```

   1. For **Role description**, enter:

      ```
      CodeCatalyst build role
      ```

   1. Choose **Create role**.

   You have now created a build role with a trust policy and permissions policy.

1. Obtain the build role ARN, as follows:

   1. In the navigation pane, choose **Roles**.

   1. In the search box, enter the name of the role you just created (`codecatalyst-build-role`).

   1. Choose the role from the list.

      The role's **Summary** page appears.

   1. At the top, copy the **ARN** value.

   You have now created the build role with the appropriate permissions, and obtained its ARN.<a name="deploy-tut-lambda-cfn-roles-stack"></a>

**To create a stack role**

1. Sign in to AWS using the account where you want to deploy your stack.

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. Create the stack role as follows:

   1. In the navigation pane, choose **Roles**.

   1. Choose **Create role**.

   1. Choose **AWS service**.

   1. In the **Use case** section, choose **CloudFormation** from the drop-down list.

   1. Select the **CloudFormation** radio button.

   1. At the bottom, choose **Next**.

   1. Using the search box, find the following permissions policies, and then select their respective check boxes.
**Note**  
If you search for a policy and it doesn't appear, make sure to choose **Clear filters** and try again.
      + **CloudWatchFullAccess**
      + **AWSCloudFormationFullAccess**
      + **IAMFullAccess**
      + **AWSLambda\$1FullAccess**
      + **AmazonAPIGatewayAdministrator**
      + **AmazonS3FullAccess**
      + **AmazonEC2ContainerRegistryFullAccess**

      The first policy allows access to CloudWatch to enable stack rollbacks when an alarm occurs.

      The remaining policies allow AWS SAM to access the services and resources in the stack that will be deployed in this tutorial. For more information, see [Permissions](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-permissions.html) in the *AWS Serverless Application Model Developer Guide*.

   1. Choose **Next**.

   1. For **Role name**, enter:

      ```
      codecatalyst-stack-role
      ```

   1. Choose **Create role**.

1. Obtain the stack role's ARN, as follows:

   1. In the navigation pane, choose **Roles**.

   1. In the search box, enter the name of the role you just created (`codecatalyst-stack-role`).

   1. Choose the role from the list.

   1. In the **Summary** section, copy the **ARN** value. You need it later.

   You have now created the stack role with the appropriate permissions, and you have obtained its ARN.

## Step 3: Add AWS roles to CodeCatalyst
<a name="deploy-tut-lambda-cfn-roles-add"></a>

In this step, you add the build role (`codecatalyst-build-role`) and deploy role (`codecatalyst-deploy-role`) to the CodeCatalyst account connection in your space.

**Note**  
You don't need to add the stack role (`codecatalyst-stack-role`) to the connection. This is because the stack role is used by *CloudFormation* (not CodeCatalyst), *after* a connection is already established between CodeCatalyst and AWS using the deploy role. Since the stack role is not used by CodeCatalyst to gain access to AWS, it does not need to be associated with an account connection.

**To add build and deploy roles to your account connection**

1. In CodeCatalyst, navigate to your space.

1. Choose **AWS accounts**. A list of account connections appears.

1. Choose the account connection that represents the AWS account where you created your build and deploy roles.

1. Choose **Manage roles from AWS management console**.

   The **Add IAM role to Amazon CodeCatalyst space** page appears. You might need to sign in to access the page.

1. Select **Add an existing role you have created in IAM**.

   A drop-down list appears. The list displays all IAM roles with a trust policy that includes the `codecatalyst-runner.amazonaws.com` and `codecatalyst.amazonaws.com` service principals.

1. In the drop-down list, choose `codecatalyst-build-role`, and choose **Add role**.

1. Choose **Add IAM role**, choose **Add an existing role you have created in IAM**, and in the drop-down list, choose `codecatalyst-deploy-role`. Choose **Add role**.

   You have now added the build and deploy roles to your space.

1. Copy the value of the **Amazon CodeCatalyst display name**. You'll need this value later, when creating your workflow.

## Step 4: Create an Amazon S3 bucket
<a name="deploy-tut-lambda-cfn-s3"></a>

In this step, you create an Amazon S3 bucket where you store your serverless application's deployment package .zip file.

**To create an Amazon S3 bucket**

1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. In the main pane, choose **Create bucket**.

1. For **Bucket name**, enter:

   ```
   codecatalyst-cfn-s3-bucket
   ```

1. For **AWS Region**, choose a Region. This tutorial assumes you chose **US West (Oregon) us-west-2**. For information about Regions supported by Amazon S3, see [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html) in the *AWS General Reference*.

1. At the bottom of the page, choose **Create bucket**.

You have now created a bucket called **codecatalyst-cfn-s3-bucket** in the US West (Oregon) us-west-2 Region.

## Step 5: Add source files
<a name="deploy-tut-lambda-cfn-files"></a>

In this step, you add several application source files to your CodeCatalyst source repository. The `hello-world` folder contains the application files that you'll deploy. The `tests` folder contains unit tests. The folder structure is as follows:

```
.
|— hello-world
|  |— tests
|     |— unit
|        |— test-handler.js
|  |— app.js
|— .npmignore
|— package.json
|— sam-template.yml
|— setup-sam.sh
```

### .npmignore file
<a name="deploy-tut-lambda-cfn-files-npmignore"></a>

The `.npmignore` file indicates which files and folders npm should exclude from the application package. In this tutorial, npm excludes the `tests` folder because it is not part of the application.

**To add the .npmignore file**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project, `codecatalyst-cfn-project`

1. In the navigation pane, choose **Code**, and then choose **Source repositories**.

1. From the list of source repositories, choose your repository, `codecatalyst-cfn-source-repository`. 

1. In **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   .npmignore
   ```

1. In the text box, enter the following code:

   ```
   tests/*
   ```

1. Choose **Commit**, and then choose **Commit** again.

   You have now created a file called `.npmignore` in the root of your repository.

### package.json file
<a name="deploy-tut-lambda-cfn-files-package-json"></a>

The `package.json` file contains important metadata about your Node project such as the project name, version number, description, dependencies, and other details that describe how to interact with and run your application.

The `package.json` in this tutorial includes a list of dependencies and a `test` script. The test script does the following:
+ Using [mocha](https://mochajs.org/), the test script runs the unit tests specified in `hello-world/tests/unit/` and writes the results to a `junit.xml` file using the [xunit]() reporter.
+ Using [Istanbul (nyc)](https://istanbul.js.org/), the test script generates a code coverage report (`clover.xml`) using the [clover](https://openclover.org/doc/manual/4.2.0/general--about-openclover.html) reporter. For more information, see [Using alternative reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/#clover) in the Istanbul documentation.

**To add the package.json file**

1. In your repository, in **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   package.json
   ```

1. In the text box, enter the following code:

   ```
   {
     "name": "hello_world",
     "version": "1.0.0",
     "description": "hello world sample for NodeJS",
     "main": "app.js",
     "repository": "https://github.com/awslabs/aws-sam-cli/tree/develop/samcli/local/init/templates/cookiecutter-aws-sam-hello-nodejs",
     "author": "SAM CLI",
     "license": "MIT",
     "dependencies": {
       "axios": "^0.21.1",
       "nyc": "^15.1.0"
     },
     "scripts": {
       "test": "nyc --reporter=clover mocha hello-world/tests/unit/ --reporter xunit --reporter-option output=junit.xml"
     },
     "devDependencies": {
       "aws-sdk": "^2.815.0",
       "chai": "^4.2.0",
       "mocha": "^8.2.1"
     }
   }
   ```

1. Choose **Commit**, and then choose **Commit** again.

   You have now added a file called `package.json` to the root of the repository.

### sam-template.yml file
<a name="deploy-tut-lambda-cfn-files-sam-template-yml"></a>

The `sam-template.yml` file contains the instructions for deploying the Lambda function and API Gateway and configuring them together. It follows the [AWS Serverless Application Model template specification](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html), which extends the CloudFormation template specification.

You use an AWS SAM template in this tutorial instead of a regular CloudFormation template because AWS SAM offers a helpful [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) resource type. This type performs much behind-the-scenes configuration that you normally have to write out to use the basic CloudFormation syntax. For example, the `AWS::Serverless::Function` creates a Lambda function, Lambda execution role, and event source mappings that start the function. You have to code all of this if you want to write it using basic CloudFormation.

Although this tutorial uses a pre-written template, you can generate one as part of your workflow using a build action. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md).

**To add the sam-template.yml file**

1. In your repository, in **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   sam-template.yml
   ```

1. In the text box, enter the following code:

   ```
   AWSTemplateFormatVersion: '2010-09-09'
   Transform: AWS::Serverless-2016-10-31
   Description: >
     serverless-api
   
     Sample SAM Template for serverless-api
     
   # More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
   Globals:
     Function:
       Timeout: 3
   
   Resources:
     HelloWorldFunction:
       Type: AWS::Serverless::Function # For details on this resource type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
       Properties:
         CodeUri: hello-world/
         Handler: app.lambdaHandler
         Runtime: nodejs12.x
         Events:
           HelloWorld:
             Type: Api # For details on this event source type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
             Properties:
               Path: /hello
               Method: get
   
   Outputs:
     # ServerlessRestApi is an implicit API created out of the events key under Serverless::Function
     # Find out about other implicit resources you can reference within AWS SAM at
     # https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api
     HelloWorldApi:
       Description: "API Gateway endpoint URL for the Hello World function"
       Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"
     HelloWorldFunction:
       Description: "Hello World Lambda function ARN"
       Value: !GetAtt HelloWorldFunction.Arn
     HelloWorldFunctionIamRole:
       Description: "Implicit Lambda execution role created for the Hello World function"
       Value: !GetAtt HelloWorldFunctionRole.Arn
   ```

1. Choose **Commit**, and then choose **Commit** again.

   You have now added a file called `sam-template.yml` under the root folder of your repository.

### setup-sam.sh file
<a name="deploy-tut-lambda-cfn-files-setup-sam"></a>

The `setup-sam.sh` file contains the instructions for downloading and installing the AWS SAM CLI utility. The workflow uses this utility to package the `hello-world` source.

**To add the setup-sam.sh file**

1. In your repository, in **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   setup-sam.sh
   ```

1. In the text box, enter the following code:

   ```
   #!/usr/bin/env bash
   echo "Setting up sam"
   
   yum install unzip -y
   
   curl -LO https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
   unzip -qq aws-sam-cli-linux-x86_64.zip -d sam-installation-directory
   
   ./sam-installation-directory/install; export AWS_DEFAULT_REGION=us-west-2
   ```

   In the preceding code, replace *us-west-2* with your AWS Region.

1. Choose **Commit**, and then choose **Commit** again.

   You have now added a file called `setup-sam.sh` to the root of the repository.

### app.js file
<a name="deploy-tut-lambda-cfn-files-app-js"></a>

The `app.js` contains the Lambda function code. In this tutorial, the code returns the text `hello world`.

**To add the app.js file**

1. In your repository, in **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   hello-world/app.js
   ```

1. In the text box, enter the following code:

   ```
   // const axios = require('axios')
   // const url = 'http://checkip.amazonaws.com/';
   let response;
   
   /**
    *
    * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
    * @param {Object} event - API Gateway Lambda Proxy Input Format
    *
    * Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html 
    * @param {Object} context
    *
    * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
    * @returns {Object} object - API Gateway Lambda Proxy Output Format
    * 
    */
   exports.lambdaHandler = async (event, context) => {
       try {
           // const ret = await axios(url);
           response = {
               'statusCode': 200,
               'body': JSON.stringify({
                   message: 'hello world',
                   // location: ret.data.trim()
               })
           }
       } catch (err) {
           console.log(err);
           return err;
       }
   
       return response
   };
   ```

1. Choose **Commit**, and then choose **Commit** again.

   You have now created a folder called `hello-world` and a file called `app.js`.

### test-handler.js file
<a name="deploy-tut-lambda-cfn-files-test-handler-js"></a>

The `test-handler.js` file contains unit tests for the Lambda function.

**To add the test-handler.js file**

1. In your repository, in **Files**, choose **Create file**.

1. For **File name**, enter:

   ```
   hello-world/tests/unit/test-handler.js
   ```

1. In the text box, enter the following code:

   ```
   'use strict';
   
   const app = require('../../app.js');
   const chai = require('chai');
   const expect = chai.expect;
   var event, context;
   
   describe('Tests index', function () {
       it('verifies successful response', async () => {
           const result = await app.lambdaHandler(event, context)
   
           expect(result).to.be.an('object');
           expect(result.statusCode).to.equal(200);
           expect(result.body).to.be.an('string');
   
           let response = JSON.parse(result.body);
   
           expect(response).to.be.an('object');
           expect(response.message).to.be.equal("hello world");
           // expect(response.location).to.be.an("string");
       });
   });
   ```

1. Choose **Commit**, and then choose **Commit** again.

   You have now added a file called `test-handler.js` under the `hello-world/tests/unit` folder.

You have now added all your source files.

Take a moment to double-check your work and make sure you placed all the files in the correct folders. The folder structure is as follows:

```
.
|— hello-world
|  |— tests
|     |— unit
|        |— test-handler.js
|  |— app.js
|— .npmignore
|— README.md
|— package.json
|— sam-template.yml
|— setup-sam.sh
```

## Step 6: Create and run a workflow
<a name="deploy-tut-lambda-cfn-workflow"></a>

In this step, you create a workflow that packages your Lambda source code and deploys it. The workflow consists of the following building blocks that run sequentially:
+ A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A test action (`Test`) – On trigger, this action installs [Node package manager (npm)](https://www.npmjs.com/), and then runs the `npm run test` command. This command tells npm to run the `test` script defined in the `package.json` file. The `test` script, in turn, runs the unit tests and generates two reports: a test report (`junit.xml`) and a code coverage report (`clover.xml`). For more information, see [package.json file](#deploy-tut-lambda-cfn-files-package-json).

  Next, the test action transforms the XML reports into CodeCatalyst reports and displays them in the CodeCatalyst console, under the **Reports** tab of the test action.

  For more information about the test action, see [Testing with workflowsTesting with workflows](test-workflow-actions.md).
+ A build action (`BuildBackend`) – On completion of the test action, the build action downloads and installs the AWS SAM CLI, packages the `hello-world` source, and copies the package to your Amazon S3 bucket, where the Lambda service expects it to be. The action also outputs a new AWS SAM template file called `sam-template-packaged.yml` and places it in an output artifact called `buildArtifact`.

  For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ A deploy action (`DeployCloudFormationStack`) – On completion of the build action, the deploy action looks for the output artifact generated by the build action (`buildArtifact`), finds the AWS SAM template inside of it, and then runs the template. The AWS SAM template creates a stack that deploys the serverless application.

**To create a workflow**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. For **Source repository**, choose `codecatalyst-cfn-source-repository`.

1. For **Branch**, choose `main`.

1. Choose **Create**.

1. Delete the YAML sample code.

1. Add the following YAML code:
**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies of both roles described in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md).

   ```
   Name: codecatalyst-cfn-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: PUSH
       Branches:
         - main   
   Actions:
     Test:
       Identifier: aws/managed-test@v1
       Inputs:
         Sources:
           - WorkflowSource
       Outputs:
         Reports:
           CoverageReport:
             Format: CLOVERXML
             IncludePaths:
               - "coverage/*"
           TestReport:
             Format: JUNITXML
             IncludePaths:
               - junit.xml
       Configuration:
         Steps:
           - Run: npm install
           - Run: npm run test  
     BuildBackend:
       Identifier: aws/build@v1
       DependsOn:
         - Test
       Environment:
         Name: codecatalyst-cfn-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-build-role
       Inputs:
         Sources:
           - WorkflowSource
       Configuration: 
         Steps:
           - Run: . ./setup-sam.sh
           - Run: sam package --template-file sam-template.yml --s3-bucket codecatalyst-cfn-s3-bucket --output-template-file sam-template-packaged.yml --region us-west-2
       Outputs:
         Artifacts:
           - Name: buildArtifact
             Files:
               - "**/*"
     DeployCloudFormationStack:
       Identifier: aws/cfn-deploy@v1
       DependsOn: 
         - BuildBackend
       Environment:
         Name: codecatalyst-cfn-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-deploy-role
       Inputs:
         Artifacts:
           - buildArtifact
         Sources: []
       Configuration:
         name: codecatalyst-cfn-stack
         region: us-west-2
         role-arn: arn:aws:iam::111122223333:role/StackRole
         template: ./sam-template-packaged.yml
         capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
   ```

   In the preceding code, replace:
   + Both instances of *codecatalyst-cfn-environment* with the name of your environment.
   + Both instances of *codecatalyst-account-connection* with the display name of your account connection. The display name might be a number. For more information, see [Step 3: Add AWS roles to CodeCatalyst](#deploy-tut-lambda-cfn-roles-add).
   + *codecatalyst-build-role* with the name of the build role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles).
   + *codecatalyst-cfn-s3-bucket* with the name of the Amazon S3 bucket you created in [Step 4: Create an Amazon S3 bucket](#deploy-tut-lambda-cfn-s3).
   + Both instances of *us-west-2* with the Region where your Amazon S3 bucket resides (first instance) and where your stack will be deployed (second instance). These Regions can be different. This tutorial assumes that both Regions are set to `us-west-2`. For details about Regions supported by Amazon S3 and CloudFormation, see [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*.
   + *codecatalyst-deploy-role* with the name of the deploy role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles).
   + *codecatalyst-cfn-environment* with the name of the environment that you created in [Prerequisites](#deploy-tut-lambda-cfn-prereqs).
   + *arn:aws:iam::111122223333:role/StackRole* with the Amazon Resource Name (ARN) of the stack role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles).
**Note**  
If you decided not to create build, deploy, and stack roles, replace *codecatalyst-build-role*, *codecatalyst-deploy-role*, and *arn:aws:iam::111122223333:role/StackRole* with the name or ARN of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles).

   For information about the properties in the code shown previously, see the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md).

1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing.

1. Choose **Commit**.

1. On the **Commit workflow** dialog box, enter the following:

   1. For **Workflow file name**, keep the default, `codecatalyst-cfn-workflow`.

   1. For **Commit message**, enter:

      ```
      add initial workflow file
      ```

   1. For **Repository**, choose **codecatalyst-cfn-source-repository**.

   1. For **Branch name**, choose **main**.

   1. Choose **Commit**.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `codecatalyst-cfn-workflow.yaml` file to your source repository, the trigger started the workflow run.

**To view the workflow run in progress**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created: `codecatalyst-cfn-workflow`.

1. Choose the **Runs** tab.

1. In the **Run ID** column, choose the run ID.

1. Choose **Test** to see the tests progress.

1. Choose **BuildBackend** to see the build progress.

1. Choose **DeployCloudFormationStack** to see the deployment progress.

   For more information about viewing run details, see [Viewing workflow run status and details](workflows-view-run.md).

1. When the **DeployCloudFormationStack** action finishes, do the following:
   + If the workflow run succeeded, go to the next procedure.
   + If the workflow run failed on the **Test** or **BuildBackend** action, choose **Logs** to troubleshoot the issue.
   + If the workflow run failed on the **DeployCloudFormationStack** action, choose the deploy action, and then choose the **Summary** tab. Scroll to the **CloudFormation events** section to view the detailed error message. If a rollback occurred, delete the `codecatalyst-cfn-stack` stack through the CloudFormation console in AWS before re-running the workflow.

**To verify the deployment**

1. After a successful deployment, choose **Variables (7)** from the horizontal menu bar near the top. (Do not choose **Variables** in the pane on the right.)

1. Next to **HelloWorldApi**, paste the `https://` URL into a browser.

   A **hello world** JSON message from the Lambda function is displayed, indicating that the workflow deployed and configured the Lambda function and API Gateway successfully.
**Tip**  
You can have CodeCatalyst display this URL in the workflow diagram with a few small configurations. For more information, see [Displaying the app URL in the workflow diagram](deploy-app-url.md).

**To verify unit test results and code coverage**

1. In the workflow diagram, choose **Test**, and then choose **Reports**.

1. Choose **TestReport** to view the unit test results, or choose **CoverageReport** to view the code coverage details of the files being tested, in this case, `app.js` and `test-handler.js`.

**To verify deployed resources**

1. Sign in to the AWS Management Console and open the API Gateway console at [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/). 

1. Observe the **codecatalyst-cfn-stack** API that the AWS SAM template created. The API name comes from the `Configuration/name` value in the workflow definition file (`codecatalyst-cfn-workflow.yaml`).

1. Open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).

1. In the navigation pane, choose **Functions**.

1. Choose your Lambda function, `codecatalyst-cfn-stack-HelloWorldFunction-string`.

1. You can see how the API Gateway is a trigger for the function. This integration was automatically configured by the AWS SAM `AWS::Serverless::Function` resource type.

## Step 7: Make a change
<a name="deploy-tut-lambda-cfn-change"></a>

In this step, you make a change to your Lambda source code and commit it. This commit starts a new workflow run. This run deploys the new Lambda function in a blue-green scheme that uses the default traffic shifting configuration specified in the Lambda console.

**To make a change to your Lambda source**

1. In CodeCatalyst, navigate to your project.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**.

1. Choose your source repository `codecatalyst-cfn-source-repository`.

1. Change the application file:

   1. Choose the `hello-world` folder.

   1. Choose the `app.js` file.

   1. Choose **Edit**.

   1. On line 23, change `hello world` to **Tutorial complete\$1**.

   1. Choose **Commit**, and then choose **Commit** again.

      The commit causes a workflow run to start. This run will fail because you haven't updated the unit tests to reflect the name change.

1. Update the unit tests:

   1. Choose `hello-world\tests\unit\test-handler.js`.

   1. Choose **Edit**.

   1. On line 19, change `hello world` to **Tutorial complete\$1**.

   1. Choose **Commit**, and then choose **Commit** again.

      The commit causes another workflow run to start. This run will succeed.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose `codecatalyst-cfn-workflow`, and then choose **Runs**.

1. Choose the run ID of the latest run. It should still be in progress.

1. Choose **Test**, **BuildBackend**, and **DeployCloudFormationStack** to see the workflow run progress.

1. When the workflow finishes, choose **Variables (7)** near the top.

1. Next to **HelloWorldApi**, paste the `https://` URL into a browser.

   A `Tutorial complete!` message appears in the browser, indicating that your new application was deployed successfully.

## Clean up
<a name="deploy-tut-lambda-cfn-clean-up"></a>

Clean up the files and services used in this tutorial to avoid being charged for them.

**To clean up in the CodeCatalyst console**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Delete `codecatalyst-cfn-workflow`.

1. Delete `codecatalyst-cfn-environment`.

1. Delete `codecatalyst-cfn-source-repository`.

1. Delete `codecatalyst-cfn-project`.

**To clean up in the AWS Management Console**

1. Clean up in CloudFormation, as follows:

   1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).

   1. Delete the `codecatalyst-cfn-stack`.

      Deleting the stack removes all tutorial resources from the API Gateway and Lambda services.

1. Clean up in Amazon S3, as follows:

   1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

   1. Choose the `codecatalyst-cfn-s3-bucket`.

   1. Delete the bucket contents.

   1. Delete the bucket.

1. Clean up in IAM, as follows:

   1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

   1. Delete the `codecatalyst-deploy-policy`.

   1. Delete the `codecatalyst-build-policy`.

   1. Delete the `codecatalyst-stack-policy`.

   1. Delete the `codecatalyst-deploy-role`.

   1. Delete the `codecatalyst-build-role`.

   1. Delete the `codecatalyst-stack-role`.

In this tutorial, you learned how to deploy a serverless application as a CloudFormation stack using a CodeCatalyst workflow and a **Deploy CloudFormation stack** action.

# Adding the 'Deploy CloudFormation stack' action
<a name="deploy-action-cfn-adding"></a>

Use the following instructions to add the **Deploy CloudFormation stack** action to your workflow. 

------
#### [ Visual ]

**To add the 'Deploy CloudFormation stack' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy CloudFormation stack** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy CloudFormation stack**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'Deploy CloudFormation stack' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy CloudFormation stack** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy CloudFormation stack**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Configuring rollbacks
<a name="deploy-consumption-enable-alarms"></a>

By default, if the **Deploy CloudFormation stack** action fails, it will cause CloudFormation to roll back the stack to the last known stable state. You can change the behavior so that rollbacks occur not only when the action fails, but also when a specified Amazon CloudWatch alarm occurs. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/) in the *Amazon CloudWatch User Guide*.

You can also change the default behavior so that CloudFormation does not roll back the stack when the action fails. 

Use the following instructions to configure rollbacks.

**Note**  
You cannot start a rollback manually.

------
#### [ Visual ]

**Before you begin**

1. Make sure you have a [workflow](workflow.md) that includes a functioning **Deploy CloudFormation stack** action. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md).

1. In the role specified in the **Stack role - optional** field of the **Deploy CloudFormation stack** action, make sure to include the **CloudWatchFullAccess** permission. For information about creating this role with the appropriate permissions, see [Step 2: Create AWS roles](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles).

**To configure rollback alarms for the 'Deploy CloudFormation stack' action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose your **Deploy CloudFormation stack** action.

1. In the details pane, choose **Configuration**.

1. At the bottom, expand **Advanced**.

1. Under **Monitor alarm ARNs**, choose **Add alarm**.

1. Enter information into the following fields.
   + **Alarm ARN**

     Specify the Amazon Resource Name (ARN) of an Amazon CloudWatch alarm to use as a rollback trigger. For example, `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`. You can have a maximum of five rollback triggers.
**Note**  
If you specify a CloudWatch alarm ARN, you'll also need to configure additional permissions to enable the action to access CloudWatch. For more information, see [Configuring rollbacks](#deploy-consumption-enable-alarms).
   + **Monitoring time**

     Specify an amount of time, from 0 to 180 minutes, during which CloudFormation monitors the specified alarms. Monitoring begins *after* all the stack resources have been deployed. If the alarm occurs within the specified monitoring time, then the deployment fails, and CloudFormation rolls back the entire stack operation.

     Default: 0. CloudFormation only monitors alarms while the stack resources are being deployed, not after.

------
#### [ YAML ]

**To configure rollback triggers for the 'Deploy CloudFormation stack' action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Add the `monitor-alarm-arns` and `monitor-timeout-in-minutes` properties in the YAML code to add rollback triggers. For an explanation of each property, see ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md).

1. In the role specified in the `role-arn` property of the **Deploy CloudFormation stack** action, make sure to include the **CloudWatchFullAccess** permission. For information about creating this role with the appropriate permissions, see [Step 2: Create AWS roles](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles).

------

------
#### [ Visual ]

**To turn off rollbacks for the 'Deploy CloudFormation stack' action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose your **Deploy CloudFormation stack** action.

1. In the details pane, choose **Configuration**.

1. At the bottom, expand **Advanced**.

1. Turn on **Disable rollback**.

------
#### [ YAML ]

**To turn off rollbacks for the 'Deploy CloudFormation stack' action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Add the `disable-rollback: 1` property in the YAML code to stop rollbacks. For an explanation of this property, see ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md).

------

# 'Deploy CloudFormation stack' variables
<a name="deploy-action-cfn-variables"></a>

The **Deploy CloudFormation stack** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:CloudFormation`.  | 
|  region  |  The region code of the AWS Region that was deployed to during the workflow run. Example: `us-west-2`  | 
|  stack-id  |  The Amazon Resource Name (ARN) of the deployed stack. Example: `arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cfn-stack/6aad4380-100a-11ec-a10a-03b8a84d40df`  | 

# 'Deploy CloudFormation stack' action YAML
<a name="deploy-action-ref-cfn"></a>

The following is the YAML definition of the **Deploy CloudFormation stack** action. To learn how to use this action, see [Deploying an CloudFormation stack](deploy-action-cfn.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.    
  DeployCloudFormationStack:  
    Identifier: aws/cfn-deploy@v1
    DependsOn:
      - build-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: DeployRole
    Inputs:
      Sources:
        - source-name-1
      Artifacts:
        - CloudFormation-artifact
    Configuration:
      name: stack-name
      region: us-west-2
      template: template-path
      role-arn: arn:aws:iam::123456789012:role/StackRole        
      capabilities: CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
      parameter-overrides: KeyOne=ValueOne,KeyTwo=ValueTwo | path-to-JSON-file
      no-execute-changeset: 1|0
      fail-on-empty-changeset: 1|0
      disable-rollback: 1|0
      termination-protection: 1|0
      timeout-in-minutes: minutes
      notification-arns: arn:aws:sns:us-east-1:123456789012:MyTopic,arn:aws:sns:us-east-1:123456789012:MyOtherTopic
      monitor-alarm-arns: arn:aws:cloudwatch::123456789012:alarm/MyAlarm,arn:aws:cloudwatch::123456789012:alarm/MyOtherAlarm
      monitor-timeout-in-minutes: minutes       
      tags: '[{"Key":"MyKey1","Value":"MyValue1"},{"Key":"MyKey2","Value":"MyValue2"}]'
```

## DeployCloudFormationStack
<a name="deploy.action.cfn.deploycloudformationstack"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `DeployCloudFormationStack_nn`.

Corresponding UI: Configuration tab/**Action display name**

## Identifier
<a name="deploy.action.cfn.identifier"></a>

(*DeployCloudFormationStack*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/cfn-deploy@v1`.

Corresponding UI: Workflow diagram/DeployCloudFormationStack\$1nn/**aws/cfn-deploy@v1** label

## DependsOn
<a name="deploy.action.cfn.dependson"></a>

(*DeployCloudFormationStack*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="deploy.action.cfn.computename"></a>

(*DeployCloudFormationStack*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="deploy.action.cfn.computetype"></a>

(*DeployCloudFormationStack*/Compute/**Type**)

(Required if [Compute](#deploy.action.cfn.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="deploy.action.cfn.computefleet"></a>

(*DeployCloudFormationStack*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="deploy.action.cfn.timeout"></a>

(*DeployCloudFormationStack*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout in minutes - optional **

## Environment
<a name="deploy.action.cfn.environment"></a>

(*DeployCloudFormationStack*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="deploy.action.cfn.environment.name"></a>

(*DeployCloudFormationStack*/Environment/**Name**)

(Required if [Environment](#deploy.action.cfn.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="deploy.action.cfn.environment.connections"></a>

(*DeployCloudFormationStack*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="deploy.action.cfn.environment.connections.name"></a>

(*DeployCloudFormationStack*/Environment/Connections/**Name**)

(Required if [Connections](#deploy.action.cfn.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="deploy.action.cfn.environment.connections.role"></a>

(*DeployCloudFormationStack*/Environment/Connections/**Role**)

(Required if [Connections](#deploy.action.cfn.environment.connections) is included)

Specify the name of the IAM role that the **Deploy CloudFormation stack** action uses to access AWS and the CloudFormation service. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.
**Note**  
The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```
+ The following custom trust policy:

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Inputs
<a name="deploy.action.cfn.inputs"></a>

(*DeployCloudFormationStack*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the `DeployCloudFormationStack` needs during a workflow run.

**Note**  
A maximum of four inputs (one source and three artifacts) are allowed per **Deploy CloudFormation stack** action.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see [Example: Referencing files in multiple artifacts](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file).

Corresponding UI: **Inputs** tab

## Sources
<a name="deploy.action.cfn.inputs.sources"></a>

(*DeployCloudFormationStack*/Inputs/**Sources**)

(Required if your CloudFormation or AWS SAM template is stored in a source repository)

If your CloudFormation or AWS SAM template is stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your CloudFormation or AWS SAM template is not contained within a source repository, it must reside in an artifact generated by another action, or in an Amazon S3 bucket.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="deploy.action.cfn.inputs.artifacts"></a>

(*DeployCloudFormationStack*/Inputs/**Artifacts**)

(Required if your CloudFormation or AWS SAM template is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the CloudFormation or AWS SAM template that you want to deploy is contained in an artifact generated by a previous action, specify that artifact here. If your CloudFormation template is not contained within an artifact, it must reside in your source repository or in an Amazon S3 bucket.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Configuration
<a name="deploy.action.cfn.configuration"></a>

(*DeployCloudFormationStack*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## name
<a name="deploy.action.cfn.stackname"></a>

(*DeployCloudFormationStack*/Configuration/**name**)

(Required)

Specify a name for the CloudFormation stack that the **Deploy CloudFormation stack** action creates or updates.

Corresponding UI: Configuration tab/**Stack name**

## region
<a name="deploy.action.cfn.stackregion"></a>

(*DeployCloudFormationStack*/Configuration/**region**)

(Required)

Specify the AWS Region into which the stack will be deployed. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes).

Corresponding UI: Configuration tab/**Stack region**

## template
<a name="deploy.action.cfn.templatepath"></a>

(*DeployCloudFormationStack*/Configuration/**template**)

(Required)

Specify the name and path to your CloudFormation or AWS SAM template file. The template can be in JSON or YAML format, and can reside in a source repository, an artifact from a previous action, or an Amazon S3 bucket. If the template file is in a source repository or artifact, the path is relative to the source or artifact root. If the template is in an Amazon S3 bucket, the path is the template's **Object URL** value.

Examples:

`./MyFolder/MyTemplate.json`

`MyFolder/MyTemplate.yml`

`https://MyBucket.s3.us-west-2.amazonaws.com/MyTemplate.yml`

**Note**  
You may need to add a prefix to the template's file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Configuration tab/**Template**

## role-arn
<a name="deploy.action.cfn.stackrolearn"></a>

(*DeployCloudFormationStack*/Configuration/**role-arn**)

(Required)

Specify the Amazon Resource Name (ARN) of the stack role. CloudFormation uses this role to access and modify resources in your stack. For example: `arn:aws:iam::123456789012:role/StackRole`.

Make sure the stack role includes:
+ One or more permissions policies. The policies depend on the resources you have in your stack. For example, if your stack includes an AWS Lambda function, you need to add permissions that grant access to Lambda. If you followed the tutorial described in [Tutorial: Deploy a serverless application](deploy-tut-lambda.md), it includes a procedure titled, [To create a stack role](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles-stack) that lists the permissions that the stack role needs if you're deploying a typical serverless application stack.
**Warning**  
Limit the permissions to those required by the CloudFormation service to access resources in your stack. Using a role with broader permissions might pose a security risk.
+ The following trust policy:

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Sid": "",
              "Effect": "Allow",
              "Principal": {
                  "Service": "cloudformation.amazonaws.com"
              },
              "Action": "sts:AssumeRole"
          }
      ]
  }
  ```

------

Optionally, associate this role with your account connection. To learn more about associating an IAM role with an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md). If you do not associate the stack role with the account connection, then the stack role will not appear in the **Stack role** drop-down list in the visual editor; however, the role ARN can still be specified in the `role-arn` field using the YAML editor.

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: Configuration tab/**Stack role - optional**

## capabilities
<a name="deploy.action.cfn.capabilities"></a>

(*DeployCloudFormationStack*/Configuration/**capabilities**)

(Required)

Specify a list of IAM capabilities that are required to allow CloudFormation to create certain stacks. In most cases, you can leave `capabilities` with the default value of `CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND`.

If you see `##[error] requires capabilities: [capability-name]` in your **Deploy CloudFormation stack** action's logs, see [How do I fix IAM capabilities errors?](troubleshooting-workflows.md#troubleshooting-workflows-capabilities) for information about how to fix the problem.

For more information about IAM capabilities, see [Acknowledging IAM resources in CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities) in the *IAM User Guide*.

Corresponding UI: Configuration tab/Advanced/**Capabilities**

## parameter-overrides
<a name="deploy.action.cfn.parameter.overrides"></a>

(*DeployCloudFormationStack*/Configuration/**parameter-overrides**)

(Optional)

Specify parameters in your CloudFormation or AWS SAM template that don't have default values, or for which you want to specify non-default values. For more information about parameters, see [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) in the * AWS CloudFormation User Guide*.

The `parameter-overrides` property accepts:
+ A JSON file containing the parameters and values.
+ A comma-separate list of parameters and values.

**To specify a JSON file**

1. Make sure the JSON file uses one of the following syntaxes:

   ```
   {
     "Parameters": {
       "Param1": "Value1",
       "Param2": "Value2",
       ...
     }
   }
   ```

   Or...

   ```
   [
     {
        "ParameterKey": "Param1",
        "ParameterValue": "Value1"
     },
     ...
   ]
   ```

   (There are other syntaxes, but they are not supported by CodeCatalyst at the time of writing.) For more information about specifying CloudFormation parameters in a JSON file, see [Supported JSON syntax](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/deploy/index.html#supported-json-syntax) in the *AWS CLI Command Reference*.

1. Specify the path to the JSON file using one of the following formats:
   + If your JSON file resides in an output artifact from a previous action, use:

     `file:///artifacts/current-action-name/output-artifact-name/path-to-json-file`

     See **Example 1** for details.
   + If your JSON file resides in your source repository, use:

     `file:///sources/WorkflowSource/path-to-json-file`

     See **Example 2** for details.

     **Example 1** – The JSON file resides in an output artifact

     ```
     ##My workflow YAML
     ...
     Actions:
       MyBuildAction:
         Identifier: aws/build@v1
         Outputs:
           Artifacts:
             - Name: ParamArtifact
               Files:
                 - params.json
         Configuration:
         ...
       MyDeployCFNStackAction:
         Identifier: aws/cfn-deploy@v1
         Configuration:
           parameter-overrides: file:///artifacts/MyDeployCFNStackAction/ParamArtifact/params.json
     ```

     **Example 2** – The JSON file resides in your source repository, in a folder called `my/folder`

     ```
     ##My workflow YAML
     ...
     Actions:
       MyDeployCloudFormationStack:
         Identifier: aws/cfn-deploy@v1
         Inputs:
           Sources:
             - WorkflowSource
         Configuration:
           parameter-overrides: file:///sources/WorkflowSource/my/folder/params.json
     ```

**To use a comma-separate list of parameters**
+ Add parameter name-value pairs in the `parameter-overrides` property using the following format:

  `param-1=value-1,param-2=value-2`

  For example, assuming the following CloudFormation template:

  ```
  ##My CloudFormation template
  
  Description: My CloudFormation template
  
  Parameters:
    InstanceType:
      Description: Defines the Amazon EC2 compute for the production server.
      Type: String
      Default: t2.micro
      AllowedValues:
        - t2.micro
        - t2.small
        - t3.medium
      
  Resources:
  ...
  ```

  ...you might set the `parameter-overrides` property as follows:

  ```
  ##My workflow YAML
  ...
  Actions:
  ...
    DeployCloudFormationStack:
      Identifier: aws/cfn-deploy@v1
      Configuration:
        parameter-overrides: InstanceType=t3.medium,UseVPC=true
  ```
**Note**  
You can specify a parameter name without a corresponding value using `undefined` as the value. For example:  
`parameter-overrides: MyParameter=undefined`  
 The effect is that during a stack update, CloudFormation uses the existing parameter value for the given parameter name.

Corresponding UI:
+ Configuration tab/Advanced/**Parameter overrides**
+ Configuration tab/Advanced/Parameter overrides/**Specify overrides using a file**
+ Configuration tab/Advanced/Parameter overrides/**Specify overrides using a value set**

## no-execute-changeset
<a name="deploy.action.cfn.noexecutechangeset"></a>

(*DeployCloudFormationStack*/Configuration/**no-execute-changeset**)

(Optional)

Specify whether you want CodeCatalyst to create the CloudFormation change set and then stop before running it. This gives you the opportunity to review the change set in the CloudFormation console. If you determine that the change set looks good, disable this option and then re-run the workflow so that CodeCatalyst can create and run the change set without stopping. The default is to create and run the change set without stopping. For more information, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*. For more information about viewing change sets, see [Viewing a change set](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-view.html) in the *AWS CloudFormation User Guide*.

Corresponding UI: Configuration tab/Advanced/**No execute change set**

## fail-on-empty-changeset
<a name="deploy.action.cfn.failonemptychangeset"></a>

(*DeployCloudFormationStack*/Configuration/**fail-on-empty-changeset**)

(Optional)

Specify whether you want CodeCatalyst to fail the **Deploy CloudFormation stack** action if the CloudFormation change set is empty. (If a change set is empty, it means there were no changes made to the stack during the latest deployment.) The default is to allow the action to proceed if the change set is empty, and to return an `UPDATE_COMPLETE` message even though the stack was not updated.

For more information about this setting, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*. For more information about change sets, see [Updating stacks using change sets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) in the *AWS CloudFormation User Guide*.

Corresponding UI: Configuration tab/Advanced/**Fail on empty changeset**

## disable-rollback
<a name="deploy.action.cfn.disablerollback"></a>

(*DeployCloudFormationStack*/Configuration/**disable-rollback**)

(Optional)

Specify whether you want CodeCatalyst to roll back the stack deployment if it fails. The rollback returns the stack to the last known stable state. The default is to enable rollbacks. For more information about this setting, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*.

For more information about how the **Deploy CloudFormation stack** action handles rollbacks, see [Configuring rollbacks](deploy-consumption-enable-alarms.md).

For more information about rolling back a stack, see [Stack failure options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html) in the *AWS CloudFormation User Guide*.

Corresponding UI: Configuration tab/Advanced/**Disable rollback**

## termination-protection
<a name="deploy.action.cfn.terminationprotection"></a>

(*DeployCloudFormationStack*/Configuration/**termination-protection**)

(Optional)

Specify whether you want the **Deploy CloudFormation stack** to add termination protection to the stack that it is deploying. If a user attempts to delete a stack with termination protection enabled, the deletion fails and the stack, including its status, remains unchanged. The default is to disable termination protection. For more information, see [Protecting a stack from being deleted](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html) in the *AWS CloudFormation User Guide*.

Corresponding UI: Configuration tab/Advanced/**Termination protection**

## timeout-in-minutes
<a name="deploy.action.cfn.timeoutinminutes"></a>

(*DeployCloudFormationStack*/Configuration/**timeout-in-minutes**)

(Optional)

Specify the amount of time, in minutes, that CloudFormation should allot before timing out stack creation operations and setting the stack status to `CREATE_FAILED`. If CloudFormation can't create the entire stack in the time allotted, it fails the stack creation due to timeout and rolls back the stack.

By default, there is no timeout for stack creation. However, individual resources may have their own timeouts based on the nature of the service they implement. For example, if an individual resource in your stack times out, stack creation also times out even if the timeout you specified for stack creation hasn't yet been reached.

Corresponding UI: Configuration tab/Advanced/**CloudFormation timeout**

## notification-arns
<a name="deploy.action.cfn.notificationarns"></a>

(*DeployCloudFormationStack*/Configuration/**notification-arns**)

(Optional)

Specify the ARN of an Amazon SNS topic that you want CodeCatalyst to send notification messages to. For example, `arn:aws:sns:us-east-1:111222333:MyTopic`. When the **Deploy CloudFormation stack** action runs, CodeCatalyst coordinates with CloudFormation to send one notification per CloudFormation event that occurs during the stack creation or update process. (The events are visible in the CloudFormation console's **Events** tab for the stack.) You can specify up to five topics. For more information, see [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html).

Corresponding UI: Configuration tab/Advanced/**Notification ARNs**

## monitor-alarm-arns
<a name="deploy.action.cfn.monitoralarmarns"></a>

(*DeployCloudFormationStack*/Configuration/**monitor-alarm-arns**)

(Optional)

Specify the Amazon Resource Name (ARN) of an Amazon CloudWatch alarm to use as a rollback trigger. For example, `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`. You can have a maximum of five rollback triggers.

**Note**  
If you specify a CloudWatch alarm ARN, you'll also need to configure additional permissions to enable the action to access CloudWatch. For more information, see [Configuring rollbacks](deploy-consumption-enable-alarms.md).

Corresponding UI: Configuration tab/Advanced/**Monitor alarm ARNs **

## monitor-timeout-in-minutes
<a name="deploy.action.cfn.monitortimeinminutes"></a>

(*DeployCloudFormationStack*/Configuration/**monitor-timeout-in-minutes**)

(Optional)

Specify an amount of time, from 0 to 180 minutes, during which CloudFormation monitors the specified alarms. Monitoring begins *after* all the stack resources have been deployed. If the alarm occurs within the specified monitoring time, then the deployment fails, and CloudFormation rolls back the entire stack operation.

Default: 0. CloudFormation only monitors alarms while the stack resources are being deployed, not after.

Corresponding UI: Configuration tab/Advanced/**Monitoring time**

## tags
<a name="deploy.action.cfn.tags"></a>

(*DeployCloudFormationStack*/Configuration/**tags**)

(Optional)

Specify tags to attach to your CloudFormation stack. Tags are arbitrary key-value pairs that you can use to identify your stack for purposes such as cost allocation. For more information about what tags are and how they can be used, see [Tagging your resources](https://docs.aws.amazon.com/) in the *Amazon EC2 User Guide*. For more information about tagging in CloudFormation, see [Setting CloudFormation stack options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-add-tags.html) in the *AWS CloudFormation User Guide*.

A key can have alphanumeric characters or spaces, and can have up to 127 characters. A value can have alphanumeric characters or spaces, and can have up to 255 characters.

You can add up to 50 unique tags for each stack.

Corresponding UI: Configuration tab/Advanced/**Tags**

# Deploying an AWS CDK app with a workflow
<a name="cdk-dep-action"></a>

This section describes how to deploy an AWS Cloud Development Kit (AWS CDK) app into your AWS account using a workflow. To accomplish this, you must add the **AWS CDK deploy** action to your workflow. The **AWS CDK deploy** action synthesizes and deploys your AWS Cloud Development Kit (AWS CDK) app into AWS. If your app already exists in AWS, the action updates it if necessary. 

For general information about writing apps using the AWS CDK, see [What is the AWS CDK?](https://docs.aws.amazon.com/cdk/v2/guide/home.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

**Topics**
+ [

## When to use the 'AWS CDK deploy' action
](#cdk-dep-action-when-to-use)
+ [

## How the 'AWS CDK deploy' action works
](#cdk-dep-action-how-it-works)
+ [

## CDK CLI versions used by the 'AWS CDK deploy' action
](#cdk-dep-action-cdk-version)
+ [

## Runtime image used by the 'AWS CDK deploy' action
](#cdk-dep-action-runtime)
+ [

## How many stacks can the action deploy?
](#cdk-dep-action-how-many-stacks)
+ [

# Example: Deploying an AWS CDK app
](cdk-dep-action-example-workflow.md)
+ [

# Adding the 'AWS CDK deploy' action
](cdk-dep-action-add.md)
+ [

# 'AWS CDK deploy' variables
](cdk-dep-action-variables.md)
+ [

# 'AWS CDK deploy' action YAML
](cdk-dep-action-ref.md)

## When to use the 'AWS CDK deploy' action
<a name="cdk-dep-action-when-to-use"></a>

Use this action if you have developed an app using the AWS CDK, and you now want to deploy it automatically as part of automated continuous integration and delivery (CI/CD) workflow. For example, you might want to deploy your AWS CDK app automatically whenever someone merges a pull request related to your AWS CDK app source. 

## How the 'AWS CDK deploy' action works
<a name="cdk-dep-action-how-it-works"></a>

The **AWS CDK deploy** works as follows:

1. At runtime, if you specified version 1.0.12 or earlier of the action, the action downloads the latest CDK CLI (also called the AWS CDK Tookit) to the CodeCatalyst [runtime environment image](#cdk-dep-action-runtime).

   If you specified version 1.0.13 or later, the action comes bundled with a [specific version](#cdk-dep-action-cdk-version) of the CDK CLI, so no download occurs.

1. The action uses the CDK CLI to run the `cdk deploy` command. This command synthesizes and deploys your AWS CDK app into AWS. For more information about this command, see the [AWS CDK Toolkit (cdk command)](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) topic in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

## CDK CLI versions used by the 'AWS CDK deploy' action
<a name="cdk-dep-action-cdk-version"></a>

The following table shows which version of the CDK CLI is used by default by different versions of the **AWS CDK deploy** action.

**Note**  
You might be able to override the default. For more information, see [CdkCliVersion](cdk-dep-action-ref.md#cdk.dep.cdk.cli.version) in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md).


| 'AWS CDK deploy' action version | AWS CDK CLI version | 
| --- | --- | 
|  1.0.0 – 1.0.12  |  latest  | 
|  1.0.13 or later  |  2.99.1  | 

## Runtime image used by the 'AWS CDK deploy' action
<a name="cdk-dep-action-runtime"></a>

The following table shows the runtime environment images that CodeCatalyst uses to run different versions of the **AWS CDK deploy** action. The images include different sets of preinstalled tooling. For more information, see [Active images](build-images.md#build-curated-images).

**Note**  
We recommend upgrading your **AWS CDK deploy** action to version 2.x to take advantage of the latest tooling available on the March 2024 image. To upgrade the action, set its `Identifier` property to `aws/cdk-deploy@v2` in your workflow definition file. For more information, see ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). 


| 'AWS CDK deploy' action version | Runtime environment images | 
| --- | --- | 
|  1.x  |  November 2022 images  | 
|  2.x  |  March 2024 images  | 

## How many stacks can the action deploy?
<a name="cdk-dep-action-how-many-stacks"></a>

The **AWS CDK deploy** can deploy a single stack only. If your AWS CDK app consists of multiple stacks, you must create a parent stack with nested stacks, and deploy the parent using this action.

# Example: Deploying an AWS CDK app
<a name="cdk-dep-action-example-workflow"></a>

The following example workflow includes the **AWS CDK deploy** action, along with the **AWS CDK bootstrap** action. The workflow consists of the following building blocks that run sequentially:
+ A **trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. This repository contains your AWS CDK app. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ An **AWS CDK bootstrap** action (`CDKBootstrap`) – On trigger, the action deploys the `CDKToolkit` bootstrap stack into AWS. If the `CDKToolkit` stack already exists in the environment, it will be upgraded if necessary; otherwise, nothing happens, and the action is marked as succeeded.
+ An **AWS CDK deploy** action (`AWS CDKDeploy`) – On completion of the **AWS CDK bootstrap** action, the **AWS CDK deploy** action synthesizes your AWS CDK app code into an CloudFormation template and deploys the stack defined in the template into AWS.

**Note**  
The following workflow example is for illustrative purposes, and will not work without additional configuration.

**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies required by the **AWS CDK bootstrap** and **AWS CDK deploy** actions. For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). For more information about the permissions and trust policies required by the **AWS CDK bootstrap** and **AWS CDK deploy** actions, see the description of the `Role` property in the ['AWS CDK bootstrap' action YAML](cdk-boot-action-ref.md) and ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md).

```
Name: codecatalyst-cdk-deploy-workflow
SchemaVersion: 1.0

Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  CDKBootstrap:
    Identifier: aws/cdk-bootstrap@v2
    Inputs:
      Sources:
        - WorkflowSource
    Environment:
      Name: codecatalyst-cdk-deploy-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-cdk-bootstrap-role
    Configuration:
      Region: us-west-2
        
  CDKDeploy:
    Identifier: aws/cdk-deploy@v2
    DependsOn: 
      - CDKBootstrap
    Environment:
      Name: codecatalyst-cdk-deploy-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-cdk-deploy-role
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      StackName: my-app-stack
      Region: us-west-2
```

# Adding the 'AWS CDK deploy' action
<a name="cdk-dep-action-add"></a>

 Use the following instructions to add the **AWS CDK deploy** action to your workflow. 

**Before you begin**

Before you can add the **AWS CDK deploy** action to your workflow, complete the following tasks:

1. **Have an AWS CDK app ready**. You can write your AWS CDK app using AWS CDK v1 or v2, in any programming language supported by the AWS CDK. Make sure your AWS CDK app files are available in:
   + A CodeCatalyst [source repository](source.md), or 
   + A CodeCatalyst [output artifact](workflows-working-artifacts.md) generated by another workflow action

1. **Bootstrap your AWS environment**. To bootstrap, you can:
   + Use one of the methods described in [How to bootstrap](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-howto) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.
   + Use the **AWS CDK bootstrap** action. You can add this action in the same workflow as your **AWS CDK deploy**, or in a different one. Just make sure the bootstrap action runs at least once prior to running the **AWS CDK deploy** action so that the necessary resources are in place. For more information about the**AWS CDK bootstrap** action, see [Bootstrapping an AWS CDK app with a workflow](cdk-boot-action.md).

     For more information about bootstrapping, see [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

------
#### [ Visual ]

**To add the 'AWS CDK deploy' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS CDK deploy** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **AWS CDK deploy**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.
**Note**  
If your **AWS CDK deploy** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error.

------
#### [ YAML ]

**To add the 'AWS CDK deploy' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS CDK deploy** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **AWS CDK deploy**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.
**Note**  
If your **AWS CDK deploy** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error.

------

# 'AWS CDK deploy' variables
<a name="cdk-dep-action-variables"></a>

The **AWS CDK deploy** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  stack-id  |  The Amazon Resource Name (ARN) of the AWS CDK application stack that was deployed to during the workflow run. Example: `arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cdk-app-stack/6aad4380-100a-11ec-a10a-03b8a84d40df`  | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:CloudFormation`.  | 
|  region  |  The region code of the AWS Region that was deployed to during the workflow run. Example: `us-west-2`  | 
|  SKIP-DEPLOYMENT  |  A value of `true` indicates that deployment of your AWS CDK application stack was skipped during the workflow run. A stack deployment will be skipped if there is no change in the stack since the last deployment. This variable is only produced if its value is `true`. Hardcoded to `true`.  | 
|  *CloudFormation variables*  |  In addition to generating the variables listed previously, the **AWS CDK deploy** action also exposes *CloudFormation* output variables as *workflow* variables for use in subsequent workflow actions. By default, the action only exposes the first four (or fewer) CloudFormation variables that it finds. To determine which ones are exposed, run the **AWS CDK deploy** action once, and then look in the **Variables** tab of the run details page. If the variables listed on the **Variables** tab are not what you want, you can configure different ones using the `CfnOutputVariables` YAML property. For more information, see the [CfnOutputVariables](cdk-dep-action-ref.md#cdk.dep.cfn.out) property description in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md).  | 

# 'AWS CDK deploy' action YAML
<a name="cdk-dep-action-ref"></a>

The following is the YAML definition of the **AWS CDK deploy** action. To learn how to use this action, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  CDKDeploy\$1nn: 
    Identifier: aws/cdk-deploy@v2
    DependsOn:
      - CDKBootstrap
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - artifact-name
    Outputs:
      Artifacts:
        - Name: cdk_artifact
          Files: 
            - "cdk.out/**/*"
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Configuration:
      StackName: my-cdk-stack
      Region: us-west-2
      Tags: '{"key1": "value1", "key2": "value2"}'
      Context: '{"key1": "value1", "key2": "value2"}'
      CdkCliVersion: version
      CdkRootPath: directory-containing-cdk.json-file
      CfnOutputVariables: '["CnfOutputKey1","CfnOutputKey2","CfnOutputKey3"]'
      CloudAssemblyRootPath: path-to-cdk.out
```

## CDKDeploy
<a name="cdk.dep.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `CDKDeploy_nn`.

Corresponding UI: Configuration tab/**Action name**

## Identifier
<a name="cdk.dep.identifier"></a>

(*CDKDeploy*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

**Note**  
Specifying `aws/cdk-deploy@v2` causes the action to run on the [March 2024 image](build-images.md#build.default-image) which includes newer tooling such as Node.js 18. Specifying `aws/cdk-deploy@v1` causes the action to run on the [November 2022 image](build-images.md#build.previous-image) which includes older tooling such as Node.js 16.

Default: `aws/cdk-deploy@v2`.

Corresponding UI: Workflow diagram/CDKDeploy\$1nn/**aws/cdk-deploy@v2** label

## DependsOn
<a name="cdk.dep.dependson"></a>

(*CDKDeploy*/**DependsOn**)

(Optional)

Specify an action or action group that must run successfully in order for the **AWS CDK deploy** action to run. We recommend specifying the **AWS CDK bootstrap** action in the `DependsOn` property, like this:

```
CDKDeploy:
  Identifier: aws/cdk-deploy@v2
  DependsOn:
    - CDKBootstrap
```

**Note**  
[Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) is a mandatory prerequisite for deploying an AWS CDK app. If you do not include the **AWS CDK Bootstrap** action in your workflow, then you must find another way to deploy the AWS CDK bootstrap stack before running your **AWS CDK deploy** action. For more information, see [Adding the 'AWS CDK deploy' action](cdk-dep-action-add.md) in [Deploying an AWS CDK app with a workflow](cdk-dep-action.md).

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="cdk.dep.computename"></a>

(*CDKDeploy*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="cdk.dep.computetype"></a>

(*CDKDeploy*/Compute/**Type**)

(Required if [Compute](#cdk.dep.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="cdk.dep.computefleet"></a>

(*CDKDeploy*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="cdk.dep.timeout"></a>

(*CDKDeploy*/**Timeout**)

(Required)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Inputs
<a name="cdk.dep.inputs"></a>

(*CDKDeploy*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the `CDKDeploy` needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed for each **AWS CDK deploy** action.

Corresponding UI: **Inputs** tab

## Sources
<a name="cdk.dep.inputs.sources"></a>

(*CDKDeploy*/Inputs/**Sources**)

(Required if the AWS CDK app you want to deploy is stored in a source repository)

If your AWS CDK app is stored in a source repository, specify the label of that source repository. The **AWS CDK deploy** action synthesizes the app in this repository before starting the deployment process. Currently, the only supported label is `WorkflowSource`.

If your AWS CDK app is not contained within a source repository, it must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="cdk.dep.inputs.artifacts"></a>

(*CDKDeploy*/Inputs/**Artifacts**)

(Required if the AWS CDK app you want to deploy is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If your AWS CDK app is contained in an artifact generated by a previous action, specify that artifact here. The **AWS CDK deploy** action synthesizes the app in the specified artifact into a CloudFormation template before starting the deployment process. If your AWS CDK app is not contained within an artifact, it must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Inputs tab/**Artifacts - optional**

## Outputs
<a name="cdk.dep.outputs"></a>

(*CDKDeploy*/**Outputs**)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts - output
<a name="cdk.dep.outputs.artifacts"></a>

(*CDKDeploy*/Outputs/**Artifacts**

(Optional)

Specify the artifacts generated by the action. You can reference these artifacts as input in other actions.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/**Artifacts**

## Name
<a name="cdk.dep.outputs.artifacts.name"></a>

(*CDKDeploy*/Outputs/Artifacts/**Name**)

(Required if [Artifacts - output](#cdk.dep.outputs.artifacts) is included)

Specify the name of the artifact that will contain the CloudFormation template that is synthesized by the **AWS CDK deploy** action at runtime. The default value is `cdk_artifact`. If you do not specify an artifact, then the action synthesizes the template but won't save it in an artifact. Consider saving the synthesized template in an artifact to preserve a record of it for testing or troubleshooting purposes.

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Build artifact name**

## Files
<a name="cdk.dep.outputs.artifacts.files"></a>

(*CDKDeploy*/Outputs/Artifacts/**Files**)

(Required if [Artifacts - output](#cdk.dep.outputs.artifacts) is included)

Specify the files to include in the artifact. You must specify `"cdk.out/**/*"` to include your AWS CDK app's synthesized CloudFormation template.

**Note**  
`cdk.out` is the default directory into which synthesized files are saved. If you specified an output directory other than `cdk.out` in your `cdk.json` file, specify that directory here instead of `cdk.out`.

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Files produced by build**

## Environment
<a name="cdk.dep.environment"></a>

(*CDKDeploy*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="cdk.dep.environment.name"></a>

(*CDKDeploy*/Environment/**Name**)

(Required if [Environment](#cdk.dep.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="cdk.dep.environment.connections"></a>

(*CDKDeploy*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="cdk.dep.environment.connections.name"></a>

(*CDKDeploy*/Environment/Connections/**Name**)

(Required if [Connections](#cdk.dep.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="cdk.dep.environment.connections.role"></a>

(*CDKDeploy*/Environment/Connections/**Role**)

(Required if [Connections](#cdk.dep.environment.connections) is included)

Specify the name of the account connection.

Specify the name of the IAM role that the **AWS CDK deploy** action uses to access AWS and deploy the AWS CDK application stack. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Sid": "VisualEditor0",
              "Effect": "Allow",
              "Action": [
                  "cloudformation:DescribeStackEvents",
                  "cloudformation:DescribeChangeSet",
                  "cloudformation:DescribeStacks",
                  "cloudformation:ListStackResources"
              ],
              "Resource": "*"
          },
          {
              "Sid": "VisualEditor1",
              "Effect": "Allow",
              "Action": "sts:AssumeRole",
              "Resource": "arn:aws:iam::111122223333:role/cdk-*"
          }
      ]
  }
  ```

------
+ The following custom trust policy:

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Configuration
<a name="cdk.dep.configuration"></a>

(*CDKDeploy*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## StackName
<a name="cdk.dep.stack.name"></a>

(*CDKDeploy*/Configuration/**StackName**)

(Required)

The name of your AWS CDK app stack, as it appears in the entrypoint file in your AWS CDK app's `bin` directory. The following example shows the contents of a TypeScript entrypoint file, with the stack name highlighted in *red italics*. If your entrypoint file is in a different language, it will look similar.

```
import * as cdk from 'aws-cdk-lib';
import { CdkWorksopTypescriptStack } from '../lib/cdk_workshop_typescript-stack';

const app = new cdk.App();
new CdkWorkshopTypescriptStack(app, 'CdkWorkshopTypescriptStack');
```

You can only specify one stack.

**Tip**  
If you have multiple stacks, you can create a parent stack with nested stacks. You can then specify the parent stack in this action to deploy all stacks.

Corresponding UI: Configuration tab/**Stack name**

## Region
<a name="cdk.dep.region"></a>

(*CDKDeploy*/Configuration/**Region**)

(Optional)

Specify the AWS Region into which the AWS CDK application stack will be deployed. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes).

If you do not specify a Region, the **AWS CDK deploy** action deploys into the Region specified in your AWS CDK code. For more information, see [Environments](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

Corresponding UI: Configuration tab/**Region**

## Tags
<a name="cdk.dep.tags"></a>

(*CDKDeploy*/Configuration/**Tags**)

(Optional)

Specify tags that you want to apply to the AWS resources in the AWS CDK application stack. Tags are applied to the stack itself as well as to individual resources in the stack. For more information about tagging, see [Tagging](https://docs.aws.amazon.com/cdk/v2/guide/tagging.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

Corresponding UI: Configuration tab/Advanced - optional/**Tags**

## Context
<a name="cdk.dep.context"></a>

(*CDKDeploy*/Configuration/**Context**)

(Optional)

Specify contexts, in the form of key-value pairs, to associate with the AWS CDK application stack. For more information about contexts, see [Runtime contexts](https://docs.aws.amazon.com/cdk/v2/guide/context.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

Corresponding UI: Configuration tab/Advanced - optional/**Context**

## CdkCliVersion
<a name="cdk.dep.cdk.cli.version"></a>

(*CDKDeploy*/Configuration/**CdkCliVersion**)

(Optional)

This property is available with version 1.0.13 or later of the **AWS CDK deploy** action, and version 1.0.8 or later of the **AWS CDK bootstrap** action.

Specify one of the following:
+ The full version of the AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI) (also called the AWS CDK Toolkit) that you want this action to use. Example: `2.102.1`. Consider specifying a full version to ensure consistency and stability when building and deploying your application.

  Or
+ `latest`. Consider specifying `latest` to take advantage of the latest features and fixes of the CDK CLI.

The action will download the specified version (or the latest version) of the AWS CDK CLI to the CodeCatalyst [build image](build-images.md), and then use this version to run the commands necessary to deploy your CDK application or bootstrap your AWS environment.

For a list of supported CDK CLI versions you can use, see [AWS CDK Versions](https://docs.aws.amazon.com/cdk/api/versions.html).

If you omit this property, the action uses a default AWS CDK CLI version described in one of the following topics:
+ [CDK CLI versions used by the 'AWS CDK deploy' action](cdk-dep-action.md#cdk-dep-action-cdk-version) 
+ [CDK CLI versions used by the "AWS CDK bootstrap" action](cdk-boot-action.md#cdk-boot-action-cdk-version)

Corresponding UI: Configuration tab/**AWS CDK CLI version**

## CdkRootPath
<a name="cdk.dep.cdk.root.path"></a>

(*CDKDeploy*/Configuration/**CdkRootPath**)

(Optional)

The path to the directory that contains your AWS CDK project's `cdk.json` file. The **AWS CDK deploy** action runs from this folder, and any outputs created by the action will be added to this directory. If unspecified, the **AWS CDK deploy** action assumes that the `cdk.json` file is in the root of your AWS CDK project.

Corresponding UI: Configuration tab/**Directory where the cdk.json resides**

## CfnOutputVariables
<a name="cdk.dep.cfn.out"></a>

(*CDKDeploy*/Configuration/**CfnOutputVariables**)

(Optional)

Specify which `CfnOutput` constructs in your AWS CDK application code you want to expose as workflow output variables. You can then reference the workflow output variables in subsequent actions in your workflow. For more information about variables in CodeCatalyst, see [Using variables in workflows](workflows-working-with-variables.md).

For example, if your AWS CDK application code looks like this:

```
import { Duration, Stack, StackProps, CfnOutput, RemovalPolicy} from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
export class HelloCdkStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
      removalPolicy: RemovalPolicy.DESTROY,
    });
    new CfnOutput(this, 'bucketName', {
      value: bucket.bucketName,
      description: 'The name of the s3 bucket',
      exportName: 'amzn-s3-demo-bucket',
    });
    const table = new dynamodb.Table(this, 'todos-table', {
      partitionKey: {name: 'todoId', type: dynamodb.AttributeType.NUMBER},
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: RemovalPolicy.DESTROY,
    })
    new CfnOutput(this, 'tableName', {
      value: table.tableName,
      description: 'The name of the dynamodb table',
      exportName: 'myDynamoDbTable',
    });
    ...
  }
}
```

...and your `CfnOutputVariables` property looks like this:

```
Configuration:
  ...
  CfnOutputVariables: '["bucketName","tableName"]'
```

...then the action generates the following workflow output variables:


| Key | Value | 
| --- | --- | 
|  bucketName  |  `bucket.bucketName`  | 
|  tableName  |  `table.tableName`  | 

You can then reference the `bucketName` and `tableName` variables in subsequent actions. To learn how to reference workflow output variables in subsequent actions, see [Referencing a predefined variable](workflows-working-with-variables-reference-output-vars.md).

If you do not specify any `CfnOutput` constructs in the `CfnOutputVariables` property, then the action exposes the first four (or fewer) CloudFormation output variables it finds as workflow output variables. For more information, see ['AWS CDK deploy' variables](cdk-dep-action-variables.md).

**Tip**  
To obtain a list of all the CloudFormation output variables the action produces, run the workflow containing the **AWS CDK deploy** action once, and then look in the action's **Logs** tab. The logs contain a list of all the CloudFormation output variables associated with your AWS CDK app. Once you know what all the CloudFormation variables are, you can specify which ones you want to convert to workflow output variables using the `CfnOutputVariables` property.

For more information about CloudFormation output variables, see the documentation for the `CfnOutput` construct, available at [class CfnOutput (construct)](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutput.html) in the *AWS Cloud Development Kit (AWS CDK) API Reference*.

Corresponding UI: Configuration tab/**CloudFormation output variables**

## CloudAssemblyRootPath
<a name="cdk.dep.cloud"></a>

(*CDKDeploy*/Configuration/**CloudAssemblyRootPath**)

(Optional)

If you have already synthesized your AWS CDK app's stack into a cloud assembly (using the `cdk synth` operation), specify the root path of the cloud assembly directory (`cdk.out`). The CloudFormation template located in the specified cloud assembly directory will be deployed by the **AWS CDK deploy** action into your AWS account using the `cdk deploy --app` command. When the `--app` option is present, the `cdk synth` operation does not occur.

If you do not specify a cloud assembly directory, then the **AWS CDK deploy** action will run the `cdk deploy` command without the `--app` option. Without the `--app` option, the `cdk deploy` operation will both synthesize (`cdk synth`) and deploy your AWS CDK app into your AWS account. 

**Why would I specify an existing, synthesized cloud assembly when the "AWS CDK deploy" action can do the synthesis at run time?**

You might want to specify an existing, synthesized cloud assembly to:
+ **Ensure that the exact same set of resources are deployed every time the "AWS CDK deploy" action runs**

  If you don't specify a cloud assembly, it's possible for the **AWS CDK deploy** action to synthesize and deploy different files depending on when it is run. For example, the **AWS CDK deploy** action might synthesize a cloud assembly with one set of dependencies during a testing stage, and another set of dependencies during a production stage (if those dependencies changed between stages). To guarantee exact parity between what is tested and what is deployed, we recommend synthesizing once and then using the **Path to cloud assembly directory** field (visual editor) or `CloudAssemblyRootPath` property (YAML editor) to specify the already-synthesized cloud assembly.
+ **Use non-standard package managers and tooling with the AWS CDK app**

  During a `synth` operation, the **AWS CDK deploy** action tries to run your app using standard tools such as npm or pip. If the action can't successfully run your app using those tools, the synthesis will not occur and the action will fail. To work around this issue, you can specify the exact commands needed to run your app successfully in the AWS CDK app's `cdk.json` file, and then synthesize your app using a method that does not involve the **AWS CDK deploy** action. After the cloud assembly has been generated, you can specify it in the **Path to cloud assembly directory** field (visual editor) or `CloudAssemblyRootPath` property (YAML editor) of the **AWS CDK deploy** action. 

For information about configuring the `cdk.json` file to include commands for installing and running your AWS CDK app, see [Specifying the app command](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-app-command).

For information about the `cdk deploy` and `cdk synth` commands, as well as the `--app` option, see [Deploying stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy), [Synthesizing stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-synth) and [Skipping synthesis](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-nosynth) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

For information about cloud assemblies, see [Cloud Assembly](https://docs.aws.amazon.com/cdk/api/v2/docs/cloud-assembly-schema-readme.html) in the *AWS Cloud Development Kit (AWS CDK) API Reference*.

Corresponding UI: Configuration tab/**Path to cloud assembly directory**

# Bootstrapping an AWS CDK app with a workflow
<a name="cdk-boot-action"></a>

This section describes how to bootstrap an AWS CDK application using a CodeCatalyst workflow. To accomplish this, you must add the **AWS CDK bootstrap** action to your workflow. The **AWS CDK bootstrap** action provisions a bootstrap stack in your AWS environment using the [modern template](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-template). If a bootstrap stack already exists, the action updates it if necessary. Having a bootstrap stack present in AWS is a prerequisite for deploying an AWS CDK app.

For more information about bootstrapping, see [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

**Topics**
+ [

## When to use the 'AWS CDK bootstrap' action
](#cdk-boot-action-when-to-use)
+ [

## How the 'AWS CDK bootstrap' action works
](#cdk-boot-action-how-it-works)
+ [

## CDK CLI versions used by the "AWS CDK bootstrap" action
](#cdk-boot-action-cdk-version)
+ [

## Runtime image used by the 'AWS CDK bootstrap' action
](#cdk-boot-action-runtime)
+ [

# Example: Bootstrapping an AWS CDK app
](cdk-boot-action-example-workflow.md)
+ [

# Adding the 'AWS CDK bootstrap' action
](cdk-boot-action-add.md)
+ [

# 'AWS CDK bootstrap' variables
](cdk-boot-action-variables.md)
+ [

# 'AWS CDK bootstrap' action YAML
](cdk-boot-action-ref.md)

## When to use the 'AWS CDK bootstrap' action
<a name="cdk-boot-action-when-to-use"></a>

Use this action if you have a workflow that deploys an AWS CDK app, and you want to deploy (and update, if needed) the bootstrap stack at the same time. In this case, you would add the **AWS CDK bootstrap** action to the same workflow as the one that deploys your AWS CDK app.

**Do not** use this action if either of the following applies:
+ You already deployed a bootstrap stack using another mechanism, and you want to keep it intact (no updates).
+ You want to use a [custom bootstrap template](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-customizing), which is not supported with the **AWS CDK bootstrap** action.

## How the 'AWS CDK bootstrap' action works
<a name="cdk-boot-action-how-it-works"></a>

The **AWS CDK bootstrap** works as follows:

1. At runtime, if you specified version 1.0.7 or earlier of the action, the action downloads the latest CDK CLI (also called the AWS CDK Tookit) to the CodeCatalyst [build image](build-images.md).

   If you specified version 1.0.8 or later, the action comes bundled with a [specific version](cdk-dep-action.md#cdk-dep-action-cdk-version) of the CDK CLI, so no download occurs.

1. The action uses the CDK CLI to run the `cdk bootstrap` command. This command performs the bootstrapping tasks described in the [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) topic in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*.

## CDK CLI versions used by the "AWS CDK bootstrap" action
<a name="cdk-boot-action-cdk-version"></a>

The following table shows which version of the CDK CLI is used by default by different versions of the **AWS CDK bootstrap** action.

**Note**  
You might be able to override the default. For more information, see [CdkCliVersion](cdk-boot-action-ref.md#cdk.boot.cdk.cli.version) in the ['AWS CDK bootstrap' action YAML](cdk-boot-action-ref.md).


| 'AWS CDK bootstrap' action version | AWS CDK CLI version | 
| --- | --- | 
|  1.0.0 – 1.0.7  |  latest  | 
|  1.0.8 or later  |  2.99.1  | 

## Runtime image used by the 'AWS CDK bootstrap' action
<a name="cdk-boot-action-runtime"></a>

The following table shows the runtime environment images that CodeCatalyst uses to run different versions of the **AWS CDK bootstrap** action. The images include different sets of preinstalled tooling. For more information, see [Active images](build-images.md#build-curated-images).

**Note**  
We recommend upgrading your **AWS CDK bootstrap** action to version 2.x to take advantage of the latest tooling available on the March 2024 image. To upgrade the action, set its `Identifier` property to `aws/cdk-bootstrap@v2` in your workflow definition file. For more information, see ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). 


| 'AWS CDK bootstrap' action version | Runtime environment images | 
| --- | --- | 
|  1.x  |  November 2022 images  | 
|  2.x  |  March 2024 images  | 

# Example: Bootstrapping an AWS CDK app
<a name="cdk-boot-action-example-workflow"></a>

Refer to the [Example: Deploying an AWS CDK app](cdk-dep-action-example-workflow.md) in the [Deploying an AWS CDK app with a workflow](cdk-dep-action.md) for a workflow that includes the **AWS CDK bootstrap** action.

# Adding the 'AWS CDK bootstrap' action
<a name="cdk-boot-action-add"></a>

 Use the following instructions to add the **AWS CDK bootstrap** action to your workflow. 

**Before you begin**

Before you can use the **AWS CDK bootstrap** action, make sure you have an AWS CDK app ready. The bootstrap action will synthesize the AWS CDK app before bootstrapping. You can write your app in any programming language supported by the AWS CDK.

Make sure your AWS CDK app files are available in:
+ A CodeCatalyst [source repository](source.md), or 
+ A CodeCatalyst [output artifact](workflows-working-artifacts.md) generated by another workflow action

------
#### [ Visual ]

**To add the 'AWS CDK bootstrap' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS CDK bootstrap** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **AWS CDK bootstrap**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs**, **Configuration**, and **Outputs** tabs, complete the fields according to your needs. For a description of each field, see the ['AWS CDK bootstrap' action YAML](cdk-boot-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.
**Note**  
If your **AWS CDK bootstrap** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error.

------
#### [ YAML ]

**To add the 'AWS CDK bootstrap' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS CDK bootstrap** action, and choose **\$1** to add it to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['AWS CDK bootstrap' action YAML](cdk-boot-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.
**Note**  
If your **AWS CDK bootstrap** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error.

------

# 'AWS CDK bootstrap' variables
<a name="cdk-boot-action-variables"></a>

The **AWS CDK bootstrap** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:CloudFormation`.  | 
|  region  |  The region code of the AWS Region that the AWS CDK bootstrap stack was deployed to during the workflow run. Example: `us-west-2`  | 
|  stack-id  |  The Amazon Resource Name (ARN) of the deployed AWS CDK bootstrap stack. Example: `arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cdk-bootstrap-stack/6aad4380-100a-11ec-a10a-03b8a84d40df`  | 
|  SKIP-DEPLOYMENT  |  A value of `true` indicates that deployment of your AWS CDK bootstrap stack was skipped during the workflow run. A stack deployment will be skipped if there is no change in the stack since the last deployment. This variable is only produced if its value is `true`. Hardcoded to `true`.  | 

# 'AWS CDK bootstrap' action YAML
<a name="cdk-boot-action-ref"></a>

The following is the YAML definition of the **AWS CDK bootstrap** action. To learn how to use this action, see [Bootstrapping an AWS CDK app with a workflow](cdk-boot-action.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.    
  CDKBootstrapAction\$1nn: 
    Identifier: aws/cdk-bootstrap@v2
    DependsOn:
      - action-name
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - artifact-name
    Outputs:
      Artifacts:
        - Name: cdk_bootstrap_artifacts
          Files: 
            - "cdk.out/**/*"
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Configuration:
      Region: us-west-2
      CdkCliVersion: version
```

## CDKBootstrapAction
<a name="cdk.boot.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `CDKBootstrapAction_nn`.

Corresponding UI: Configuration tab/**Action display name**

## Identifier
<a name="cdk.boot.identifier"></a>

(*CDKBootstrapAction*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

**Note**  
Specifying `aws/cdk-bootstrap@v2` causes the action to run on the [March 2024 image](build-images.md#build.default-image) which includes newer tooling such as Node.js 18. Specifying `aws/cdk-bootstrap@v1` causes the action to run on the [November 2022 image](build-images.md#build.previous-image) which includes older tooling such as Node.js 16.

Default: `aws/cdk-bootstrap@v2`.

Corresponding UI: Workflow diagram/CDKBootstrapAction\$1nn/**aws/cdk-bootstrap@v2** label

## DependsOn
<a name="cdk.boot.dependson"></a>

(*CDKBootstrapAction*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="cdk.boot.computename"></a>

(*CDKBootstrapAction*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="cdk.boot.computetype"></a>

(*CDKBootstrapAction*/Compute/**Type**)

(Required if [Compute](#cdk.boot.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="cdk.boot.computefleet"></a>

(*CDKBootstrapAction*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="cdk.boot.timeout"></a>

(*CDKBootstrapAction*/**Timeout**)

(Required)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Inputs
<a name="cdk.boot.inputs"></a>

(*CDKBootstrapAction*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the **AWS CDK bootstrap** action needs during a workflow run.

Corresponding UI: **Inputs** tab

**Note**  
Only one input (either a source or an artifact) is allowed for each **AWS CDK bootstrap** action.

## Sources
<a name="cdk.boot.inputs.sources"></a>

(*CDKBootstrapAction*/Inputs/**Sources**)

(Required if your AWS CDK app is stored in a source repository)

If your AWS CDK app is stored in a source repository, specify the label of that source repository. The **AWS CDK bootstrap** action synthesizes the app in this repository before starting the bootstrapping process. Currently, the only supported repository label is `WorkflowSource`.

If your AWS CDK app is not contained within a source repository, it must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="cdk.boot.inputs.artifacts"></a>

(*CDKBootstrapAction*/Inputs/**Artifacts**)

(Required if your AWS CDK app is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If your AWS CDK app is contained in an artifact generated by a previous action, specify that artifact here. The **AWS CDK bootstrap** action synthesizes the app in the specified artifact into a CloudFormation template before starting the bootstrapping process. If your AWS CDK app is not contained within an artifact, it must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Inputs tab/**Artifacts - optional**

## Outputs
<a name="cdk.boot.outputs"></a>

(*CDKBootstrapAction*/**Outputs**)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts - output
<a name="cdk.boot.outputs.artifacts"></a>

(*CDKBootstrapAction*/Outputs/**Artifacts**)

(Optional)

Specify the artifacts generated by the action. You can reference these artifacts as input in other actions.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/**Artifacts**

## Name
<a name="cdk.boot.outputs.artifacts.name"></a>

(*CDKBootstrapAction*/Outputs/Artifacts/**Name**)

(Required if [Artifacts - output](#cdk.boot.outputs.artifacts) is included)

Specify the name of the artifact that will contain the CloudFormation template that is synthesized by the **AWS CDK bootstrap** action at runtime. The default value is `cdk_bootstrap_artifacts`. If you do not specify an artifact, then the action synthesizes the template, but won't save it in an artifact. Consider saving the synthesized template in an artifact to preserve a record of it for testing or troubleshooting purposes.

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Build artifact name**

## Files
<a name="cdk.boot.outputs.artifacts.files"></a>

(*CDKBootstrapAction*/Outputs/Artifacts/**Files**)

(Required if [Artifacts - output](#cdk.boot.outputs.artifacts) is included)

Specify the files to include in the artifact. You must specify `"cdk.out/**/*"` to include your AWS CDK app's synthesized CloudFormation template.

**Note**  
`cdk.out` is the default directory into which synthesized files are saved. If you specified an output directory other than `cdk.out` in your `cdk.json` file, specify that directory here instead of `cdk.out`.

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Files produced by build**

## Environment
<a name="cdk.boot.environment"></a>

(*CDKBootstrapAction*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="cdk.boot.environment.name"></a>

(*CDKBootstrapAction*/Environment/**Name**)

(Required if [Environment](#cdk.boot.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="cdk.boot.environment.connections"></a>

(*CDKBootstrapAction*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="cdk.boot.environment.connections.name"></a>

(*CDKBootstrapAction*/Environment/Connections/**Name**)

(Required if [Connections](#cdk.boot.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="cdk.boot.environment.connections.role"></a>

(*CDKBootstrapAction*/Environment/Connections/**Role**)

(Required if [Connections](#cdk.boot.environment.connections) is included)

Specify the name of the IAM role that the **AWS CDK bootstrap** action uses to access AWS and add the bootstrap stack. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the appropriate policies.

You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Configuration
<a name="cdk.boot.configuration"></a>

(*CDKBootstrapAction*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## Region
<a name="cdk.boot.region"></a>

(*CDKBootstrapAction*/Configuration/**Region**)

(Required)

Specify the AWS Region into which the bootstrap stack will be deployed. This Region should match the one into which your AWS CDK app is deployed. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes).

Corresponding UI: Configuration tab/**Region**

## CdkCliVersion
<a name="cdk.boot.cdk.cli.version"></a>

(*CDKBootstrapAction*/Configuration/**CdkCliVersion**)

(Optional)

This property is available with version 1.0.13 or later of the **AWS CDK deploy** action, and version 1.0.8 or later of the **AWS CDK bootstrap** action.

Specify one of the following:
+ The full version of the AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI) (also called the AWS CDK Toolkit) that you want this action to use. Example: `2.102.1`. Consider specifying a full version to ensure consistency and stability when building and deploying your application.

  Or
+ `latest`. Consider specifying `latest` to take advantage of the latest features and fixes of the CDK CLI.

The action will download the specified version (or the latest version) of the AWS CDK CLI to the CodeCatalyst [build image](build-images.md), and then use this version to run the commands necessary to deploy your CDK application or bootstrap your AWS environment.

For a list of supported CDK CLI versions you can use, see [AWS CDK Versions](https://docs.aws.amazon.com/cdk/api/versions.html).

If you omit this property, the action uses a default AWS CDK CLI version described in one of the following topics:
+ [CDK CLI versions used by the 'AWS CDK deploy' action](cdk-dep-action.md#cdk-dep-action-cdk-version) 
+ [CDK CLI versions used by the "AWS CDK bootstrap" action](cdk-boot-action.md#cdk-boot-action-cdk-version)

Corresponding UI: Configuration tab/**AWS CDK CLI version**

# Publishing files to Amazon S3 with a workflow
<a name="s3-pub-action"></a>

This section describes how to publish files to Amazon S3 using a CodeCatalyst workflow. To accomplish this, you must add the **Amazon S3 publish** action to your workflow. The **Amazon S3 publish** action copies files from a source directory to an Amazon S3 bucket. The source directory can reside in:
+ A [source repository](source.md), or 
+ An [output artifact](workflows-working-artifacts.md) generated by another workflow action

**Topics**
+ [

## When to use the 'Amazon S3 publish' action
](#s3-pub-action-when-to-use)
+ [

## Runtime image used by the 'Amazon S3 publish' action
](#s3-pub-action-runtime)
+ [

# Example: Publish files to Amazon S3
](s3-pub-action-example-workflow.md)
+ [

# Adding the 'Amazon S3 publish' action
](s3-pub-action-add.md)
+ [

# 'Amazon S3 publish' action YAML
](s3-pub-action-ref.md)

## When to use the 'Amazon S3 publish' action
<a name="s3-pub-action-when-to-use"></a>

Use this action if:
+ You have a workflow that generates files that you want to store in Amazon S3.

  For example, you might have a workflow that builds a static website that you want to host in Amazon S3. In this case, your workflow would include a [build action](build-add-action.md) to build the site's HTML and supporting files, and an **Amazon S3 publish** action to copy the files to Amazon S3.
+ You have a source repository that contains files that you want to store in Amazon S3.

  For example, you might have a source repository with application source files that you want to archive on a nightly basis to Amazon S3.

## Runtime image used by the 'Amazon S3 publish' action
<a name="s3-pub-action-runtime"></a>

The **Amazon S3 publish** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Example: Publish files to Amazon S3
<a name="s3-pub-action-example-workflow"></a>

The following example workflow includes the **Amazon S3 publish** action, along with a build action. The workflow builds a static documentation website and then publishes it to Amazon S3, where it is hosted. The workflow consists of the following building blocks that run sequentially:
+ A **trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A **build** action (`BuildDocs`) – On trigger, the action builds a static documentation website (`mkdocs build`) and adds the associated HTML files and supporting metadata to an artifact called `MyDocsSite`. For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ An **Amazon S3 publish** action (`PublishToS3`) – On completion of the build action, this action copies the site in the `MyDocsSite` artifact to Amazon S3 for hosting.

**Note**  
The following workflow example is for illustrative purposes, and will not work without additional configuration.

**Note**  
In the YAML code that follows, you can omit the `Connections:` section if you want. If you omit this section, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies required by the **Amazon S3 publish** action. For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). For more information about the permissions and trust policies required by the **Amazon S3 publish** action, see the description of the [Role](s3-pub-action-ref.md#s3.pub.environment.connections.role) property in the ['Amazon S3 publish' action YAML](s3-pub-action-ref.md).

```
Name: codecatalyst-s3-publish-workflow
SchemaVersion: 1.0

Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  BuildDocs:
    Identifier: aws/build@v1
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Steps:
        - Run: echo BuildDocs started on `date`
        - Run: pip install --upgrade pip
        - Run: pip install mkdocs
        - Run: mkdocs build
        - Run: echo BuildDocs completed on `date`
    Outputs:
      Artifacts:
      - Name: MyDocsSite
        Files:
          - "site/**/*"
        
  PublishToS3:
    Identifier: aws/s3-publish@v1
    Environment:
      Name: codecatalyst-s3-publish-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-s3-publish-build-role
    Inputs:
      Sources:
        - WorkflowSource
      Artifacts:
        - MyDocsSite
    Configuration:      
      DestinationBucketName: amzn-s3-demo-bucket
      SourcePath: /artifacts/PublishToS3/MyDocSite/site
      TargetPath: my/docs/site
```

# Adding the 'Amazon S3 publish' action
<a name="s3-pub-action-add"></a>

 Use the following instructions to add the **Amazon S3 publish** action to your workflow. 

------
#### [ Visual ]

**To add the 'Amazon S3 publish' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Amazon S3 publish** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Amazon S3 publish**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs**, **Configuration**, and **Outputs** tabs, complete the fields according to your needs. For a description of each field, see the ['Amazon S3 publish' action YAML](s3-pub-action-ref.md). This reference provides detailed information on each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.

------
#### [ YAML ]

**To add the 'Amazon S3 publish' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Amazon S3 publish** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Amazon S3 publish**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Amazon S3 publish' action YAML](s3-pub-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.

------

# 'Amazon S3 publish' action YAML
<a name="s3-pub-action-ref"></a>

The following is the YAML definition of the **Amazon S3 publish** action. To learn how to use this action, see [Publishing files to Amazon S3 with a workflow](s3-pub-action.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.    
  S3Publish\$1nn: 
    Identifier: aws/s3-publish@v1
    DependsOn:
      - build-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Inputs:
      Sources:
        - source-name-1
      Artifacts:
        - artifact-name
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Configuration:
      SourcePath: my/source
      DestinationBucketName: amzn-s3-demo-bucket
      TargetPath: my/target
```

## S3Publish
<a name="s3.pub.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `S3Publish_nn`.

Corresponding UI: Configuration tab/**Action name**

## Identifier
<a name="s3.pub.identifier"></a>

(*S3Publish*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/s3-publish@v1`.

Corresponding UI: Workflow diagram/S3Publish\$1nn/**aws/s3-publish@v1** label

## DependsOn
<a name="s3.pub.dependson"></a>

(*S3Publish*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="s3.pub.computename"></a>

(*S3Publish*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="s3.pub.computetype"></a>

(*S3Publish*/Compute/**Type**)

(Required if [Compute](#s3.pub.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/**Compute type**

## Fleet
<a name="s3.pub.computefleet"></a>

(*S3Publish*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/**Compute fleet**

## Timeout
<a name="s3.pub.timeout"></a>

(*S3Publish*/**Timeout**)

(Required)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Inputs
<a name="s3.pub.inputs"></a>

(*S3Publish*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the `S3Publish` needs during a workflow run.

**Note**  
A maximum of four inputs (one source and three artifacts) are allowed for each **AWS CDK deploy** action. Variables do not count towards this total.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see [Example: Referencing files in multiple artifacts](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file).

Corresponding UI: **Inputs** tab

## Sources
<a name="s3.pub.inputs.sources"></a>

(*S3Publish*/Inputs/**Sources**)

(Required if the files you want to publish to Amazon S3 are stored in a source repository)

If the files that you want to publish to Amazon S3 are stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If the files that you want to publish to Amazon S3 are not contained within a source repository, they must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="s3.pub.inputs.artifacts"></a>

(*S3Publish*/Inputs/**Artifacts**)

(Required if the files you want to publish to Amazon S3 are stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the files that you want to publish to Amazon S3 are contained in an artifact generated by a previous action, specify that artifact here. If your files are not contained within an artifact, they must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Variables - input
<a name="s3.pub.inputs.variables"></a>

(*S3Publish*/Inputs/**Variables**)

(Optional)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Inputs tab/**Variables - optional**

## Environment
<a name="s3.pub.environment"></a>

(*S3Publish*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="s3.pub.environment.name"></a>

(*S3Publish*/Environment/**Name**)

(Required if [Environment](#s3.pub.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="s3.pub.environment.connections"></a>

(*S3Publish*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="s3.pub.environment.connections.name"></a>

(*S3Publish*/Environment/Connections/**Name**)

(Required if [Connections](#s3.pub.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="s3.pub.environment.connections.role"></a>

(*S3Publish*/Environment/Connections/**Role**)

(Required if [Connections](#s3.pub.environment.connections) is included)

Specify the name of the IAM role that the **Amazon S3 publish** action uses to access AWS and to copy files to Amazon S3. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Sid": "VisualEditor0",
              "Effect": "Allow",
              "Action": [
                  "s3:PutObject",
                  "s3:ListBucket",
                  "s3:DeleteObject"
              ],
              "Resource": [
                  "arn:aws:s3:::bucket-name",
                  "arn:aws:s3:::bucket-name/*"
              ]
          }
      ]
  }
  ```

------
+ The following custom trust policy:

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Configuration
<a name="s3.pub.configuration"></a>

(*S3Publish*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## SourcePath
<a name="s3.pub.source.directory"></a>

(*S3Publish*/Configuration/**SourcePath**)

(Required)

Specify the name and path of a directory or file that you want to publish to Amazon S3. The directory or file can reside in a source repository or an artifact from a previous action, and is relative to the source repository or artifact root.

Examples:

Specifying `./myFolder/` copies the contents of `/myFolder` to Amazon S3, and preserves the underlying directory structure.

Specifying `./myFolder/myfile.txt` copies *just *`myfile.txt` to Amazon S3. (The directory structure is removed.)

You cannot use wildcards.

**Note**  
You may need to add a prefix to the directory or file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Configuration tab/**Source path**

## DestinationBucketName
<a name="s3.pub.dest.bucket"></a>

(*S3Publish*/Configuration/**DestinationBucketName**)

(Required)

Specify the name of the Amazon S3 bucket where you want to publish files.

Corresponding UI: Configuration tab/**Destination bucket - optional**

## TargetPath
<a name="s3.pub.dest.directory"></a>

(*S3Publish*/Configuration/**TargetPath**)

(Optional)

Specify the name and path of the directory in Amazon S3 where you want to publish your files. If the directory does not exist, it will be created. The directory path must not include the bucket name.

Examples:

`myS3Folder`

`./myS3Folder/myS3Subfolder`

Corresponding UI: Configuration tab/**Destination directory - optional**

# Deploying into AWS accounts and VPCs
<a name="deploy-environments"></a>

Using [CodeCatalyst workflows](workflow.md), you can deploy applications and other resources to target AWS accounts and Amazon VPCs in the AWS cloud. To enable these deployments, you must set up CodeCatalyst environments.

A CodeCatalyst *environment*, not to be confused with a [Dev Environment](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html), defines the target AWS account and optional Amazon VPC that a CodeCatalyst [workflow](workflow.md) connects to. An environment also defines the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a workflow needs to access the AWS services and resources within the target account.

You can set up multiple environments and give them names such as development, test, staging, and production. When you deploy into these environments, information about the deployments appears on the CodeCatalyst **Deployment activity** and **Deployment targets** tabs in the environment.

## How do I get started with environments?
<a name="deploy-environments-get-started"></a>

The high-level steps to add and use a CodeCatalyst environment are as follows:

1. In your CodeCatalyst space, **connect one or more AWS accounts**. During this process, add the IAM roles that your workflow requires to access resources in your AWS account. For more information, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).

1. In your CodeCatalyst project, **create an environment** that includes one of the AWS accounts and IAM roles from step 1. For more information, see [Creating an environment](deploy-environments-creating-environment.md).

1. In your CodeCatalyst project, in a workflow, **add an [action](workflows-actions.md) that points to the environment** you created in step 2. For more information, see [Adding an action to a workflow](workflows-add-action.md).

   You have now configured an environment. The action can now deploy resources into the AWS account specified in the environment.

**Note**  
You can also add an Amazon VPC to the environment. For more information, see [Adding VPC connections for a space](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) in the *CodeCatalyst Administration Guide* and [Associating a VPC with an environment](deploy-environments-associate-vpc.md).

## Can multiple environments exist within a single workflow?
<a name="deploy-environments-multiple"></a>

Yes. If a workflow includes multiple actions, each of those actions can be assigned an environment. For example, you could have a workflow that includes two deploy actions, where one is assigned a `my-staging-enviroment` environment and another is assigned a `my-production-environment` environment.

## Which workflow actions support environments?
<a name="deploy-environments-supported"></a>

Any workflow action that deploys resources into the AWS cloud, or communicates with AWS services for other reasons (such as monitoring and reporting), supports environments.

## Which actions support having their deployment information displayed in CodeCatalyst?
<a name="deploy-environments-supported-targets"></a>

Of the workflow actions that support environments, only a few support having their deployment information displayed on the **Deployment activity** and **Deployment targets** pages of the CodeCatalyst console.

The following workflow actions support having their deployment information displayed:
+ **Deploy CloudFormation stack** – For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md)
+ **Deploy to Amazon ECS** – For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md)
+ **Deploy to Kubernetes cluster** – For more information, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md)
+ **AWS CDK deploy** – For more information, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md)

## Supported Regions
<a name="deploy-environments-supported-regions"></a>

The **Environments** page can display resources in any AWS Region.

## Is an environment mandatory?
<a name="deploy-environments-optional-or-mandatory"></a>

An environment is mandatory if the workflow action to which it is assigned deploys resources into the AWS cloud, or communicates with AWS services for other reasons (such as monitoring and reporting).

For example, if you have a build action that builds an application but doesn't need to communicate with your AWS account or Amazon VPC, then you do not need to assign an environment to the action. If, however, the build action sends logs to the Amazon CloudWatch service in your AWS account, then the action must have an environment assigned. 

**Topics**
+ [

## How do I get started with environments?
](#deploy-environments-get-started)
+ [

## Can multiple environments exist within a single workflow?
](#deploy-environments-multiple)
+ [

## Which workflow actions support environments?
](#deploy-environments-supported)
+ [

## Which actions support having their deployment information displayed in CodeCatalyst?
](#deploy-environments-supported-targets)
+ [

## Supported Regions
](#deploy-environments-supported-regions)
+ [

## Is an environment mandatory?
](#deploy-environments-optional-or-mandatory)
+ [

# Creating an environment
](deploy-environments-creating-environment.md)
+ [

# Associating an environment with an action
](deploy-environments-add-app-to-environment.md)
+ [

# Associating a VPC with an environment
](deploy-environments-associate-vpc.md)
+ [

# Associating an AWS account with an environment
](deploy-environments-associate-account.md)
+ [

# Changing the IAM role of an action
](deploy-environments-switch-role.md)

# Creating an environment
<a name="deploy-environments-creating-environment"></a>

Use the following instructions to create an environment that you can later associate with a workflow action.

**Before you begin**

You need the following:
+ A CodeCatalyst space. For more information, see [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md).
+ A CodeCatalyst project. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).
+ An AWS account connection that includes the IAM roles your workflow action will need to access AWS. For information about creating an account connection, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). You can use a maximum of one account connection per environment.
**Note**  
You can create an environment without an account connection; however, you will need to come back and add the connection later.
+ One of the following CodeCatalyst roles:
  + **Space administrator**
  + **Project administrator**
  + **Contributor**
**Note**  
If you have the **Contributor role**, you'll be able to create an environment but you won't be able to associate it with an AWS account connection. You'll need to ask someone with the **Space administrator** or **Project administrator** role to associate the environment with an AWS account connection.

   For more information about permissions and roles, see [Granting users project permissions](projects-members.md).

**To create an environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. In **Environment name**, enter a name, such as **Production** or **Staging**.

1. In **Environment type**, select one of the following:
   + **Non-production** – An environment where you can test your application to make sure it's working as intended before moving it into production.
   + **Production** – A 'live' environment that is publicly-available and hosts your finalized application.

     If you choose **Production**, a **Production** badge appears in the UI next to any actions that the environment is associated with. The badge helps you quickly see which actions are deploying to production. Other than the appearance of the badge, there are no differences between production and non-production environments.

1. (Optional) In **Description**, enter a description such as **Production environment for the hello-world app**.

1. In **AWS account connection - optional**, choose the AWS account connection you want to associate with this environment. Workflow actions that are assigned this environment will be able to connect to the associated AWS account. For more information about creating AWS account connections in CodeCatalyst, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).

   If the AWS account connection that you want to use is not listed, it might be because it's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.

1. In **Default IAM role**, choose the IAM role you want to associate with this environment. Workflow actions that are assigned this environment will inherit this IAM role, and will be able to use it to connect to services and resources in your AWS account.

   If you need to assign the environment to multiple actions, and those actions need IAM roles that are different from the default one specified here, then you can specify the different roles on each action's **Configuration** tab, using the **Switch role** option. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

   If the IAM role that you want to use as the default is not listed, it might be because you have not added it to your AWS account connection yet. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

1. (Optional) In **VPC connection**, choose a VPC connection that you want to associate with this environment. For more information about creating VPC connections, see [ Managing Amazon Virtual Private Clouds](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html) in the *Amazon CodeCatalyst Administrator Guide*.

   If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.

1. Choose **Create environment**. CodeCatalyst creates an empty environment.

**Next steps**
+ Now that you have created an environment, you are ready to associate it with a workflow action. For more information, see [Associating an environment with an action](deploy-environments-add-app-to-environment.md).

# Associating an environment with an action
<a name="deploy-environments-add-app-to-environment"></a>

When you associate an environment with a [supported workflow action](deploy-environments.md#deploy-environments-supported), the environment's AWS account, default IAM role, and optional Amazon VPC become assigned to the action. The action can then connect and deploy to the AWS account using the IAM role, and also connect to the optional Amazon VPC.

Use the following instructions to associate an environment with an action.

## Step 1: Associate the environment with a workflow action
<a name="deploy-environments-add-app-to-environment-assoc"></a>

Use the following procedure to associate an environment with a workflow action.

------
#### [ Visual ]

**To associate an environment with a workflow action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose an action that is supported with environments. For more information, see [Which actions support having their deployment information displayed in CodeCatalyst?](deploy-environments.md#deploy-environments-supported-targets).

1. Choose the **Configuration** tab, and specify information in the **Environment** field, as follows.

   **Environment**

   Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.
**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

   For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

1. (Optional) Change the IAM role associated with the action. You might want to change the role if it contains the wrong set of permissions for the action.

    To change the role:

   1. In the **What's in *my-environment* ?** box, and choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)).

   1. Choose one of the following:
      +  **Switch role**. Choose this option to change the IAM role used by this action, and only this action. Other actions continue to use the default IAM role specified in their associated environment. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).
      +  **Edit environment**. Choose this option to change the default IAM role listed in your environment. When you choose this option, your action—and any other action associated with the same environment—begins using the new default IAM role.
**Important**  
Use caution when updating the default IAM role. Changing the role might lead to action failures if the permissions in the role are not sufficient for all actions that share the environment.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To associate an environment with a workflow action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the workflow action that you want to associate with an environment, add code similar to the following:

   ```
   action-name:
     Environment:
       Name: environment-name
   ```

   For more information, see the [Action types](workflows-actions.md#workflows-actions-types) topic. This topic has links into the documentation for each action, including its YAML reference.

1. (Optional) If you want the action to use a different role from the default IAM role that's listed in the environment, add a `Connections:` section that includes the role you want to use. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## Step 2: Populate the deployment activity page
<a name="deploy-environments-add-app-to-environment-run"></a>

After associating an environment with a workflow action, you can populate the **Deployment activity** and **Deployment target** pages in the **Environments** section of the CodeCatalyst console with deployment information. Use the following instructions to populate these pages.

**Note**  
Only a few actions support having their deployment information displayed in the CodeCatalyst console. For more information, see [Which actions support having their deployment information displayed in CodeCatalyst?](deploy-environments.md#deploy-environments-supported-targets).

**To add deployment information to CodeCatalyst**

1. If a workflow run did not start automatically when you committed your changes in [Step 1: Associate the environment with a workflow action](#deploy-environments-add-app-to-environment-assoc), manually start a run as follows:

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

   1. Choose **Run**.

   The workflow run starts a new deployment, which causes CodeCatalyst to add deployment information to CodeCatalyst.

1. Verify that deployment activity was added to the CodeCatalyst console:

   1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

   1. Choose your environment (for example, `Production`).

   1. Choose the **Deployment activity** tab, and verify that a deployment appears with a **Status** of **SUCCEEDED**. This indicates that a workflow run successfully deployed your application resources.

   1. Choose the **Deployment targets** tab, and verify that your application resources appear.

# Associating a VPC with an environment
<a name="deploy-environments-associate-vpc"></a>

When an action is configured with an environment that has a VPC connection, the action will run connected to the VPC, adhering to the network rules and access resources specified by the associated VPC. The same VPC connection can be used by one or more environments.

Use the following instructions to associate a VPC connection with an environment.

**To associate a VPC connection with an environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. Choose your environment (for example, `Production`).

1. Choose the **Environment properties** tab.

1. Choose **Manage VPC connection**, choose your desired VPC connection, and choose **Confirm**. This associates your selected VPC connection with this environment.
**Note**  
If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.

For more information, see [ Managing Amazon Virtual Private Clouds](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html) in the *CodeCatalyst Administrator Guide*.

# Associating an AWS account with an environment
<a name="deploy-environments-associate-account"></a>

Use the following instructions to associate an AWS account with an environment. When you associate an AWS account with an environment, workflow actions that are assigned the environment will be able to connect to the AWS account.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).

**Before you begin**

You need the following:
+ An AWS account connection that includes the IAM roles your workflow action will need to access AWS. For information about creating an account connection, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). You can use a maximum of one account connection per environment.
+ One of the following CodeCatalyst roles: **Space administrator** or **Project administrator**. For more information, see [Granting users project permissions](projects-members.md).

**To associate an AWS account with an environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. Choose your environment (for example, `Production`).

1. Choose **Edit environment**.

1. Under **Environment properties**, in the **AWS account connection - optional** drop-down list, choose your desired AWS account.

   If the AWS account connection that you want to use is not listed, it might be because it's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.

1. In **Default IAM role**, choose the IAM role you want to associate with this environment. Workflow actions that are assigned this environment will inherit this IAM role, and will be able to use it to connect to services and resources in your AWS account.

   If the IAM role that you want to use as the default is not listed, it might be because you have not added it to your AWS account connection yet. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

# Changing the IAM role of an action
<a name="deploy-environments-switch-role"></a>

By default, when you associate an [environment](deploy-environments.md) with a workflow [action](workflows-actions.md), the action inherits the default IAM role specified in the environment. You can change this behavior so that the action uses a different role. You might want an action to use a different role if the default IAM role is missing the permissions that the action needs to operate in the AWS cloud.

To assign a different IAM role to an action, you can use the **Switch role** option in the visual editor or the `Connections:` property in the YAML editor. The new role overrides the default IAM role specified in the environment, allowing you to keep the default IAM role as-is. You might want to keep the default IAM role as-is if there are other actions that use it.

Use the following instructions to configure an action to use a different IAM role from the one specified in its environment.

------
#### [ Visual ]

**To assign a different IAM role to an action (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose the box that represents the action whose IAM role you want to update.

1. Choose the **Configuration** tab.

1. In the **What's in *my-environment* ?** box, choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)).

1. Choose **Switch role**.

1. In the **Switch role** dialog box, in the **IAM role** drop-down list, choose the IAM role that you want the action to use. This role will override the default IAM role in the environment. If the role you want to use is not in the list, make sure you've added it to your space. For more information, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

   The chosen role now appears in the **What's in *my-environment*?** box along with a **Defined in workflow** badge. The role also appears in the workflow definition file, in the `Connections:` section.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To assign a different IAM role to an action (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the workflow action where you want to use a different IAM role, add a `Connections:` section, similar to the following:

   ```
   action-name:
     Environment:
       Name: environment-name
       Connections: 
         - Name: account-connection-name
           Role: iam-role-name
   ```

   In the preceding code, replace *account-connection-name* with the name of the [account connection](ipa-connect-account.md) that contains the IAM role, and replace *iam-role-name* with the name of the IAM role that you want the action to use. This role will override the default IAM role in the environment. Make sure you've added the role to your space. For more information, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

   For more information, see the [Action types](workflows-actions.md#workflows-actions-types) topic. This topic has links into the documentation for each action, including its YAML reference.

------

# Displaying the app URL in the workflow diagram
<a name="deploy-app-url"></a>

If your workflow deploys an application, you can configure Amazon CodeCatalyst to display the application's URL as a clickable link. This link appears in the CodeCatalyst console, inside the action that deployed it. The following workflow diagram shows the **View App** URL appearing at the bottom of an action.

![\[View app URL\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/deploy/view-app-url.png)


By making this URL clickable in the CodeCatalyst console, you can quickly verify your application deployment.

**Note**  
The app URL is not supported with the **Deploy to Amazon ECS** action.

To enable this feature, add an output variable to your action with a name that contains `appurl`, or `endpointurl`. You can use a name with or without a joining dash (`-`), underscore (`_`), or space (` `). The string is case-insensitive. Set the variable's value to the `http` or `https` URL of your deployed application.

**Note**  
If you're updating an existing output variable to include the `app url`, or `endpoint url` string, update all references to this variable to use the new variable name.

For detailed steps, see one of the following procedures:
+ [To display the app URL in the "AWS CDK deploy" action](#deploy-app-url-cdk)
+ [To display the app URL in the "Deploy CloudFormation stack" action](#deploy-app-url-cfn)
+ [To display the app URL in all other actions](#deploy-app-url-other)

When you've finished configuring the URL, verify that it appears as expected by following these instructions:
+ [To verify that the application URL was added](#deploy-app-url-verify)<a name="deploy-app-url-cdk"></a>

**To display the app URL in the "AWS CDK deploy" action**

1. If you're using the **AWS CDK deploy** action, add a `CfnOutput` construct (which is a key-value pair) in your AWS CDK application code:
   + The key name must contain `appurl`, or `endpointurl`, with or without a joining dash (`-`), underscore (`_`), or space (` `). The string is case-insensitive.
   + The value must be the `http` or `https` URL of your deployed application.

   For example, your AWS CDK code might look like this:

   ```
   import { Duration, Stack, StackProps, CfnOutput, RemovalPolicy} from 'aws-cdk-lib';
   import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
   import * as s3 from 'aws-cdk-lib/aws-s3';
   import { Construct } from 'constructs';
   import * as cdk from 'aws-cdk-lib';
   export class HelloCdkStack extends Stack {
     constructor(scope: Construct, id: string, props?: StackProps) {
       super(scope, id, props);
       const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
         removalPolicy: RemovalPolicy.DESTROY,
       });
       new CfnOutput(this, 'APP-URL', {
         value: https://mycompany.myapp.com,
         description: 'The URL of the deployed application',
         exportName: 'myApp',
       });
       ...
     }
   }
   ```

   For more information about the `CfnOutput` construct, see [interface CfnOutputProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutputProps.html) in the *AWS Cloud Development Kit (AWS CDK) API Reference*.

1. Save and commit your code.

1. Proceed to [To verify that the application URL was added](#deploy-app-url-verify).<a name="deploy-app-url-cfn"></a>

**To display the app URL in the "Deploy CloudFormation stack" action**

1. If you're using the **Deploy CloudFormation stack** action, add an output to the `Outputs` section in your CloudFormation template or AWS SAM template with these characteristics:
   + The key (also called the logical ID) must contain `appurl`, or `endpointurl`, with or without a joining dash (`-`), underscore (`_`), or space (` `). The string is case-insensitive.
   + The value must be the `http` or `https` URL of your deployed application.

   For example, your CloudFormation template might look like this:

   ```
   "Outputs" : {
     "APP-URL" : {
       "Description" : "The URL of the deployed app",
       "Value" : "https://mycompany.myapp.com",
       "Export" : {
         "Name" : "My App"
       }
     }
   }
   ```

   For more information about CloudFormation outputs, see [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) in the *AWS CloudFormation User Guide*.

1. Save and commit your code.

1. Proceed to [To verify that the application URL was added](#deploy-app-url-verify).<a name="deploy-app-url-other"></a>

**To display the app URL in all other actions**

If you're using another action to deploy your application, such as the build action or **GitHub Actions**, do the following to have the app URL displayed.

1. Define an environment variable in the `Inputs` or `Steps` section of the action in the workflow definition file. The variable must have these characteristics:
   + The `name` must contain `appurl`, or `endpointurl`, with or without a joining dash (`-`), underscore (`_`), or space (` `). The string is case-insensitive.
   + The value must be the `http` or `https` URL of your deployed application.

   For example, a build action might look like this:

   ```
   Build-action:
     Identifier: aws/build@v1
     Inputs:
       Variables:
         - Name: APP-URL
           Value: https://mycompany.myapp.com
   ```

   ...or this:

   ```
   Actions:
     Build:
       Identifier: aws/build@v1
       Configuration:    
         Steps:
           - Run: APP-URL=https://mycompany.myapp.com
   ```

   For more information about defining environment variables, see [Defining a variable](workflows-working-with-variables-define-input.md).

1. Export the variable.

   For example, your build action might look like this:

   ```
   Build-action:
     ...
     Outputs:
       Variables:
         - APP-URL
   ```

   For information about exporting variables, see [Exporting a variable so that other actions can use it](workflows-working-with-variables-export-input.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

1. Proceed to [To verify that the application URL was added](#deploy-app-url-verify).<a name="deploy-app-url-verify"></a>

**To verify that the application URL was added**
+ Start a workflow run, if it hasn't started automatically. The new run should have the app URL displayed as a clickable link in its workflow diagram. For more information about starting runs, see [Starting a workflow run manually](workflows-manually-start.md). 

# Removing a deployment target
<a name="deploy-remove-target"></a>

You can remove a deployment target such as an Amazon ECS cluster or CloudFormation stack from the **Deployment targets** page in the CodeCatalyst console.

**Important**  
When you remove a deployment target, it is removed from the CodeCatalyst console, but remains available in the AWS service that hosts it (if it still exists).

Consider removing a deployment target if the target has become stale in CodeCatalyst. Targets might become stale if:
+ You deleted the workflow that deployed to the target.
+ You changed the stack or cluster that you're deploying to. 
+ You deleted the stack or cluster from the CloudFormation or Amazon ECS service in the AWS console.

**To remove a deployment target**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. Choose the name of the environment that contains the deployment target you want to remove. For information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

1. Choose the **Deployment targets** tab.

1. Choose the radio button next to the deployment target you want to remove.

1. Choose **Remove**.

   The target is removed from the page.

# Tracking deployment status by commit
<a name="track-changes"></a>

At any time in the development lifecycle, it's important to know the deployment status of specific commits, such as bug fixes, new features, or other impactful changes. Consider the following scenarios in which deployment status tracking capability is helpful to development teams:
+ As a developer, you've made a fix to address a bug and you want to report the status of its deployment across your team's deployment environments.
+ As a release manager, you want to view a list of deployed commits to track and report their deployment status.

CodeCatalyst provides a view you can use to determine at a glance where individual commits or changes have been deployed, and to which environment. This view includes: 
+ A list of commits.
+ The status of deployments that include the commits.
+ The environments in which the commits are successfully deployed.
+ The status of any tests run against the commits in your CI/CD workflow.

The following procedure details how to navigate to and use this view to track changes in your project.

**Note**  
Tracking deployment status by commit is only supported with [CodeCatalyst repositories](source.md). You cannot use this feature with a [GitHub repository, Bitbucket repository, or GitLab project repository](extensions.md).

**To track deployment status by commit**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Change tracking**.

1. In the two dropdown lists at the top of the main pane, choose the source repository and branch that contain the commits whose release status you want to view.

1. Choose **View changes**.

   A list of commits appears.

   For each commit, you can view the following:
   + Commit information such as ID, author, message, and when it was committed. For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).
   + The status of deployments to each environment. For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).
   + Test and code coverage results. For more information, see [Testing with workflowsTesting with workflows](test-workflow-actions.md).
**Note**  
Software Composition Analysis (SCA) results are not displayed.

1. (Optional) To view more information about the changes related to a specific commit, including the latest deployment and detailed code coverage and unit test information, choose **View details** for that commit.

# Viewing the deployment logs
<a name="deploy-deployment-logs"></a>

You can view logs related to specific deploy actions to troubleshoot problems in Amazon CodeCatalyst.

You can view logs starting from a [workflow](workflow.md), or an [environment](deploy-environments.md).

**To view the logs of a deploy action starting from a workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Runs**.

1. Choose the workflow run that deployed your application.

1. In the workflow diagram, choose the action whose logs you want to view.

1. Choose the **Logs** tab and expand the sections to reveal the log messages.

1. To view more logs, choose the **Summary** tab, and then choose **View in CloudFormation** (if it's available) to view more logs there. You may need to sign in to AWS.

**To view the logs of a deploy action starting from an environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. Choose the environment into which your application was deployed.

1. In **Deployment activity**, find the **Workflow Run ID** column, and choose the workflow run that deployed your stack.

1. In the workflow diagram, choose the action whose logs you want to view.

1. Choose the **Logs** tab and expand the sections to reveal the log messages.

1. To view more logs, choose the **Summary** tab, and then choose **View in CloudFormation** (if it's available) to view more logs there. You may need to sign in to AWS.

# Viewing deployment information
<a name="deploy-view-deployment-info"></a>

You can view the following information about a deployment in Amazon CodeCatalyst:
+ Deployment activity, including the deployment status, start time, end time, history, and duration of events.
+ Stack name, AWS Region, last update time, and associated workflows.
+ Commits and pull requests.
+ Action-specific information, for example, CloudFormation events and outputs.

You can view deployment information starting from a [workflow](workflow.md), an [environment](deploy-environments.md), or a workflow [action](workflows-concepts.md#workflows-concepts-actions).

**To view deployment information starting from a workflow**
+ Go to the workflow run that deployed your application. For instructions, see [Viewing workflow run status and details](workflows-view-run.md). 

**To view deployment information starting from an environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.

1. Choose the environment where your stack was deployed, for example, `Production`.

1. Choose **Deployment activity** to view the deployment history of your stacks, the status of the deployments (for example, **SUCCEEDED** or **FAILED**), and other deployment-related information.

1. Choose **Deployment target** to view information about the stacks, clusters, or other targets deployed into the environment. You can view information such as the stack name, Region, provider, and identifier.

**To view deployment information starting from an action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. In the workflow diagram, choose the workflow action that deployed your application. For example, you might choose **DeployCloudFormationStack**.

1. Review the contents in the right pane for action-specific deployment information. 

# Creating a workflow
<a name="workflows-create-workflow"></a>

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](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors).

**Tip**  
For a quick look at how you might use workflows in a project, [create a project with a blueprint](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template). Each blueprint deploys a functioning workflow that you can review, run, and experiment with.

Use the following procedure to create a workflow in CodeCatalyst. The workflow will be stored as a YAML file in a `~/.codecatalyst/workflows/` folder in the chosen source repository. Optionally, you can store the workflow in a subfolder of `~/.codecatalyst/workflows/` by prefacing the workflow file name with a folder name when you commit it. For more information, see the following instructions.

For more information about workflows, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md).

------
#### [ Visual ]<a name="workflows-create"></a>

**To create a workflow using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

   The **Create workflow** dialog box appears.

1. In the **Source repository** field, choose a source repository where the workflow definition file will reside. If no source repository exists, [create one](source-repositories-create.md).

1. In the **Branch** field, choose a branch where the workflow definition file will reside.

1. Choose **Create**.

   Amazon CodeCatalyst saves the repository and branch information in memory, but the workflow is not yet committed.

1. Choose **Visual**.

1. Build the workflow:

   1. (Optional) In the workflow diagram, choose the **Source** and **Triggers** box. A **Triggers** pane appears. Choose **Add trigger** to add a trigger. For more information, see [Adding triggers to workflows](workflows-add-trigger-add.md).

   1. Choose **\$1 Actions** (top-left). The **Actions** catalog appears.

   1. Choose the plus sign (**\$1**) inside an action to add it to the workflow. Use the pane on the right to configure the action. For more information, see [Adding an action to a workflow](workflows-add-action.md).

   1. (Optional) Choose **Workflow properties** (top-right). A **Workflow properties** pane appears. Configure the workflow name run mode, and compute. For more information, see [Configuring the queuing behavior of runs](workflows-configure-runs.md) and [Configuring compute and runtime images](workflows-working-compute.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, and on the **Commit workflow** dialog box, do the following:

   1. For **Workflow file name**, leave the default name or enter your own. The file will be stored in a `~/.codecatalyst/workflows/` folder in the chosen source repository and branch. You can preface the file name with a folder or subfolder. Examples:
      + Specifying `my-workflow` (no folder) stores the file as `~/.codecatalyst/workflows/my-workflow.yaml`
      + Specifying `folder/subfolder/my-workflow` stores the file as `~/.codecatalyst/workflows/folder/subfolder/my-workflow.yaml`

   1. For **Commit message**, leave the default message or enter your own.

   1. For **Repository** and **Branch**, choose the source repository and branch for the workflow definition file. These fields should be set to the repository and branch that you specified earlier in the **Create workflow** dialog box. You can change the repository and branch now, if you'd like.
**Note**  
After committing your workflow definition file, it cannot be associated with another repository or branch, so make sure to choose them carefully.

   1. Choose **Commit** to commit the workflow definition file.

------
#### [ YAML ]

**To create a workflow using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

   The **Create workflow** dialog box appears.

1. In the **Source repository** field, choose a source repository where the workflow definition file will reside. If no source repository exists, [create one](source-repositories-create.md).

1. In the **Branch** field, choose a branch where the workflow definition file will reside.

1. Choose **Create**.

   Amazon CodeCatalyst saves the repository and branch information in memory, but the workflow is not yet committed.

1. Choose **YAML**.

1. Build the workflow:

   1. (Optional) Add a trigger to the YAML code. For more information, see [Adding triggers to workflows](workflows-add-trigger-add.md).

   1. Choose **\$1 Actions** (top-left). The **Actions** catalog appears.

   1. Choose the plus sign (**\$1**) inside an action to add it to the workflow. Use the pane on the right to configure the action. For more information, see [Adding an action to a workflow](workflows-add-action.md).

   1. (Optional) Choose **Workflow properties** (top-right). A **Workflow properties** pane appears. Configure the workflow name, run mode, and compute. For more information, see [Configuring the queuing behavior of runs](workflows-configure-runs.md) and [Configuring compute and runtime images](workflows-working-compute.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, and on the **Commit workflow** dialog box, do the following:

   1. For **Workflow file name**, leave the default name or enter your own. The file will be stored in a `~/.codecatalyst/workflows/` folder in the chosen source repository and branch. You can preface the file name with a folder or subfolder. Examples:
      + Specifying `my-workflow` (no folder) stores the file as `~/.codecatalyst/workflows/my-workflow.yaml`
      + Specifying `folder/subfolder/my-workflow` stores the file as `~/.codecatalyst/workflows/folder/subfolder/my-workflow.yaml`

   1. For **Commit message**, leave the default message or enter your own.

   1. For **Repository** and **Branch**, choose the source repository and branch for the workflow definition file. These fields should be set to the repository and branch that you specified earlier in the **Create workflow** dialog box. You can change the repository and branch now, if you'd like.
**Note**  
After committing your workflow definition file, it cannot be associated with another repository or branch, so make sure to choose them carefully.

   1. Choose **Commit** to commit the workflow definition file.

------

# Running a workflow
<a name="workflows-working-runs"></a>

A *run* is a single iteration of a workflow. During a run, CodeCatalyst performs the actions defined in the workflow configuration file and outputs the associated logs, artifacts, and variables.

You can start a run manually, or you can start one automatically, through a *workflow trigger*. An example of a workflow trigger might be a software developer pushing a commit to your main branch.

You can also manually stop a workflow run midway through its processing if you started it by mistake.

If multiple workflow runs are started at around the same time, you can configure how you want these runs to be queued. You can use the default queuing behavior, where runs are queued one after the other in the order in which they were started, or you can have a later run supersede (or 'take over') from an earlier one to speed up your run throughout. Setting up your workflow runs to occur in parallel, so that no run waits for any other, is also possible.

After you've started a workflow run, either manually or automatically, you can view the status of the run and other details. For example, you can see when it was started, who it was started by, and whether it's still running.

**Topics**
+ [

# Starting a workflow run manually
](workflows-manually-start.md)
+ [

# Starting a workflow run automatically using triggers
](workflows-add-trigger.md)
+ [

# Configuring manual-only triggers
](workflows-manual-only.md)
+ [

# Stopping a workflow run
](workflows-stop.md)
+ [

# Gating a workflow run
](workflows-gates.md)
+ [

# Requiring approvals on workflow runs
](workflows-approval.md)
+ [

# Configuring the queuing behavior of runs
](workflows-configure-runs.md)
+ [

# Caching files between workflow runs
](workflows-caching.md)
+ [

# Viewing workflow run status and details
](workflows-view-run.md)

# Starting a workflow run manually
<a name="workflows-manually-start"></a>

In Amazon CodeCatalyst, you can start a workflow run manually from the CodeCatalyst console.

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**Note**  
You can also start a workflow run automatically by [configuring a trigger](workflows-add-trigger.md).

**To start a workflow run manually**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Run**.

# Starting a workflow run automatically using triggers
<a name="workflows-add-trigger"></a>

You can start an Amazon CodeCatalyst workflow run automatically with a workflow trigger.

A *workflow trigger*, or simply a *trigger*, allows you to start a workflow run automatically when certain events occur, like a code push. You might want to configure triggers to free your software developers from having to start workflow runs manually through the CodeCatalyst console.

You can use three types of trigger:
+ **Push** – A code push trigger causes a workflow run to start whenever a commit is pushed.
+ **Pull request** – A pull request trigger causes a workflow run to start whenever a pull request is either created, revised, or closed.
+ **Schedule** – A schedule trigger causes a workflow run to start on a schedule that you define. Consider using a schedule trigger to run nightly builds of your software so that the latest build is ready for your software developers to work on the next morning.

You can use push, pull request, and schedule triggers alone or in combination in the same workflow.

Triggers are optional—if you don't configure any, you can only start a workflow manually.

**Tip**  
To see a trigger in action, launch a project with a blueprint. Most blueprints contain a workflow with a trigger. Look for the `Trigger` property in the blueprint's workflow definition file. For more information about blueprints, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).

**Topics**
+ [

# Examples: Triggers in workflows
](workflows-add-trigger-examples.md)
+ [

# Usage guidelines for triggers and branches
](workflows-add-trigger-considerations.md)
+ [

# Adding triggers to workflows
](workflows-add-trigger-add.md)

# Examples: Triggers in workflows
<a name="workflows-add-trigger-examples"></a>

The following examples show how to add different types of triggers in an Amazon CodeCatalyst workflow definition file.

For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).

**Topics**
+ [

## Example: A simple code push trigger
](#workflows-add-trigger-examples-push-simple)
+ [

## Example: A simple 'push to main' trigger
](#workflows-add-trigger-examples-push-main)
+ [

## Example: A simple pull request trigger
](#workflows-add-trigger-examples-pull-simple)
+ [

## Example: A simple schedule trigger
](#workflows-add-trigger-examples-schedule-simple)
+ [

## Example: A trigger with a schedule and branches
](#workflows-add-trigger-examples-schedule-branches)
+ [

## Example: A trigger with a schedule, a push, and branches
](#workflows-add-trigger-examples-schedule-push-branches)
+ [

## Example: A trigger with a pull and branches
](#workflows-add-trigger-examples-pull-branches)
+ [

## Example: A trigger with a pull, branches, and a 'CLOSED' event
](#workflows-add-trigger-examples-push-pull-close)
+ [

## Example: A trigger with a push, branches, and files
](#workflows-add-trigger-examples-push-multi)
+ [

## Example: A manual trigger
](#workflows-add-trigger-examples-manual)
+ [

## Example: Triggers in a CI/CD multi-workflow setup
](#workflows-add-trigger-usecases)

## Example: A simple code push trigger
<a name="workflows-add-trigger-examples-push-simple"></a>

The following example shows a trigger that starts a workflow run whenever code is pushed to *any* branch in your source repository.

When this trigger is activated, CodeCatalyst starts a workflow run using the files in the branch that you're pushing *to* (that is, the destination branch). 

For example, if you push a commit to `main`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `main`.

As another example, if you push a commit to `feature-branch-123`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `feature-branch-123`.

```
Triggers:
  - Type: PUSH
```

**Note**  
If you want a workflow run to start only when you push to `main`, see [Example: A simple 'push to main' trigger](#workflows-add-trigger-examples-push-main).

## Example: A simple 'push to main' trigger
<a name="workflows-add-trigger-examples-push-main"></a>

The following example shows a trigger that starts a workflow run whenever code is pushed to the `main` branch—and *only* the `main` branch—in your source repository.

```
Triggers:
  - Type: PUSH
    Branches:
      - main
```

## Example: A simple pull request trigger
<a name="workflows-add-trigger-examples-pull-simple"></a>

The following example shows a trigger that starts a workflow run whenever a pull request is created or revised in your source repository.

When this trigger is activated, CodeCatalyst starts a workflow run using the workflow definition file and other source files in the branch that you're pulling *from* (that is, the source branch).

For example, if you create a pull request with a source branch called `feature-123` and a destination branch called `main`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `feature-123`.

```
Triggers:
  - Type: PULLREQUEST
    Events:
      - OPEN
      - REVISION
```

## Example: A simple schedule trigger
<a name="workflows-add-trigger-examples-schedule-simple"></a>

The following example shows a trigger that starts a workflow run at midnight (UTC\$10) every Monday through Friday.

When this trigger is activated, CodeCatalyst starts a single workflow run for each branch in your source repository that contains a workflow definition file with this trigger.

For example, if you have three branches in your source repository, `main`, `release-v1`, `feature-123`, and each of these branches contains a workflow definition file with the trigger that follows, CodeCatalyst starts three workflow runs: one using the files in `main`, another using the files in `release-v1`, and another using the files in `feature-123`.

```
Triggers:
  - Type: SCHEDULE
    Expression: "0 0 ? * MON-FRI *"
```

For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression).

## Example: A trigger with a schedule and branches
<a name="workflows-add-trigger-examples-schedule-branches"></a>

The following example shows a trigger that starts a workflow run at 6:15 pm (UTC\$10) every day.

When this trigger is activated, CodeCatalyst starts a workflow run using the files in the `main` branch, and starts additional runs for each branch that begins with `release-`.

For example, if you have branches named `main`, `release-v1`, `bugfix-1`, and `bugfix-2` in your source repository, CodeCatalyst starts two workflow runs: one using the the files in `main`, and another using the files in `release-v1`. It does *not* start workflow runs for the `bugfix-1` and `bugfix-1` branches.

```
Triggers:
  - Type: SCHEDULE
    Expression: "15 18 * * ? *"
    Branches:
      - main
      - release\-.*
```

For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression).

## Example: A trigger with a schedule, a push, and branches
<a name="workflows-add-trigger-examples-schedule-push-branches"></a>

The following example shows a trigger that starts a workflow run at midnight (UTC\$10) every day, and whenever code is pushed to the `main` branch.

In this example:
+ A workflow run starts at midnight every day. The workflow run uses the workflow definition file and other source files in the `main` branch.
+ A workflow run also starts whenever you push a commit to the `main` branch. The workflow run uses the workflow definition file and other source files in the destination branch (`main`).

```
Triggers:
  - Type: SCHEDULE
    Expression: "0 0 * * ? *"
    Branches:
      - main
  - Type: PUSH
    Branches: 
      - main
```

For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression).

## Example: A trigger with a pull and branches
<a name="workflows-add-trigger-examples-pull-branches"></a>

The following example shows a trigger that starts a workflow run whenever someone opens or modifies a pull request with a destination branch called `main`. Although the branch specified in the `Triggers` configuration is `main`, the workflow run will use the workflow definition file and other source files in the *source* branch (which is the branch you're pulling *from*).

```
Triggers:      
  - Type: PULLREQUEST
    Branches:
      - main
    Events:
      - OPEN
      - REVISION
```

## Example: A trigger with a pull, branches, and a 'CLOSED' event
<a name="workflows-add-trigger-examples-push-pull-close"></a>

The following example shows a trigger that starts a workflow run whenever a pull request is closed on a branch that starts with `main`.

In this example:
+ When you close a pull request with a destination branch that starts with `main`, a workflow run starts automatically using the workflow definition file and other source files in the (now closed) source branch.
+ If you've configured your source repository to delete branches automatically after a pull request is merged, these branches will never have the chance to enter the `CLOSED` state. This means that merged branches will not activate the pull request `CLOSED` trigger. The only way to activate the `CLOSED` trigger in this scenario is to close the pull request without merging it.

```
Triggers:     
  - Type: PULLREQUEST
    Branches:
      - main.*               
    Events:
      - CLOSED
```

## Example: A trigger with a push, branches, and files
<a name="workflows-add-trigger-examples-push-multi"></a>

The following example shows a trigger that starts a workflow run whenever a change is made to the `filename.txt` file, or any file in the `src` directory, on the `main` branch.

When this trigger is activated, CodeCatalyst starts a workflow run using the workflow definition file and other source files in the `main` branch.

```
Triggers:
  - Type: PUSH
    Branches:
      - main
    FilesChanged:
      - filename.txt
      - src\/.*
```

## Example: A manual trigger
<a name="workflows-add-trigger-examples-manual"></a>

To configure a manual trigger, omit the `Triggers` section from the workflow definition file. Without this section, users are forced to start the workflow manually by choosing the **Run** button in the CodeCatalyst console. For more information, see [Starting a workflow run manually](workflows-manually-start.md).

## Example: Triggers in a CI/CD multi-workflow setup
<a name="workflows-add-trigger-usecases"></a>

This example describes how to set up triggers when you want to use separate Amazon CodeCatalyst workflows for continuous integration (CI) and continuous deployment (CD).

In this scenario, you set up two workflows:
+ a **CI workflow** – this workflow builds and tests your application when a pull request is created or revised.
+ a **CD workflow** – this workflow builds and deploys your application when a pull request is merged.

The **CI workflow**'s definition file would look similar to this:

```
Triggers:      
  - Type: PULLREQUEST
    Branches:
      - main
    Events:
      - OPEN
      - REVISION
Actions:
  BuildAction:
    instructions-for-building-the-app
  TestAction:
    instructions-for-test-the-app
```

The `Triggers` code indicates to start a workflow run automatically whenever a software developer creates a pull request (or [modifies one](pull-requests-update.md)) asking to merge their feature branch to the `main` branch. CodeCatalyst starts the workflow run using the source code in the source branch (which is the feature branch).

The **CD workflow**'s definition file would look similar to this:

```
Triggers:      
  - Type: PUSH
    Branches:
      - main
Actions:
  BuildAction:
    instructions-for-building-the-app
  DeployAction:
    instructions-for-deploying-the-app
```

The `Triggers` code indicates to start the workflow automatically when a merge to `main` occurs. CodeCatalyst starts the workflow run using the source code in the `main` branch.

# Usage guidelines for triggers and branches
<a name="workflows-add-trigger-considerations"></a>

This section describes some of the main guidelines when setting up Amazon CodeCatalyst triggers that include branches.

For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ **Guideline 1:** For both push and pull request triggers, if you are going to specify a branch, you must specify the destination (or 'to') branch in the trigger configuration. Never specify the source (or 'from') branch.

  In the following example, a push from any branch to `main` activates the workflow.

  ```
  Triggers:
    - Type: PUSH
      Branches:
        - main
  ```

  In the following example, a pull request from any branch into `main` activates the workflow.

  ```
  Triggers:
    - Type: PULLREQUEST
      Branches:
        - main
      Events:
        - OPEN
        - REVISION
  ```
+ **Guideline 2:** For push triggers, after the workflow is activated, the workflow will run using the workflow definition file and source files in the *destination* branch.
+ **Guideline 3:** For pull request triggers, after the workflow is activated, the workflow will run using the workflow definition file and source files in the *source* branch (even though you specified the destination branch in the trigger configuration).
+ **Guideline 4:** The exact same trigger in one branch might not run in another branch.

  Consider the following push trigger:

  ```
  Triggers:
    - Type: PUSH
      Branches:
        - main
  ```

  If the workflow definition file containing this trigger exists in `main` and gets cloned to `test`, the workflow will never start automatically using the files in `test` (although you could start the workflow *manually* to have it use the files in `test`). Review **Guideline 2** to understand why the workflow will never run automatically using the files in `test`.

  Consider also the following pull request trigger:

  ```
  Triggers:
    - Type: PULLREQUEST
      Branches:
        - main
      Events:
        - OPEN
        - REVISION
  ```

  If the workflow definition file containing this trigger exists in `main`, the workflow will never run using the files in `main`. (However, if you create a `test` branch off of `main`, the workflow will run using the files in `test`.) Review **Guideline 3** to understand why.

# Adding triggers to workflows
<a name="workflows-add-trigger-add"></a>

Use the following instructions to add a push, pull, or schedule trigger to your Amazon CodeCatalyst workflow.

For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).

------
#### [ Visual ]<a name="workflows-add-trigger-add-console"></a>

**To add a trigger (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the **Source** and **Triggers** box.

1. In the configuration pane, Choose **Add trigger**.

1. In the **Add trigger** dialog box, supply information in the fields, as follows.

    **Trigger type** 

   Specify 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 a change is pushed to your source repository. The workflow run will use the files in the branch that you're pushing *to* (that is, the destination branch).
   + **Pull request** (visual editor) or `PULLREQUEST` (YAML editor)

     A pull request trigger starts a workflow run when a pull request is opened, updated, or closed in your source repository. The workflow run will use the files in the branch that you're pulling *from* (that is, the source branch).
   + **Schedule** (visual editor) or `SCHEDULE` (YAML editor)

     A schedule trigger starts workflow runs on a schedule defined by a cron expression that you specify. A separate workflow run will start for each branch in your source repository using the branch's files. (To limit the branches that the trigger activates on, use the **Branches** field (visual editor) or `Branches` property (YAML editor).)

     When configuring a schedule trigger, follow these guidelines:
     + Only use one schedule trigger per workflow.
     + If you've defined multiple workflows in your CodeCatalyst space, we recommend that you schedule no more than 10 of them to start concurrently.
     + Make sure you configure the trigger's cron expression with adequate time between runs. For more information, see [Expression](workflow-reference.md#workflow.triggers.expression).

   For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

    **Events for pull request** 

   This field only appears if you selected the **Pull request** trigger type.

   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. The `CLOSED` event's behavior is tricky, and is best understood through an example. See [Example: A trigger with a pull, branches, and a 'CLOSED' event](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close) for more information.
   + **New revision is made to pull request** (visual editor) or `REVISION` (YAML editor)

     The workflow run is started when a revision to a pull request is created. The first revision is created when the pull request is created. After that, a new revision is created every time someone pushes a new commit to the source branch specified in the pull request. If you include the `REVISION` event in your pull request trigger, you can omit the `OPEN` event, since `REVISION` is a superset of `OPEN`.

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

   For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

    **Schedule** 

   This field only appears if you selected the **Schedule** trigger type.

   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**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-add-trigger-add.html)

   When specifying cron expressions in CodeCatalyst, make sure you follow these guidelines:
   + Specify a single cron expression per `SCHEDULE` trigger.
   + Enclose the cron expression in double-quotes (`"`) in the YAML editor.
   + Specify the time in Coordinated Universal Time (UTC). Other time zones are not supported.
   + Configure at least 30 minutes between runs. A faster cadence is not supported.
   + Specify the *days-of-month* or *days-of-week* field, but not both. If you specify a value or an asterisk (`*`) in one of the fields, you must use a question mark (`?`) in the other. The asterisk means 'all' and the question mark means 'any'.

    For more examples of cron expressions and information about wildcards like `?`, `*`, and `L`, see the [Cron expressions reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html) 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](workflows-add-trigger-examples.md).

    **Branches** and **Branch pattern** 

   (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 with `main`.

   The branches to specify are different depending on the trigger type:
   + For a push trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the files in the matched branch.

     Examples: `main.*`, `mainline`
   + For a pull request trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the workflow definition file and source files in the **source** branch (*not* the matched branch).

     Examples: `main.*`, `mainline`, `v1\-.*` (matches branches that start with `v1-`)
   + For a schedule trigger, specify the branches that contain the files that you want your scheduled run to use. One workflow run will start per matched branch, using the the workflow definition file and source files in the matched branch.

     Examples: `main.*`, `version\-1\.0`
**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:  
The branch you're pushing *to* (for push triggers). For more information, see [Example: A simple code push trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple).
The branch you're pulling *from* (for pull request triggers). For more information, see [Example: A simple pull request trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple).
All branches (for schedule triggers). One workflow run will start per branch in your source repository. For more information, see [Example: A simple schedule trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple).

   For more information about branches and triggers, see [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md).

   For more examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

    **Files changed** 

   This field only appears if you selected the **Push** or **Pull request** trigger type.

   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](workflows-add-trigger-examples.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add a trigger (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Add a `Triggers` section and underlying properties using the following example as a guide. For more information, see the [Triggers](workflow-reference.md#triggers-reference) in the [Workflow YAML definition](workflow-reference.md).

   A code push trigger might look like this:

   ```
   Triggers:
     - Type: PUSH
       Branches:
         - main
   ```

   A pull request trigger might look like this:

   ```
   Triggers:
     - Type: PULLREQUEST
       Branches:
         - main.*
       Events: 
         - OPEN
         - REVISION
         - CLOSED
   ```

   A schedule trigger might look like this:

   ```
   Triggers:
     - Type: SCHEDULE
       Branches:
         - main.*
       # Run the workflow at 1:15 am (UTC+0) every Friday until the end of 2023
       Expression: "15 1 ? * FRI 2022-2023"
   ```

   For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression).

   For more examples of push, pull request, and schedule triggers, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Configuring manual-only triggers
<a name="workflows-manual-only"></a>

You can limit a workflow so that it can only be started manually by your team using the **Run** button in the CodeCatalyst console. To configure this functionality, you must remove the `Triggers` section in the workflow definition file. The `Triggers` section is included by default when you create a workflow, but the section is optional and can be removed.

Use the following instructions to remove the `Triggers` section in the workflow definition file so that the workflow can only be started manually.

For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).

For more information about running workflows, see [Running a workflow](workflows-working-runs.md).

------
#### [ Visual ]

**To remove the 'Triggers' section (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose the **Source** box in the workflow diagram.

1. Under **Triggers**, choose the trash can icon to remove the `Triggers` section from the workflow.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To remove the 'Triggers' section (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Find the `Triggers` section and remove it.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Stopping a workflow run
<a name="workflows-stop"></a>

Use the following procedure to stop a workflow run that's in progress. You might want to stop a run if it was started by accident.

When you stop a workflow run, CodeCatalyst waits for in-progress actions to complete before it marks the run as **Stopped** in the CodeCatalyst console. Any actions that didn't have a chance to start will not be started, and will be marked as **Abandoned**.

**Note**  
If a run is queued (that is, it has no in-progress actions), then the run is stopped immediately.

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**To stop a workflow run**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Under **Workflows**, choose **Runs** and choose the in-progress run from the list.

1. Choose **Stop**.

# Gating a workflow run
<a name="workflows-gates"></a>

A *gate* is a workflow component that you can use to prevent a workflow run from proceeding unless certain conditions are met. An example of a gate is the **Approval** gate where users must submit an approval in the CodeCatalyst console before the workflow run is allowed to continue.

You can add gates between sequences of actions in a workflow, or before the first action (which runs immediately after the **Source** downloads). You can also add gates after the last action, if you have a need to do so.

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**Topics**
+ [

## Gate types
](#workflows-gates-types)
+ [

## Can I set up a gate to run in parallel to another action?
](#workflows-approval-parallel)
+ [

## Can I use a gate to prevent a workflow run from starting?
](#workflows-gates-prevent)
+ [

## Limitations of gates
](#workflows-gate-limitations)
+ [

# Adding a gate to a workflow
](workflows-gates-add.md)
+ [

# Sequencing gates and actions
](workflows-gates-depends-on.md)
+ [

# Specifying the version of a gate
](workflows-gates-version.md)

## Gate types
<a name="workflows-gates-types"></a>

Currently, Amazon CodeCatalyst supports one type of gate: the **Approval** gate. For more information, see [Requiring approvals on workflow runs](workflows-approval.md).

## Can I set up a gate to run in parallel to another action?
<a name="workflows-approval-parallel"></a>

No. Gates can only run before or after an action. For more information, see [Sequencing gates and actions](workflows-gates-depends-on.md).

## Can I use a gate to prevent a workflow run from starting?
<a name="workflows-gates-prevent"></a>

Yes, with qualifications.

You can prevent a workflow run from *performing tasks*, which is slightly different from preventing it from *starting*.

To prevent a workflow from performing tasks, add a gate before the very first action in a workflow. In this scenario, a workflow run *will start*—meaning it will download your source repository files—but it will be prevented from performing tasks until the gate is unlocked.

**Note**  
Workflows that start and then get blocked by a gate still count against your *Maximum number of concurrent workflow runs per space* quota and other quotas. To ensure that you do not exceed workflow quotas, consider using a workflow trigger to conditionally start a workflow instead of using a gate. Also consider using a pull request approval rule instead of a gate. For more information about quotas, triggers, and pull request approval rules, see [Quotas for workflows in CodeCatalyst](workflows-quotas.md), [Starting a workflow run automatically using triggers](workflows-add-trigger.md), and [Managing requirements for merging a pull request with approval rules](source-pull-requests-approval-rules.md).

## Limitations of gates
<a name="workflows-gate-limitations"></a>

Gates have the following limitations:
+ Gates cannot be used in conjunction with the compute sharing feature. For more information about this feature, see [Sharing compute across actions](compute-sharing.md).
+ Gates cannot be used within action groups. For more information about action groups, see [Grouping actions into action groups](workflows-group-actions.md).

# Adding a gate to a workflow
<a name="workflows-gates-add"></a>

In Amazon CodeCatalyst, you can add a gate to a workflow to prevent it from proceeding unless certain conditions are met. Use the following instructions to add a gate to a workflow.

For more information about gates, see [Gating a workflow run](workflows-gates.md).

**To add and configure a gate**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. On the left, choose **Gates**.

1. In the gate catalog, search for a gate, and then choose the plus sign (**\$1**) to add the gate to your workflow.

1. Configure the gate. Choose **Visual** to use the visual editor, or **YAML** to use the YAML editor. For detailed instructions, see:
   + [Adding an 'Approval' gate](workflows-approval-add.md)

1. (Optional) Choose **Validate** to make sure the YAML code is valid.

1. Choose **Commit** to commit your changes.

# Sequencing gates and actions
<a name="workflows-gates-depends-on"></a>

In Amazon CodeCatalyst, you can set up a gate to run before or after a workflow action, action group, or gate. For example, you might set up an `Approval` gate to run before a `Deploy` action. In this case, the `Deploy` action is said to *depend on* the `Approval` gate.

To set up dependencies between gates and actions, configure the gate or action's **Depends on** property. For instructions, see [Setting up dependencies between actions](workflows-depends-on-set-up.md). The referenced instructions refer to workflow *actions* but apply equally to gates. 

For an example of how to set up the **Depends on** property with a gate, see [Example: An 'Approval' gate](workflows-approval-example.md).

For more information about gates, see [Gating a workflow run](workflows-gates.md).

For more information about workflow actions, see [Configuring workflow actions](workflows-actions.md).

# Specifying the version of a gate
<a name="workflows-gates-version"></a>

By default, when you add a gate to a workflow, CodeCatalyst adds the full version to the workflow definition file using the format:

`vmajor.minor.patch` 

For example:

```
My-Gate:
  Identifier: aws/approval@v1
```

You can lengthen the version so that the workflow uses a specific major or minor version of the gate. For instructions, see [Specifying the action version to use](workflows-action-versions.md). The referenced topic refers to workflow actions but applies equally to gates.

For more information about gates in CodeCatalyst, see [Gating a workflow run](workflows-gates.md).

# Requiring approvals on workflow runs
<a name="workflows-approval"></a>

You can configure a workflow run to require an approval before it can proceed. To accomplish this, you must add a **Approval** [gate](workflows-gates.md) to the workflow. An *Approval gate* prevents a workflow from proceeding until a user or set of users submit one or more approvals in the CodeCatalyst console. Once all approvals are given, the gate is 'unlocked' and the workflow run is allowed to resume.

Use an **Approval** gate in your workflow to give your development, operations, and leadership teams a chance to review your changes before they are deployed to a wider audience.

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**Topics**
+ [

## How do I unlock an approval gate?
](#workflows-approval-conditions)
+ [

## When to use the 'Approval' gate
](#workflows-approval-when)
+ [

## Who can provide an approval?
](#workflows-approval-who)
+ [

## How do I notify users that an approval is required?
](#workflows-approval-notify-methods)
+ [

## Can I use an 'Approval' gate to prevent a workflow run from starting?
](#workflows-approval-prevent)
+ [

## How do workflow approvals work with queued, superseded, and parallel run modes?
](#workflows-approval-run-mode)
+ [

# Example: An 'Approval' gate
](workflows-approval-example.md)
+ [

# Adding an 'Approval' gate
](workflows-approval-add.md)
+ [

# Configuring approval notifications
](workflows-approval-notify.md)
+ [

# Approving or rejecting a workflow run
](workflows-approval-approve.md)
+ [

# 'Approval' gate YAML
](approval-ref.md)

## How do I unlock an approval gate?
<a name="workflows-approval-conditions"></a>

To unlock an **Approval** gate, *all* of the following conditions must be met:
+ **Condition 1**: The required number of approvals must be submitted. The required number of approvals is configurable, and each user is allowed to submit a single approval.
+ **Condition 2**: All approvals must be submitted before the gate times out. The gate times out 14 days after it is activated. This period is not configurable.
+ **Condition 3**: No one must reject the workflow run. A single rejection will cause the workflow run to fail.
+ **Condition 4**: (Only applies if you are using the superseded run mode.) The run must not be superseded by a later run. For more information, see [How do workflow approvals work with queued, superseded, and parallel run modes?](#workflows-approval-run-mode).

If any of the conditions are not met, CodeCatalyst stops the workflow and sets the run status to **Failed** (in the case of **Conditions 1** to **3**) or **Superseded** (in the case of **Condition 4**).

## When to use the 'Approval' gate
<a name="workflows-approval-when"></a>

Typically, you would use an **Approval** gate in a workflow that deploys applications and other resources to a production server or any environment where quality standards must be validated. By placing the gate before the deployment to production, you give reviewers a chance to validate your new software revision before it becomes available to the public. 

## Who can provide an approval?
<a name="workflows-approval-who"></a>

Any user who is a member of your project and who has the **Contributor** or **Project administrator** role can provide an approval. Users with the **Space administrator** role who belong to your project's space can also provide an approval.

**Note**  
Users with the **Reviewer** role cannot provide approvals.

## How do I notify users that an approval is required?
<a name="workflows-approval-notify-methods"></a>

To notify users that an approval is required, you must:
+ Have CodeCatalyst send them a Slack notification. For more information, see [Configuring approval notifications](workflows-approval-notify.md).
+ Go to the page in the CodeCatalyst console where the **Approve** and **Reject** buttons are, and paste that page's URL into an email or messaging application addressed to the approvers. For more information about how to navigate to this page, see [Approving or rejecting a workflow run](workflows-approval-approve.md).

## Can I use an 'Approval' gate to prevent a workflow run from starting?
<a name="workflows-approval-prevent"></a>

Yes, with qualifications. For more information, see [Can I use a gate to prevent a workflow run from starting?](workflows-gates.md#workflows-gates-prevent).

## How do workflow approvals work with queued, superseded, and parallel run modes?
<a name="workflows-approval-run-mode"></a>

When using the queued, superseded, or parallel run mode, the **Approval** gate works in a similar way to [actions](workflows-actions.md). We suggest reading the [About queued run mode](workflows-configure-runs.md#workflows-configure-runs-queued), [About superseded run mode](workflows-configure-runs.md#workflows-configure-runs-superseded), [About parallel run mode](workflows-configure-runs.md#workflows-configure-runs-parallel) sections to familiarize yourself with these run modes. Once you have a basic understanding of them, return to this section to find out how these run modes work when the **Approval** gate is present.

When the **Approval** gate is present, runs are processed as follows:
+ If you're using the [queued run mode](workflows-configure-runs.md#workflows-configure-runs-queued), runs will queue up behind the run that is currently waiting for approval at the gate. When that gate becomes unlocked (that is, all approvals have been given), the next run in the queue advances to the gate, and waits for approvals. This process continues with queued runs being processed through the gate one-by-one. [Figure 1](#figure-1-workflow-queued-run-mode-ma) illustrates this process.
+ If you're using the [superseded run mode](workflows-configure-runs.md#workflows-configure-runs-superseded), the behavior is the same as for the queued run mode, except that instead of having runs pile up in the queue at the gate, newer runs supersede (take over from) earlier runs. There are no queues, and any run that is currently waiting at the gate for an approval will be cancelled and superseded by a newer run. [Figure 2](#figure-2-workflow-superseded-run-mode-ma) illustrates this process.
+ If you're using the [parallel run mode](workflows-configure-runs.md#workflows-configure-runs-parallel), runs start in parallel and no queues form. Each run gets processed by the gate immediately since there are no runs in front of it. [Figure 3](#figure-3-workflow-parallel-run-mode-ma) illustrates this process.

**Figure 1**: 'Queued run mode' and an **Approval** gate

![\[How an 'Approval' gate works with the 'queued run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-queued-ma.png)


**Figure 2**: 'Superseded run mode' and an **Approval** gate

![\[How an 'Approval' gate works with the 'superseded run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-superseded-ma.png)


**Figure 3**: 'Parallel run mode' and an **Approval** gate

![\[How an 'Approval' gate works with the 'parallel run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-parallel-ma.png)


# Example: An 'Approval' gate
<a name="workflows-approval-example"></a>

The following example shows how to add an **Approval** gate called `Approval_01` between two actions called `Staging`, and `Production`. The `Staging` action runs first, the `Approval_01` gate second, and the `Production` action last. The `Production` action only runs if the `Approval_01` gate is unlocked. The `DependsOn` property ensures that the `Staging`, `Approval_01`, and `Production` phases run in sequential order.

For more information about the **Approval** gate, see [Requiring approvals on workflow runs](workflows-approval.md).

```
Actions:
  Staging: # Deploy to a staging server
    Identifier: aws/ecs-deploy@v1
    Configuration:
    ...       
  Approval_01:
    Identifier: aws/approval@v1
    DependsOn:
      - Staging
    Configuration:
      ApprovalsRequired: 2 
  Production: # Deploy to a production server
    Identifier: aws/ecs-deploy@v1
    DependsOn:
      - Approval_01
    Configuration:
    ...
```

# Adding an 'Approval' gate
<a name="workflows-approval-add"></a>

To configure your workflow to require an approval, you must add the **Approval** gate to the workflow. Use the following instructions to add an **Approval** gate to your workflow.

For more information about this gate, see [Requiring approvals on workflow runs](workflows-approval.md).

------
#### [ Visual ]<a name="workflows-add-trigger-add-console"></a>

**To add an 'Approval' gate to a workflow (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. At the top-left, choose **Gates**.

1. In the **Gates** catalog, in **Approval**, choose the plus sign (**\$1**).

1. Choose **Inputs**, and in the **Depends on** field, do the following.

   Specify an action, action group, or gate that must run successfully in order for this gate to run. By default, when you add a gate to a workflow, the gate is set to depend on the last action in your workflow. If you remove this property, the gate will not depend on anything, and will run first, before other actions.
**Note**  
A gate must be configured to run before or after an action, action group, or gate. It cannot be set up to run in parallel with other actions, action groups, and gates.

   For more information about the **Depends on** functionality, see [Sequencing gates and actions](workflows-gates-depends-on.md).

1. Choose the **Configuration** tab.

1. In the **Gate name** field, do the following.

   Specify the name you want to give the gate. All gate names must be unique within the workflow. Gate names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in gate names.

1. (Optional) In the **Number of approvals** field, do the following.

   Specify the minimum number of approvals required to unlock the **Approval** gate. The minimum is `1`. The maximum is `2`. If omitted, the default is `1`.
**Note**  
If you want to omit the `ApprovalsRequired` property, remove the gate's `Configuration` section from the workflow definition file.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add an 'Approval' gate to a workflow (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Add an `Approval` section and underlying properties using the following example as a guide. For more information, see the ['Approval' gate YAML](approval-ref.md) in the [Workflow YAML definition](workflow-reference.md).

   ```
   Actions:
     MyApproval_01:
       Identifier: aws/approval@v1
       DependsOn:
         - PreviousAction
       Configuration:
         ApprovalsRequired: 2
   ```

   For another example, see [Example: An 'Approval' gate](workflows-approval-example.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Configuring approval notifications
<a name="workflows-approval-notify"></a>

You can have CodeCatalyst send a notification to a Slack channel informing users that a workflow run requires an approval. Users see the notification and click the link inside of it. The link takes them to a CodeCatalyst approvals page where they can either approve or reject the workflow.

You can also configure notifications to inform users that a workflow was approved, rejected, or that the approval request has expired.

Use the following instructions to set up Slack notifications.

**Before you begin**  
Make sure you have added an **Approval** gate to your workflow. For more information, see [Adding an 'Approval' gate](workflows-approval-add.md).

**To send workflow approval notifications to a Slack channel**

1. Configure CodeCatalyst with Slack. For more information, see [Getting started with Slack notifications](getting-started-notifications.md).

1. In the CodeCatalyst project that contains the workflow that requires an approval, enable notifications, if they're not already enabled. To enable notifications:

   1. Navigate to your project and in the navigation pane, choose **Project settings**.

   1. At the top, choose **Notifications**.

   1. In **Notification events**, choose **Edit notifications**.

   1. Turn on **Workflow approval pending** and choose a Slack channel where CodeCatalyst will send the notification. 

   1. (Optional) Turn on additional notifications to alert people about approved, rejected, and expired approvals. You can turn on **Workflow run approved**, **Workflow run rejected**, **Workflow approval superseded**, and **Workflow approval timed out**. Next to each notification, choose the Slack channel where CodeCatalyst will send the notification.

   1. Choose **Save**.

# Approving or rejecting a workflow run
<a name="workflows-approval-approve"></a>

Workflow runs that include the **Approval** gate will need to be approved or rejected. Users can provide their approval or rejection starting from:
+ the CodeCatalyst console
+ a link provided by a team member
+ an automated Slack notification

After a user provides their approval or rejection, this decision cannot be undone.

**Note**  
Only certain users can approve or reject a workflow run. For more information, see [Who can provide an approval?](workflows-approval.md#workflows-approval-who).

**Before you begin**  
Make sure you have added an **Approval** gate to your workflow. For more information, see [Adding an 'Approval' gate](workflows-approval-add.md).

**To approve or reject a workflow run starting from the CodeCatalyst console**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. In the workflow diagram, choose the box representing the **Approval** gate.

   A side panel appears.
**Note**  
At this point, you can send the URL of this page to other approvers if you want.

1. Under **Review decision**, choose **Approve** or **Reject**.

1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run.

1. Choose **Submit**.

**To approve or reject a workflow run starting from a link provided by a team member**

1. Choose the link sent to you by your team member. (You can have your team member read the preceding procedure to obtain the link.)

1. Sign in to CodeCatalyst, if asked.

   You are redirected to the workflow run approval page.

1. Under **Review decision**, choose **Approve** or **Reject**.

1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run.

1. Choose **Submit**.

**To approve or reject a workflow run starting from an automated Slack notification**

1. Make sure Slack notifications are set up. See [Configuring approval notifications](workflows-approval-notify.md).

1. In Slack, in the channel to which the approval notification was sent, choose the link in the approval notification.

1. Sign in to CodeCatalyst, if asked.

   You are redirected to the workflow run page.

1. In the workflow diagram, choose the approval gate.

1. Under **Review decision**, choose **Approve** or **Reject**.

1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run.

1. Choose **Submit**.

# 'Approval' gate YAML
<a name="approval-ref"></a>

The following is the YAML definition of the **Approval** gate. To learn how to use this gate, see [Requiring approvals on workflow runs](workflows-approval.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:
 
# The 'Approval' gate definition starts here.    
  Approval: 
    Identifier: aws/approval@v1
    DependsOn:
      - another-action
    Configuration:
      ApprovalsRequired: number
```

## Approval
<a name="approval.name"></a>

(Required)

Specify the name you want to give the gate. All gate names must be unique within the workflow. Gate names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in gate names.

Default: `Approval_nn`.

Corresponding UI: Configuration tab/**Gate name**

## Identifier
<a name="approval.identifier"></a>

(*Approval*/**Identifier**)

(Required)

Identifies the gate. The **Approval** gate supports version `1.0.0`. Do not change this property unless you want to shorten the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/approval@v1`.

Corresponding UI: Workflow diagram/Approval\$1nn/**aws/approval@v1** label

## DependsOn
<a name="approval.dependson"></a>

(*Approval*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this gate to run. By default, when you add a gate to a workflow, the gate is set to depend on the last action in your workflow. If you remove this property, the gate will not depend on anything, and will run first, before other actions.

**Note**  
A gate must be configured to run before or after an action, action group, or gate. It cannot be set up to run in parallel with other actions, action groups, and gates.

For more information about the **Depends on** functionality, see [Sequencing gates and actions](workflows-gates-depends-on.md).

Corresponding UI: Inputs tab/**Depends on**

## Configuration
<a name="approval.configuration"></a>

(*Approval*/**Configuration**)

(Optional)

A section where you can define the configuration properties of the gate.

Corresponding UI: **Configuration** tab

## ApprovalsRequired
<a name="approval.approvals.required"></a>

(*Approval*/Configuration/**ApprovalsRequired**)

(Optional)

Specify the minimum number of approvals required to unlock the **Approval** gate. The minimum is `1`. The maximum is `2`. If omitted, the default is `1`.

**Note**  
If you want to omit the `ApprovalsRequired` property, remove the gate's `Configuration` section from the workflow definition file.

Corresponding UI: Configuration tab/**Number of approvals**

# Configuring the queuing behavior of runs
<a name="workflows-configure-runs"></a>

By default in Amazon CodeCatalyst, when multiple workflow runs occur at the same time, CodeCatalyst queues them up, and processes them one by one, in the order that they were started. You can change this default behavior by specifying a *run mode*. There are a few run modes:
+ (Default) Queued run mode – CodeCatalyst processes runs one by one
+ Superseded run mode – CodeCatalyst processes runs one by one, with newer runs overtaking older ones
+ Parallel run mode – CodeCatalyst processes runs in parallel

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**Topics**
+ [

## About queued run mode
](#workflows-configure-runs-queued)
+ [

## About superseded run mode
](#workflows-configure-runs-superseded)
+ [

## About parallel run mode
](#workflows-configure-runs-parallel)
+ [

## Configuring the run mode
](#workflows-configure-runs-configure)

## About queued run mode
<a name="workflows-configure-runs-queued"></a>

In *queued run mode*, runs occur in series, with waiting runs forming a queue.

Queues form at the entry points to actions and action groups, so you can have *multiple queues within the same workflow* (see [Figure 1](#figure-1-workflow-queued-run-mode)). When a queued run enters an action, the action is locked and no other runs can enter. When the run finishes and exits the action, the action becomes unlocked and ready for the next run.

[Figure 1](#figure-1-workflow-queued-run-mode) illustrates a workflow configured in queued run mode. It shows:
+ Seven runs working their way through the workflow.
+ Two queues: one outside the entry to the input source (**Repo:main**), and one outside the entry to the **BuildTestActionGroup** action.
+ Two locked blocks: the input source (**Repo:main**) and the **BuildTestActionGroup**. 

Here's how things will transpire as the workflow runs finish processing:
+ When **Run-4d444** finishes cloning the source repository, it will exit the input source and join the queue behind **Run-3c333**. Then, **Run-5e555** will enter the input source.
+ When **Run-1a111** finishes building and testing, it will exit the **BuildTestActionGroup** action and enter the **DeployAction** action. Then, **Run-2b222** will enter the **BuildTestActionGroup** action.

**Figure 1**: A workflow configured in 'queued run mode'

![\[A workflow configured in 'queued run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/RunMode-Queued.png)


Use queued run mode if:
+ **You want to keep a one-to-one relationship between features and runs – these features may be grouped when using superseded mode**. For example, when you merge feature 1 in commit 1, run 1 starts, and when you merge feature 2 in commit 2, run 2 starts, and so on. If you were to use superseded mode instead of queued mode, your features (and commits) will be grouped together in the run that supersedes the others.
+ **You want to avoid race conditions and unexpected problems that may occur when using parallel mode**. For example, if two software developers, Wang and Saanvi, start workflow runs at roughly the same time to deploy to an Amazon ECS cluster, Wang's run might begin integration tests on the cluster while Saanvi's run deploys new application code to the cluster, causing Wang's tests either to fail or to test the wrong code. As another example, you might have a target that doesn't have a locking mechanism, in which case the two runs could overwrite each other's changes in unexpected ways.
+ **You want to limit the load** on the compute resources that CodeCatalyst uses to process your runs. For example, if you have three actions in your workflow, you can have a maximum of three runs occurring at the same time. Imposing a limit on the number of runs that can occur at once makes run throughput more predictable.
+ **You want to constrain the number of requests made to third-party services** by the workflow. For example, your workflow might have a build action that includes instructions to pull an image from Docker Hub. [Docker Hub limits the number of pull requests](https://www.docker.com/increase-rate-limits) you can make to a certain number per hour per account, and you will be locked out if you go over the limit. Using queued run mode to slow down your run throughput will have the effect of generating fewer requests to Docker Hub per hour, thus limiting the potential for lockouts and resulting build and run failures.

**Maximum queue size**: 50

Notes on **Maximum queue size**:
+ The maximum queue size refers to the maximum number of runs allowed across *all queues* in the workflow.
+ If a queue becomes longer than 50 runs, then CodeCatalyst drops the 51st and subsequent runs.

**Failure behavior**:

If a run becomes unresponsive while it's being processed by an action, then the runs behind it are held up in the queue until the action times out. Actions time out after an hour.

If a run fails inside an action, then the first queued run behind it is allowed to proceed.

## About superseded run mode
<a name="workflows-configure-runs-superseded"></a>

*Superseded run mode* is the same as *queued run mode* except that:
+ If a queued run catches up to another run in the queue, the later run supersedes (takes over from) the earlier run, and the earlier run is canceled and marked as 'superseded'.
+ As an outcome of the behavior described in the first bullet, a queue can only include one run when superseded run mode is used. 

Using the workflow in [Figure 1](#figure-1-workflow-queued-run-mode) as a guide, applying superseded run mode to this workflow would result in the following:
+ **Run-7g777** would supersede the other two runs in its queue, and would be the only run remaining in **Queue \$11**. **Run-6f666** and **Run-5e555** would be canceled.
+ **Run-3c333** would supersede **Run-2b222** and be the only run remaining in **Queue \$12**. **Run-2b222** would be canceled.

Use superseded run mode if you want:
+ better throughput than with queued mode
+ even fewer requests into third-party services than with queued mode; this is advantageous if the third-party service has rate limits, such as Docker Hub

## About parallel run mode
<a name="workflows-configure-runs-parallel"></a>

In *parallel run mode*, runs are independent of one another and don’t wait for other runs to complete before starting. There are no queues, and run throughput is limited only by how fast the actions inside the workflow take to complete. 

Use parallel run mode in development environments where each user has their own feature branch and deploys to targets that are not shared by other users.

**Important**  
If you have a shared target that multiple users can deploy to, such as a Lambda function in a production environment, do not use parallel mode, because race conditions may result. A *race condition* occurs when parallel workflow runs attempt to change a shared resource at the same time, leading to unpredictable results.

**Maximum number of parallel runs**: 1000 per CodeCatalyst space

## Configuring the run mode
<a name="workflows-configure-runs-configure"></a>

You can set the run mode to queued, superseded, or parallel. The default is queued.

When you change the run mode from queued or superseded to parallel, CodeCatalyst cancels the runs that are queued, and allows the runs that are currently being processed by an action to finish before canceling them.

When you change the run mode from parallel to queued or superseded, CodeCatalyst lets all currently-running parallel runs complete. Any runs that you start after changing the run mode to queued or superseded use the new mode.

------
#### [ Visual ]

**To change the run mode using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. At the top-right, choose **Workflow properties**.

1. Expand **Advanced**, and under **Run mode**, choose one of the following:

   1. **Queued** – see [About queued run mode](#workflows-configure-runs-queued)

   1. **Superseded** – see [About superseded run mode](#workflows-configure-runs-superseded)

   1. **Parallel** – see [About parallel run mode](#workflows-configure-runs-parallel)

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To change the run mode using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Add the `RunMode` property, like this:

   ```
   Name: Workflow_6d39
   SchemaVersion: "1.0"
   RunMode: QUEUED|SUPERSEDED|PARALLEL
   ```

   For more information, see the description of the `RunMode` property in the [Top-level properties](workflow-reference.md#workflow.top.level) section of the [Workflow YAML definition](workflow-reference.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Caching files between workflow runs
<a name="workflows-caching"></a>

When file caching is enabled, the build and test actions save on-disk files to a cache and restore them from that cache in subsequent workflow runs. Caching reduces the latency caused by building or downloading dependencies that haven’t changed between runs. CodeCatalyst also supports fallback caches, which can be used to restore partial caches containing some of the needed dependencies. This helps reduce the latency impacts of a cache miss.

**Note**  
File caching is only available with the Amazon CodeCatalyst [build](build-workflow-actions.md) and [test](test-workflow-actions.md) actions, and only when they are configured to use the **EC2** [compute type](workflows-working-compute.md#compute.types).

**Topics**
+ [

## About file caching
](#workflows-caching.files)
+ [

## Creating a cache
](#workflows-caching.fallback)
+ [

## File caching constraints
](#workflows-caching.constraints)

## About file caching
<a name="workflows-caching.files"></a>

File caching allows you to organize your data into multiple caches, which are each referenced under the `FileCaching` property. Each cache saves a directory specified by a given path. The specified directory will be restored in future workflow runs. The following is an example YAML snippet for caching with multiple caches named `cacheKey1` and `cacheKey2`.

```
Actions:
  BuildMyNpmApp:
    Identifier: aws/build@v1
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Steps:
        - Run: npm install
        - Run: npm run test
    Caching:
      FileCaching:
        cacheKey1:
          Path: file1.txt
          RestoreKeys:
             - restoreKey1
        cacheKey2:
          Path: /root/repository
          RestoreKeys:
             - restoreKey2
             - restoreKey3
```

**Note**  
CodeCatalyst uses multilayered caching, which consists of a local cache and a remote cache. When provisioned fleets or on-demand machines encounter a cache miss on a local cache, dependencies will be restored from a remote cache. As a result, some action runs may experience latency from downloading a remote cache.

CodeCatalyst applies cache access restrictions to ensure that an action in one workflow cannot modify the caches from a different workflow. This protects each workflow from others that might push incorrect data that impact builds or deployments. Restrictions are enforced with cache-scopes which isolate caches to every workflow and branch pairing. For example, `workflow-A` in branch `feature-A` has a different file cache than `workflow-A` in sibling branch `feature-B`.

Cache misses occur when a workflow looks for a specified file cache and is unable to find it. This can occur for multiple reasons, such as when a new branch is created or when a new cache is referenced and it hasn't been created yet. It can also occur when a cache expires, which by default occurs 14 days after it was last used. To mitigate cache misses and increase the rate of cache hits, CodeCatalyst supports fallback caches. Fallback caches are alternate caches and provide an opportunity to restore partial-caches, which can be an older version of a cache. A cache is restored by first searching for a match under `FileCaching` for the property name, and if not found, evaluates `RestoreKeys`. If there is a cache miss for both the property name and all `RestoreKeys`, the workflow will continue to run, as caching is best effort and not guaranteed.

## Creating a cache
<a name="workflows-caching.fallback"></a>

You can use the following instructions to add a cache to your workflow.

------
#### [ Visual ]

**To add a cache using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action where you want to add your cache.

1. Choose **Configuration**.

1. Under **File caching - optional**, choose **Add cache** and enter information into the fields, as follows:

    **Key** 

   Specify the name of your primary cache property name. Cache property names must be unique within your workflow. Each action can have up to five entries in `FileCaching`.

    **Path** 

   Specify the associated path for your cache. 

    **Restore keys - optional** 

   Specify the restore key to use as a fallback when the primary cache property can't be found. Restore key names must be unique within your workflow. Each cache can have up to five entries in `RestoreKeys`.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and then choose **Commit** again.

------
#### [ YAML ]

**To add a cache using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a workflow action, add code similar to the following:

   ```
   action-name:
     Configuration:
       Steps: ...
     Caching:
       FileCaching:
         key-name:
           Path: file-path
           # # Specify any additional fallback caches
           # RestoreKeys:
           #  - restore-key
   ```

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## File caching constraints
<a name="workflows-caching.constraints"></a>

The following are the constraints for the property name and `RestoreKeys`:
+ Names must be unique within a workflow.
+ Names are limited to alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), and underscores (\$1).
+ Names can have up to 180 characters.
+ Each action can have up to five caches in `FileCaching`.
+ Each cache can have up to five entries in `RestoreKeys`.

The following are the constraints for paths:
+ Asterisks (\$1) are not allowed.
+ Paths can have up to 255 characters.

# Viewing workflow run status and details
<a name="workflows-view-run"></a>

IN Amazon CodeCatalyst, you can view the status and details of a single workflow run, or multiple runs at the same time.

For a list of possible run states see [Workflow run states](workflows-view-run-status.md).

**Note**  
You can also view the workflow status, which is different from the workflow *run* status. For more information, see [Viewing a workflow's status](workflows-view-status.md).

For more information about workflow runs, see [Running a workflow](workflows-working-runs.md).

**Topics**
+ [

## Viewing the status and details of a single run
](#workflows-view-run-single)
+ [

## Viewing the status and details of all runs in your project
](#workflows-view-run-all)
+ [

## Viewing the status and details of all runs of a specific workflow
](#workflows-view-run-wf)
+ [

## Viewing runs of a workflow in the workflow diagram
](#workflows-view-run-wf-diagram)

## Viewing the status and details of a single run
<a name="workflows-view-run-single"></a>

You might want to view the status and details of a single workflow run to check whether it was successful, to see at what time it was completed, or to view who or what started it.

**To view the status and details of a single run**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Under the workflow's name, choose **Runs**.

1. In **Run history**, in the **Run ID** column, choose a run. For example, `Run-95a4d`.

1. Under the run's name, do one of the following:
   + **Visual** to see a workflow diagram showing your workflow run's actions and their status (see [Workflow run states](workflows-view-run-status.md)). This view also shows the source repository and branch used during the run.

     In the workflow diagram, choose an action to see details such as logs, reports, and outputs generated by the action during the run. The information shown depends on which action type is selected. For more information about viewing build or deploy logs, see [Viewing the results of a build action](build-view-results.md) or [Viewing the deployment logs](deploy-deployment-logs.md).
   + **YAML** to see the workflow definition file that was used for the run.
   + **Artifacts** to see the artifacts produced by the workflow run. For more information about artifacts, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).
   + **Reports** to see the test reports and other types of reports produced by the workflow run. For more information about reports, see [Quality report types](test-workflow-actions.md#test-reporting).
   + **Variables** to see the output variables produced by the workflow run. For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).
**Note**  
If the run's parent workflow was deleted, a message indicating this fact appears at the top of the run details page.

## Viewing the status and details of all runs in your project
<a name="workflows-view-run-all"></a>

You might want to view the status and details of all workflow runs within your project understand how much workflow activity is going on in your project, and learn about the overall health of your workflows.

**To view the status and details of all runs in your project**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Under **Workflows**, choose **Runs**.

   All the runs, for all workflows, in all branches, across all repositories in your project, are displayed. 

   The page includes the following columns:
   + **Run ID** – The unique identifier of the run. Choose the run ID link to view detailed information about the run.
   + **Status** – The processing status of the workflow run. For more information about run states, see [Workflow run states](workflows-view-run-status.md).
   + **Trigger** – The person, commit, pull request (PR), or schedule that started the workflow run. For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
   + **Workflow** – The name of the workflow for which a run was started, and the source repository and branch where the workflow definition file resides. You might need to expand the column width to see this information.
**Note**  
If this column is set to **Not available**, it's usually because the associated workflow was deleted or moved.
   + **Start time** – The time when the workflow run started.
   + **Duration** – How long the workflow run took to process. Very long or very short durations might indicate problems.
   + **End time** – The time when the workflow run ended.

## Viewing the status and details of all runs of a specific workflow
<a name="workflows-view-run-wf"></a>

You might want to view the status and details of all runs associated with a specific workflow to see if any runs are creating bottlenecks within the workflow, or to see which runs are currently in progress or have completed.

**To view the status and details of all runs of a specific workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Under the workflow's name, choose **Runs**.

   The runs associated with the chosen workflow appear.

   The page is divided into two sections:
   + **Active runs** – Displays runs that are in progress. These runs will be in one of the following states: **In progress**.
   + **Run history** – Displays runs that have completed (that is, not in progress).

     For more information about run states, see [Workflow run states](workflows-view-run-status.md).

## Viewing runs of a workflow in the workflow diagram
<a name="workflows-view-run-wf-diagram"></a>

You can view the status of all runs of a workflow as they progress together through the workflow. The runs are displayed within the workflow diagram (as opposed to in a list view). This gives you a visual representation of which runs are being processed by which actions, and which runs are waiting in a queue.

**To view the status of multiple runs as they progress together through a workflow**
**Note**  
This procedure only applies if your workflow is using the queued or superseded run mode. For more information, see [Configuring the queuing behavior of runs](workflows-configure-runs.md).

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
**Note**  
Make sure you're looking at a workflow page and not a run page.

1. Choose the **Latest state** tab on the upper left.

   A workflow diagram appears.

1. Review the workflow diagram. The diagram shows all the runs that are currently in progress within the workflow, and the latest runs that have finished. More specifically:
   + Runs that appear at the top, before **Sources**, are queued and waiting to start.
   + Runs that appear between actions are queued and waiting to be processed by the next action.
   + Runs that appear within an action are 1. currently being processed by the action, 2. have finished being processed by the action, or 3. were not processed by the action (usually because a previous action failed).

# Configuring workflow actions
<a name="workflows-actions"></a>

An *action* is the main building block of a workflow, and defines a logical unit of work, or task, to perform during a workflow run. Typically, a workflow includes multiple actions that run sequentially or in parallel depending on how you've configured them.

**Topics**
+ [

## Action types
](#workflows-actions-types)
+ [

# Adding an action to a workflow
](workflows-add-action.md)
+ [

# Removing an action from a workflow
](workflows-delete-action.md)
+ [

# Developing a custom action
](workflows-custom-action.md)
+ [

# Grouping actions into action groups
](workflows-group-actions.md)
+ [

# Sequencing actions
](workflows-depends-on.md)
+ [

# Sharing artifacts and files between actions
](workflows-working-artifacts.md)
+ [

# Specifying the action version to use
](workflows-action-versions.md)
+ [

# Listing the available action versions
](workflows-action-versions-determine.md)
+ [

# Viewing an action's source code
](workflows-view-source.md)
+ [

# Integrating with GitHub Actions
](integrations-github-actions.md)

## Action types
<a name="workflows-actions-types"></a>

Within an Amazon CodeCatalyst workflow, you can use the following types of actions.

**Topics**
+ [

### CodeCatalyst actions
](#workflows-actions-types-cc)
+ [

### CodeCatalyst Labs actions
](#workflows-actions-types-cc-labs)
+ [

### GitHub Actions
](#workflows-actions-types-github)
+ [

### Third-party actions
](#workflows-actions-types-3p)

### CodeCatalyst actions
<a name="workflows-actions-types-cc"></a>

A *CodeCatalyst action* is an action that is authored, maintained, and fully supported by the CodeCatalyst development team.

There are CodeCatalyst actions for building, testing, and deploying applications, as well as for performing miscellaneous tasks, such as invoking an AWS Lambda function.

The following CodeCatalyst actions are available:
+ **Build**

  This action builds your artifacts and runs your unit tests in a Docker container. For more information, see [Adding the build action](build-add-action.md).
+ **Test**

  This action runs integration and system tests against your application or artifacts. For more information, see [Adding the test action](test-add-action.md).
+ **Amazon S3 publish**

  This action copies your application artifacts to an Amazon S3 bucket. For more information, see [Publishing files to Amazon S3 with a workflow](s3-pub-action.md).
+ **AWS CDK bootstrap**

  This action provisions the resources that the AWS CDK needs to deploy your CDK app. For more information, see [Bootstrapping an AWS CDK app with a workflow](cdk-boot-action.md).
+ **AWS CDK deploy**

  This action synthesizes and deploys an AWS Cloud Development Kit (AWS CDK) app. For more information, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md).
+ **AWS Lambda invoke**

  This action invokes an AWS Lambda function. For more information, see [Invoking a Lambda function using a workflow](lam-invoke-action.md).
+ **GitHub Actions**

  This action is a *CodeCatalyst* action that allows you to run GitHub Actions within a CodeCatalyst workflow. For more information, see [Invoking a Lambda function using a workflow](lam-invoke-action.md).
+ **Deploy CloudFormation stack**

  This action deploys CloudFormation stacks. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md).
+ **Deploy to Amazon ECS**

  This action registers an Amazon ECS task definition and deploys it to an Amazon ECS service. For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md).
+ **Deploy to Kubernetes cluster**

  This action deploys an application to a Kubernetes cluster. For more information, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md).
+ **Render Amazon ECS task definition**

  This action inserts a container image URI into an Amazon ECS task definition JSON file, creating a new task definition file. For more information, see [Modifying an Amazon ECS task definition](render-ecs-action.md).

Documentation for CodeCatalyst actions is available in this guide, and in each action's readme.

For information about the available CodeCatalyst actions, and how to add one to a workflow, see [Adding an action to a workflow](workflows-add-action.md).

### CodeCatalyst Labs actions
<a name="workflows-actions-types-cc-labs"></a>

A *CodeCatalyst Labs action* is an action that is part of Amazon CodeCatalyst Labs, a proving ground for experimental applications. CodeCatalyst Labs actions have been developed to showcase integrations with AWS services.

The following CodeCatalyst Labs actions are available:
+ **Deploy to AWS Amplify Hosting**

  This action deploys an application to Amplify Hosting.
+ **Deploy to AWS App Runner**

  This action deploys the latest image in a source image repository to App Runner.
+ **Deploy to Amazon CloudFront and Amazon S3**

  This action deploys an application to CloudFront and Amazon S3.
+ **Deploy with AWS SAM**

  This action deploys your serverless application with AWS Serverless Application Model (AWS SAM).
+ **Invalidate Amazon CloudFront Cache**

  This action invalidates a CloudFront cache for a given set of paths.
+ **Outgoing Webhook**

  This action allows users to send messages within a workflow to an arbitrary web server using an HTTPS request.
+ **Publish to AWS CodeArtifact**

  This action publishes packages to a CodeArtifact repository.
+ **Publish to Amazon SNS**

  This action allows users to integrate with Amazon SNS by creating a topic, publishing to a topic, or subscribing to a topic.
+ **Push to Amazon ECR**

  This action builds and publishes a Docker image to an Amazon Elastic Container Registry (Amazon ECR) repository.
+ **Scan with Amazon CodeGuru Security**

  This action creates a zip archive of a configured code path and uses CodeGuru Security to run a code scan.
+ **Terraform Community Edition**

  This action runs Terraform Community Edition `plan` and `apply` operations.

Documentation for CodeCatalyst Labs actions is available in each action's readme.

For information about adding a CodeCatalyst Labs action to a workflow and viewing its readme, see [Adding an action to a workflow](workflows-add-action.md).

### GitHub Actions
<a name="workflows-actions-types-github"></a>

A *GitHub Action* is a lot like a [CodeCatalyst action](#workflows-actions-types-cc), except that it was developed for use with GitHub workflows. For details about GitHub Actions, see the [GitHub Actions](https://docs.github.com/en/actions) documentation.

You can use GitHub Actions alongside native CodeCatalyst actions in a CodeCatalyst workflow.

For your convenience, the CodeCatalyst console provides access to several popular GitHub Actions. You can also use any GitHub Action listed in the [GitHub Marketplace](https://github.com/marketplace/actions) (subject to a few limitations).

Documentation for GitHub Actions is available in each action's readme.

For more information, see [Integrating with GitHub Actions](integrations-github-actions.md).

### Third-party actions
<a name="workflows-actions-types-3p"></a>

A *third-party action* is an action that is authored by a third-party vendor, and made available in the CodeCatalyst console. Examples of third-party actions include the **Mend SCA** and **SonarCloud Scan** actions, authored by Mend and Sonar, respectively.

Documentation for third-party actions is available in each action's readme. Additional documentation might also be provided by the third-party vendor.

For information about adding a third-party action to a workflow and viewing its readme, see [Adding an action to a workflow](workflows-add-action.md).

# Adding an action to a workflow
<a name="workflows-add-action"></a>

Use the following instructions to add an action to a workflow and then configure it.

**To add and configure an action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. At the top-left, choose **\$1 Actions**, The **Actions** catalog appears.

1. In the drop-down list, do one of the following:
   + Choose **Amazon CodeCatalyst** to view [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc), [CodeCatalyst Labs ](workflows-actions.md#workflows-actions-types-cc-labs), or [third-party](workflows-actions.md#workflows-actions-types-3p) actions.
     + CodeCatalyst actions have a **by AWS** label.
     + CodeCatalyst Labs actions have a **by CodeCatalyst Labs** label.
     + Third-party actions have a **by *vendor*** label, where *vendor* is the name of the third-party vendor.
   + Choose **GitHub** to view a [curated list of GitHub Actions](integrations-github-action-add-curated.md).

1. In the action catalog, search for an action, and then do one of the following:
   + Choose the plus sign (**\$1**) to add the action to your workflow.
   + Choose the action's name to view its readme.

1. Configure the action. Choose **Visual** to use the visual editor, or **YAML** to use the YAML editor. For detailed instructions, see the following links.

   For instructions on adding [CodeCatalyst actions](workflows-actions.md#workflows-actions-types-cc), see:
   + [Adding the build action](build-add-action.md)
   + [Adding the test action](test-add-action.md)
   + [Adding the 'Deploy to Amazon ECS' action](deploy-action-ecs-adding.md)
   + [Adding the 'Deploy to Kubernetes cluster' action](deploy-action-eks-adding.md)
   + [Adding the 'Deploy CloudFormation stack' action](deploy-action-cfn-adding.md)
   + [Adding the 'AWS CDK deploy' action](cdk-dep-action-add.md)
   + [Adding the 'AWS CDK bootstrap' action](cdk-boot-action-add.md)
   + [Adding the 'Amazon S3 publish' action](s3-pub-action-add.md)
   + [Adding the 'AWS Lambda invoke' action](lam-invoke-action-add.md)
   + [Adding the 'Render Amazon ECS task definition' action](render-ecs-action-add.md)

   For instructions on adding [CodeCatalyst Labs actions](workflows-actions.md#workflows-actions-types-cc-labs), see:
   + The action's readme. You can find the readme by choosing the action's name in the action catalog.

   For instructions on adding [GitHub Actions](workflows-actions.md#workflows-actions-types-github), see:
   + [Integrating with GitHub Actions](integrations-github-actions.md)

   For instructions on adding [third-party actions](workflows-actions.md#workflows-actions-types-3p), see:
   + The action's readme. You can find the readme by choosing the action's name in the action catalog.

1. (Optional) Choose **Validate** to make sure the YAML code is valid.

1. Choose **Commit** to commit your changes.

# Removing an action from a workflow
<a name="workflows-delete-action"></a>

Use the following instructions to remove an action from a workflow.

------
#### [ Visual ]

**To remove an action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, in the action you want to remove, choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)), and choose **Remove**.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To remove an action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Find the section of the YAML that contains the action you want to remove.

   Select the section and press the delete key on your keyboard.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Developing a custom action
<a name="workflows-custom-action"></a>

You can develop a custom action to use in your workflows using the CodeCatalyst Action Development Kit (ADK). You can then publish the action to the CodeCatalyst actions catalog, so that other CodeCatalyst users can view and use it in their workflows.

**To develop, test, and publish an action (high-level tasks)**

1. Install the required tools and packages necessary to develop an action.

1. Create a CodeCatalyst repository to store your action code.

1. Initialize the action. This lays down the source files required by the action, including an action definition file (`action.yml`) that you can update with your own code.

1. Bootstrap the action code to get the necessary tools and libraries to build, test, and release the action project.

1. Build the action on your local computer, and push the changes to your CodeCatalyst repository.

1. Test the action with unit tests locally, and run the ADK-generated workflow in CodeCatalyst.

1. Publish the action to the CodeCatalyst actions catalog by choosing the **Publish** button in the CodeCatalyst console.

For detailed steps, see the [Amazon CodeCatalyst Action Development Kit Developer Guide](https://docs.aws.amazon.com/codecatalyst/latest/adk/what-is-action-development-kit.html).

# Grouping actions into action groups
<a name="workflows-group-actions"></a>

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.

**Note**  
You cannot nest action groups within other action groups or actions.

**Topics**
+ [

## Defining an action group
](#workflows-define-action-group)
+ [

# Example: Defining two action groups
](workflows-group-actions-example.md)

## Defining an action group
<a name="workflows-define-action-group"></a>

Use the following instructions to define an CodeCatalyst action group.

------
#### [ Visual ]

*Not available. Choose YAML to view the YAML instructions.*

------
#### [ YAML ]

**To define a group**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In `Actions`, add code similar to the following:

   ```
   Actions:
     action-group-name: 
       Actions:
         action-1:
           Identifier: aws/build@v1
           Configuration:
             ...
         action-2:
           Identifier: aws/build@v1
           Configuration:
             ...
   ```

   For another example, see [Example: Defining two action groups](workflows-group-actions-example.md). For more information, see the description of the `action-group-name` property in the [Actions](workflow-reference.md#actions-reference) of the [Workflow YAML definition](workflow-reference.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Example: Defining two action groups
<a name="workflows-group-actions-example"></a>

The following example shows how to define two Amazon CodeCatalyst action groups: `BuildAndTest` and `Deploy`. The `BuildAndTest` group includes two actions (`Build` and `Test`), and the `Deploy` group also includes two actions (`DeployCloudFormationStack` and `DeployToECS`).

```
Actions:
  BuildAndTest: # Action group 1
    Actions:
      Build:
        Identifier: aws/build@v1
        Configuration:
          ...
      Test:
        Identifier: aws/managed-test@v1
        Configuration:
  Deploy: #Action group 2
    Actions:
      DeployCloudFormationStack:
        Identifier: aws/cfn-deploy@v1
        Configuration:
          ...
      DeployToECS:
        Identifier: aws/ecs-deploy@v1
        Configuration:
          ...
```

# Sequencing actions
<a name="workflows-depends-on"></a>

By default, when you add actions to a workflow, they are added side by side in the [visual editor](workflow.md#workflow.editors). This means that the actions will run in parallel when you start a workflow run. If you want actions to run in sequential order (and appear vertically in the visual editor), you must set up dependencies between them. For example, you might set up a `Test` action to depend on the `Build` action so that the test action runs after the build action.

You can set up dependencies between actions and action groups. You can also configure one-to-many dependencies so that one action depends on several others in order to start. Consult the guidelines in [Setting up dependencies between actions](workflows-depends-on-set-up.md) to ensure your dependency setup conforms with the workflow's YAML syntax.

**Topics**
+ [

# Examples of how to configure dependencies between actions
](workflows-depends-on-examples.md)
+ [

# Setting up dependencies between actions
](workflows-depends-on-set-up.md)

# Examples of how to configure dependencies between actions
<a name="workflows-depends-on-examples"></a>

The following examples show how to configure dependencies between actions and groups in the workflow definition file.

**Topics**
+ [

## Example: Configuring a simple dependency
](#workflows-depends-on-example-simple)
+ [

## Example: Configuring an action group to depend on an action
](#workflows-depends-on-example-action-groups-actions)
+ [

## Example: Configuring an action group to depend on another action group
](#workflows-depends-on-example-two-action-groups)
+ [

## Example: Configuring an action group to depend on multiple actions
](#workflows-depends-on-example-advanced)

## Example: Configuring a simple dependency
<a name="workflows-depends-on-example-simple"></a>

The following example shows how to configure a `Test` action to depend on the `Build` action using the `DependsOn` property.

```
Actions:
  Build:
    Identifier: aws/build@v1
    Configuration:
      ...
  Test:
    DependsOn:
      - Build
    Identifier: aws/managed-test@v1
     Configuration:
       ...
```

## Example: Configuring an action group to depend on an action
<a name="workflows-depends-on-example-action-groups-actions"></a>

The following example shows how to configure a `DeployGroup` action group to depend on the `FirstAction` action. Notice that action and action group are at the same level.

```
Actions:
  FirstAction: #An action outside an action group
    Identifier: aws/github-actions-runner@v1
    Configuration:
      ...
  DeployGroup: #An action group containing two actions
    DependsOn: 
      - FirstAction
    Actions:
      DeployAction1:
      ...
      DeployAction2:
      ...
```

## Example: Configuring an action group to depend on another action group
<a name="workflows-depends-on-example-two-action-groups"></a>

The following example shows how to configure a `DeployGroup` action group to depend on the `BuildAndTestGroup` action group. Notice that the action groups are at the same level.

```
Actions:
  BuildAndTestGroup: # Action group 1
    Actions:
      BuildAction:
      ...
      TestAction:
      ...
  DeployGroup: #Action group 2
    DependsOn: 
      - BuildAndTestGroup
    Actions:
      DeployAction1:
      ...
      DeployAction2:
      ...
```

## Example: Configuring an action group to depend on multiple actions
<a name="workflows-depends-on-example-advanced"></a>

The following example shows how to configure a `DeployGroup` action group to depend on the `FirstAction` action, the `SecondAction` action, as well as the `BuildAndTestGroup` action group. Notice that `DeployGroup` is at the same level as `FirstAction`, `SecondAction`, and `BuildAndTestGroup`.

```
Actions:
  FirstAction: #An action outside an action group
    ...
  SecondAction: #Another action 
    ...
  BuildAndTestGroup: #Action group 1
    Actions:
      Build:
      ...
      Test:
      ...
  DeployGroup: #Action group 2
    DependsOn: 
      - FirstAction
      - SecondAction
      - BuildAndTestGroup
    Actions:
      DeployAction1:
      ...
      DeployAction2:
      ...
```

# Setting up dependencies between actions
<a name="workflows-depends-on-set-up"></a>

Use the following instructions to set up dependencies between actions in a workflow.

When configuring dependencies, follow these guidelines:
+ If an action is inside a group, that action can only depend on other actions within the same group.
+ Actions and action groups can depend on other actions and action groups *at the same level* in the YAML hierarchy, but *not* at a different level.

------
#### [ Visual ]

**To set up dependencies using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that will depend on another action.

1. Choose the **Inputs** tab.

1. In **Depends on - optional**, do the following:

   Specify an action, action group, or gate that must run successfully in order for this action to run.

   For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To set up dependencies using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In an action that will depend on another, add code similar to the following:

   ```
   action-name:
     DependsOn:
       - action-1
   ```

   For more examples, see [Examples of how to configure dependencies between actions](workflows-depends-on-examples.md). For general guidelines, see [Setting up dependencies between actions](#workflows-depends-on-set-up). For more information, see the description of the `DependsOn` property in the [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Sharing artifacts and files between actions
<a name="workflows-working-artifacts"></a>

An *artifact* is the output of a workflow action, and typically consists of a folder or archive of files. Artifacts are important because they allow you to share files and information between actions.

For example, you might have a build action that *generates* a `sam-template.yml` file, but you want a deploy action to *use* it. In this scenario, you would use an artifact to allow the build action to share the `sam-template.yml` file with the deploy action. The code might look something like this:

```
Actions:
  BuildAction:
    Identifier: aws/build@v1
    Steps:
      - Run: sam package --output-template-file sam-template.yml
    Outputs:
      Artifacts:
        - Name: MYARTIFACT
          Files:
            - sam-template.yml
  DeployAction:
    Identifier: aws/cfn-deploy@v1  
    Inputs:
      Artifacts:
        - MYARTIFACT
    Configuration:
      template: sam-template.yml
```

In the previous code, the build action (`BuildAction`) generates a `sam-template.yml` file, and then adds it to an output artifact called `MYARTIFACT`. A subsequent deploy action (`DeployAction`) specifies `MYARTIFACT` as an input, giving it access to the `sam-template.yml` file.

**Topics**
+ [

## Can I share artifacts without specifying them as outputs and inputs?
](#workflows-working-artifacts-share)
+ [

## Can I share artifacts between workflows?
](#workflows-working-artifacts-share-wf)
+ [

# Examples of artifacts
](workflows-working-artifacts-ex.md)
+ [

# Defining an output artifact
](workflows-working-artifacts-output.md)
+ [

# Defining an input artifact
](workflows-working-artifacts-refer.md)
+ [

# Referencing files in an artifact
](workflows-working-artifacts-refer-files.md)
+ [

# Downloading artifacts
](workflows-download-workflow-outputs.md)

## Can I share artifacts without specifying them as outputs and inputs?
<a name="workflows-working-artifacts-share"></a>

Yes, you can share artifacts between actions without specifying them in the `Outputs` and `Inputs` sections of your actions' YAML code. To do this, you must turn on compute sharing. For more information about compute sharing and how to specify artifacts when it is turned on, see [Sharing compute across actions](compute-sharing.md). 

**Note**  
Although the compute sharing feature allows you to simplify your workflow's YAML code by eliminating the need for the `Outputs` and `Inputs` sections, the feature has limitations that you should be aware of before you turn it on. For information about these limitations, see [Considerations for compute sharing](compute-sharing.md#compare-compute-sharing).

## Can I share artifacts between workflows?
<a name="workflows-working-artifacts-share-wf"></a>

No, you cannot share artifacts between different workflows; however, you can share artifacts between actions within the same workflow.

# Examples of artifacts
<a name="workflows-working-artifacts-ex"></a>

The following examples show how to output, input, and reference artifacts in the Amazon CodeCatalyst workflow definition file.

**Topics**
+ [

## Example: Outputting an artifact
](#workflows-working-artifacts-ex-basic)
+ [

## Example: Inputting an artifact generated by another action
](#workflows-working-artifacts-ex-ref)
+ [

## Example: Referencing files in multiple artifacts
](#workflows-working-artifacts-ex-ref-file)
+ [

## Example: Referencing a file in a single artifact
](#workflows-working-artifacts-ex-ref-file-one)
+ [

## Example: Referencing a file in an artifact when a WorkflowSource is present
](#workflows-working-artifacts-ex-ref-file-wf-source)
+ [

## Example: Referencing a file in an artifact when an action group is present
](#workflows-working-artifacts-ex-groups)

## Example: Outputting an artifact
<a name="workflows-working-artifacts-ex-basic"></a>

The following example shows how to output an artifact that includes two .jar files.

```
Actions:
  Build:
    Identifier: aws/build@v1
    Outputs:
      Artifacts:
        - Name: ARTIFACT1
          Files:
            - build-output/file1.jar
            - build-output/file2.jar
```

## Example: Inputting an artifact generated by another action
<a name="workflows-working-artifacts-ex-ref"></a>

The following example shows you how to output an artifact called `ARTIFACT4` in `BuildActionA`, and input it into `BuildActionB`.

```
Actions:
  BuildActionA:
    Identifier: aws/build@v1  
    Outputs:
      Artifacts:
        - Name: ARTIFACT4
          Files:
            - build-output/file1.jar
            - build-output/file2.jar
  BuildActionB:
    Identifier: aws/build@v1  
    Inputs:
      Artifacts:
        - ARTIFACT4
    Configuration:
```

## Example: Referencing files in multiple artifacts
<a name="workflows-working-artifacts-ex-ref-file"></a>

The following example shows you how to output two artifacts named `ART5` and `ART6` in `BuildActionC`, and then reference two files named `file5.txt` (in artifact `ART5`) and `file6.txt` (in artifact `ART6`) in `BuildActionD` (under `Steps`).

**Note**  
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

**Note**  
Although the example shows the `$CATALYST_SOURCE_DIR_ART5` prefix being used, you could omit it. This is because `ART5` is the *primary input*. To learn more about the primary input, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md). 

```
Actions:
  BuildActionC:
    Identifier: aws/build@v1  
    Outputs:
      Artifacts:
        - Name: ART5
          Files:
            - build-output/file5.txt
        - Name: ART6
          Files:
            - build-output/file6.txt
  BuildActionD:
    Identifier: aws/build@v1  
    Inputs:
      Artifacts:
        - ART5
        - ART6
    Configuration:
      Steps:
        - run: cd $CATALYST_SOURCE_DIR_ART5/build-output && cat file5.txt
        - run: cd $CATALYST_SOURCE_DIR_ART6/build-output && cat file6.txt
```

## Example: Referencing a file in a single artifact
<a name="workflows-working-artifacts-ex-ref-file-one"></a>

The following example shows you how to output one artifact named `ART7` in `BuildActionE`, and then reference `file7.txt` (in artifact `ART7`) in `BuildActionF` (under `Steps`).

Notice how the reference does not require the `$CATALYST_SOURCE_DIR_`*artifact-name* prefix in front of the `build-output` directory as it did in [Example: Referencing files in multiple artifacts](#workflows-working-artifacts-ex-ref-file). This is because there is only one item specified under `Inputs`.

**Note**  
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

```
Actions:
  BuildActionE:
    Identifier: aws/build@v1  
    Outputs:
      Artifacts:
        - Name: ART7
          Files:
            - build-output/file7.txt
  BuildActionF:
    Identifier: aws/build@v1  
    Inputs:
      Artifacts:
        - ART7
    Configuration:
      Steps:
        - run: cd build-output && cat file7.txt
```

## Example: Referencing a file in an artifact when a WorkflowSource is present
<a name="workflows-working-artifacts-ex-ref-file-wf-source"></a>

The following example shows you how to output one artifact named `ART8` in `BuildActionG`, and then reference `file8.txt` (in artifact `ART8`) in `BuildActionH` (under `Steps`).

Notice how the reference requires the `$CATALYST_SOURCE_DIR_`*artifact-name* prefix, as it did in [Example: Referencing files in multiple artifacts](#workflows-working-artifacts-ex-ref-file). This is because there are multiple items specified under `Inputs` (a source and an artifact), so you need the prefix to indicate where to look for the file.

**Note**  
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

```
Actions:
  BuildActionG:
    Identifier: aws/build@v1  
    Outputs:
      Artifacts:
        - Name: ART8
          Files:
            - build-output/file8.txt
  BuildActionH:
    Identifier: aws/build@v1  
    Inputs:
      Sources:
        - WorkflowSource
      Artifacts:
        - ART8
    Configuration:
      Steps:
        - run: cd $CATALYST_SOURCE_DIR_ART8/build-output && cat file8.txt
```

## Example: Referencing a file in an artifact when an action group is present
<a name="workflows-working-artifacts-ex-groups"></a>

The following example shows you how to output an artifact named `ART9` in `ActionGroup1`, `ActionI`, and then reference `file9.txt` (in artifact `ART9`) in `ActionJ`.

For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

```
Actions:
  ActionGroup1:
    Actions:
      ActionI:
        Identifier: aws/build@v1
        Outputs:
          Artifacts:
            - Name: ART9
              Files:
                - build-output/file9.yml
      ActionJ:
        Identifier: aws/cfn-deploy@v1 
        Inputs:
          Sources:
            - WorkflowSource
          Artifacts:
            - ART9
        Configuration:
          template: /artifacts/ActionGroup1@ActionJ/ART9/build-output/file9.yml
```

# Defining an output artifact
<a name="workflows-working-artifacts-output"></a>

Use the following instructions to define an artifact that you want an Amazon CodeCatalyst action to output. This artifact then becomes available for other actions to use.

**Note**  
Not all actions support output artifacts. To determine whether your action supports them, run through the visual editor instructions that follow, and see if the action includes an **Output artifacts** button on the **Outputs** tab. If yes, output artifacts are supported. 

------
#### [ Visual ]

**To define an output artifact using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that will produce the artifact.

1. Choose the **Outputs** tab.

1. Under **Artifacts**, choose **Add artifact**.

1. Choose **Add artifact**, and enter information into the fields, as follows.

    **Build artifact name** 

   Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (\$1). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

   For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

    **Files produced by build** 

   Specify the files that CodeCatalyst includes in the artifact that is output by the action. These files are generated by the workflow action when it runs, and are also available in your source repository. File paths can reside in a source repository or an artifact from a previous action, and are relative to the source repository or artifact root. You can use glob patterns to specify paths. Examples:
   + To specify a single file that is in the root of your build location or source repository location, use `my-file.jar`.
   + To specify a single file in a subdirectory, use `directory/my-file.jar` or `directory/subdirectory/my-file.jar`.
   + To specify all files, use `"**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
   + To specify all files and directories in a directory named `directory`, use `"directory/**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
   + To specify all files in a directory named `directory`, but not any of its subdirectories, use `"directory/*"`. 
**Note**  
If your file path includes one or more asterisks (`*`) or other special character, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

   For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).
**Note**  
You may need to add a prefix to the file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To define an output artifact using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a workflow action, add code similar to the following:

   ```
   action-name:
     Outputs:
       Artifacts:
         - Name: artifact-name
           Files:
             - file-path-1
             - file-path-2
   ```

   For more examples, see [Examples of artifacts](workflows-working-artifacts-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Defining an input artifact
<a name="workflows-working-artifacts-refer"></a>

If you want to use an artifact generated by another Amazon CodeCatalyst action, you must specify it as an input to the current action. You may be able to specify multiple artifacts as input—it depends on the action. For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.

**Note**  
You cannot reference artifacts from other workflows.

Use the following instructions to specify an artifact from another action as input to the current action.

**Prerequisite**  
Before you begin, make sure you have output the artifact from the other action. For more information, see [Defining an output artifact](workflows-working-artifacts-output.md). Outputting the artifact makes it available for other actions to use.

------
#### [ Visual ]

**To specify an artifact as input to an action (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action where you want to specify an artifact as input.

1. Choose **Inputs**.

1. In **Artifacts - optional**, do the following:

   Specify artifacts from previous actions that you want to provide as input to this action. These artifacts must already be defined as output artifacts in previous actions.

   If you do not specify any input artifacts, then you must specify at least one source repository under `action-name/Inputs/Sources`.

   For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).
**Note**  
If the **Artifacts - optional** drop-down list is unavailable (visual editor), or if you get errors in when you validate your YAML (YAML editor), it might be because the action only supports one input. In this case, try removing the source input.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To specify an artifact as input to an action (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the action where you want to specify the artifact as input, add code similar to the following:

   ```
   action-name:
     Inputs:
       Artifacts:
         - artifact-name
   ```

   For more examples, see [Examples of artifacts](workflows-working-artifacts-ex.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Referencing files in an artifact
<a name="workflows-working-artifacts-refer-files"></a>

If you have a file that resides within an artifact, and you need to refer to this file in one of your Amazon CodeCatalyst workflow actions, complete the following procedure.

**Note**  
See also [Referencing source repository files](workflows-sources-reference-files.md).

------
#### [ Visual ]

*Not available. Choose YAML to view the YAML instructions.*

------
#### [ YAML ]

**To reference files in an artifact (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the action where you want to reference a file, add code similar to the following:

   ```
   Actions:
     My-action:
       Inputs:
         Sources:
           - WorkflowSource
         Artifacts:
           - artifact-name  
       Configuration:
         template: artifact-path/path/to/file.yml
   ```

   In the previous code, replace:
   + *artifact-name* with the name of the artifact.
   + *artifact-path* with a value from the following table.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-working-artifacts-refer-files.html)

   For examples, see [Examples of artifacts](workflows-working-artifacts-ex.md).
**Note**  
You can omit the *artifact-path* and just specify the file path relative to the artifact root directory if:  
The action where you're including the reference only includes one item under `Inputs` (for example, it includes one input artifact and no source).
The file that you want to reference resides in the primary input. The *primary input* is either the `WorkflowSource`, or the first input artifact listed, if there is no `WorkflowSource`.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Downloading artifacts
<a name="workflows-download-workflow-outputs"></a>

You can download and inspect artifacts generated by your Amazon CodeCatalyst workflow actions for troubleshooting purposes. There are two types of artifact you can download:
+ **Source artifacts** – An artifact that contains a snapshot of the source repository content as it existed when the run started.
+ **Workflow artifacts** – An artifact defined in the `Outputs` property of your workflow's configuration file.

**To download artifacts output by the workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Under the workflow's name, choose **Runs**.

1. In **Run history**, in the **Run ID** column, choose a run. For example, `Run-95a4d`.

1. Under the run's name, choose **Artifacts**.

1. Next to an artifact, choose **Download**. An archive file downloads. Its file name consists of seven random characters.

1. Extract the archive using an archive extraction utility of your choice.

# Specifying the action version to use
<a name="workflows-action-versions"></a>

By default, when you add an action to a workflow, Amazon CodeCatalyst adds the full version to the workflow definition file using the format:

 `vmajor.minor.patch` 

For example:

```
My-Build-Action:
  Identifier: aws/build@v1.0.0
```

You can shorten the full version in the `Identifier` property so that the workflow always uses the latest minor or patch version of the action.

For example, if you specify:

```
My-CloudFormation-Action:
  Identifier: aws/cfn-deploy@v1.0
```

...and the latest patch version is `1.0.4`, then the action will use `1.0.4`. If a later version is released, say `1.0.5`, then the action will use `1.0.5`. If a minor version is released, say `1.1.0`, then the action will continue to use `1.0.5`.

For detailed instructions on specifying versions, see one of the following topics.

Use the following instructions to indicate which version of an action you want your workflow to use. You can specify the latest major or minor version, or a specific patch version.

We recommend using the latest minor or patch version of an action.

------
#### [ Visual ]

 *Not available. Choose YAML to view the YAML instructions.* 

------
#### [ YAML ]

**To configure a workflow to use the latest version of an action, or a specific patch version**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Find the action whose version you want to edit.

1. Find the action's `Identifier` property, and set the version to one of the following:
   + action-identifier@v*major* – Use this syntax to have the workflow use a specific major version, and allow the latest minor and patch versions to be chosen automatically.
   + action-identifier@v*major*.*minor* – Use this syntax to have the workflow use a specific minor version, and allow the latest patch version to be chosen automatically.
   + action-identifier@v*major*.*minor*.*patch* – Use this syntax to have the workflow use a specific patch version.
**Note**  
If you're not sure which versions are available, see [Listing the available action versions](workflows-action-versions-determine.md).
**Note**  
You cannot omit the major version.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Listing the available action versions
<a name="workflows-action-versions-determine"></a>

Use the following instructions to determine which versions of an action are available for you to use in a workflow.

------
#### [ Visual ]

**To determine which action versions are available**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. Find the action whose versions you want to view:

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose the name of any workflow, or create one. For information about creating a workflow, see [Creating a workflow](workflows-create-workflow.md).

   1. Choose **Edit**.

   1. At the top-left, choose **\$1 Actions** to open the action catalog.

   1. In the drop-down list, choose **Amazon CodeCatalyst** to view CodeCatalyst, CodeCatalyst Labs, and third-party actions, or choose **GitHub** to view curated GitHub Actions.

   1. Search for an action, and choose its name. Do not choose the plus sign (**\$1**).

      Details about the action appear.

1. In the action details dialog box, near the top-right, choose the **Versions** drop-down list to see a list of available versions of the action.

------
#### [ YAML ]

 *Not available. Choose 'visual' to view the visual editor instructions.* 

------

# Viewing an action's source code
<a name="workflows-view-source"></a>

You can view an action's source code to make sure it doesn't contain risky code, security vulnerabilities, or other defects.

Use the following instructions to view the source code of a [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc), [CodeCatalyst Labs](workflows-actions.md#workflows-actions-types-cc-labs), or [third-party](workflows-actions.md#workflows-actions-types-3p) action.

**Note**  
To view the source code of a [GitHub Action](workflows-actions.md#workflows-actions-types-github), go to the action's page in the [GitHub Marketplace](https://github.com/marketplace/actions). The page includes a link to the action's repository, where you can find the action's source code.

**Note**  
You cannot view the source code of the following CodeCatalyst actions: [build](build-workflow-actions.md), [test](test-workflow-actions.md), [GitHub Actions](integrations-github-action-add.md).

**Note**  
AWS does not support or guarantee the action code of GitHub Actions or third-party actions.<a name="workflows-to-view-source-cc"></a>

**To view an action's source code**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. Find the action whose code you want to view:

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose the name of any workflow, or create one. For information about creating a workflow, see [Creating a workflow](workflows-create-workflow.md).

   1. Choose **Edit**.

   1. At the top-left, choose **\$1 Actions** to open the action catalog.

   1. In the drop-down list, choose **Amazon CodeCatalyst** to view CodeCatalyst, CodeCatalyst Labs, and third-party actions.

   1. Search for an action, and choose its name. Do not choose the plus sign (**\$1**).

      Details about the action appear.

1. In the action details dialog box, near the bottom, choose **Download**.

   A page appears, showing the Amazon S3 bucket where the action's source code resides. For information about Amazon S3, see [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) in the *Amazon Simple Storage Service User Guide*.

1. Inspect the code to ensure it meets your expectations for quality and security. 

# Integrating with GitHub Actions
<a name="integrations-github-actions"></a>

A *GitHub Action* is a lot like a [CodeCatalyst action](workflows-actions.md#workflows-actions-types-cc), except that it was developed for use with GitHub workflows. For details about GitHub Actions, see the [GitHub Actions](https://docs.github.com/en/actions) documentation.

You can use GitHub Actions alongside native CodeCatalyst actions in a CodeCatalyst workflow.

There are two ways to add a GitHub Action to a CodeCatalyst workflow:
+ You can select the GitHub Action from a curated list in the CodeCatalyst console. Several popular GitHub Actions are available. For more information, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
+ If the GitHub Action that you want to use is not available in the CodeCatalyst console, you can add it using a **GitHub Actions** action.

  A ***GitHub Actions*** action is a *CodeCatalyst action* that wraps a GitHub Action and makes it compatible with CodeCatalyst workflows.

  Here is an example of a **GitHub Actions** action wrapping the [Super-Linter](https://github.com/marketplace/actions/super-linter) GitHub Action:

  ```
  Actions:
    GitHubAction:
      Identifier: aws/github-actions-runner@v1
      Configuration:
        Steps:
          - name: Lint Code Base
            uses: github/super-linter@v4
            env:
              VALIDATE_ALL_CODEBASE: "true"
              DEFAULT_BRANCH: main
  ```

  In the previous code, the CodeCatalyst **GitHub Actions** action (identified by `aws/github-actions-runner@v1`) wraps the Super-Linter action (identified by `github/super-linter@v4`), making it work in a CodeCatalyst workflow.

  For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).

All GitHub Actions—both curated and not—must be wrapped inside a **GitHub Actions** action (`aws/github-actions-runner@v1`), as shown in the previous example. The wrapper is required for the action to function properly. 

**Topics**
+ [

## How are GitHub Actions different from CodeCatalyst actions?
](#integrations-github-actions-how-different)
+ [

## Can GitHub Actions interact with other CodeCatalyst actions in the workflow?
](#integrations-github-actions-interactions.title)
+ [

## Which GitHub Actions can I use?
](#integrations-github-actions-supported)
+ [

## Limitations of GitHub Actions in CodeCatalyst
](#integrations-github-actions-limitations)
+ [

## How do I add a GitHub Action (high-level steps)?
](#integrations-github-actions-how-to)
+ [

## Does the GitHub Action run in GitHub?
](#integrations-github-actions-where-it-runs)
+ [

## Can I use GitHub workflows too?
](#integrations-github-actions-workflows-support.title)
+ [

## Runtime image used by the 'GitHub Actions' action
](#integrations-github-actions-runtime)
+ [

# Tutorial: Lint code using a GitHub Action
](integrations-github-action-tutorial.md)
+ [

# Adding the 'GitHub Actions' action
](integrations-github-action-add.md)
+ [

# Adding a curated GitHub Action
](integrations-github-action-add-curated.md)
+ [

# Exporting GitHub output parameters
](integrations-github-action-export.md)
+ [

# Referencing GitHub output parameters
](integrations-github-action-referencing.md)
+ [

# 'GitHub Actions' action YAML
](github-action-ref.md)

## How are GitHub Actions different from CodeCatalyst actions?
<a name="integrations-github-actions-how-different"></a>

GitHub Actions that are used inside a CodeCatalyst workflow do not have the same level of access and integration with AWS and CodeCatalyst features (such as [environments](deploy-environments.md) and [issues](issues.md)) that CodeCatalyst actions do.

## Can GitHub Actions interact with other CodeCatalyst actions in the workflow?
<a name="integrations-github-actions-interactions.title"></a>

Yes. For example, GitHub Actions can use variables produced by other CodeCatalyst actions as input, and can also share output parameters and artifacts with CodeCatalyst actions. For more information, see [Exporting GitHub output parameters](integrations-github-action-export.md) and [Referencing GitHub output parameters](integrations-github-action-referencing.md).

## Which GitHub Actions can I use?
<a name="integrations-github-actions-supported"></a>

You can use any GitHub Action available through the CodeCatalyst console, and any GitHub Action available in the [GitHub Marketplace](https://github.com/marketplace/actions). If you decide to use a GitHub Action from the Marketplace, keep in mind the following [limitations](#integrations-github-actions-limitations).

## Limitations of GitHub Actions in CodeCatalyst
<a name="integrations-github-actions-limitations"></a>
+ GitHub Actions cannot be used with the CodeCatalyst [Lambda compute type](workflows-working-compute.md#compute.types).
+ GitHub Actions run on the [November 2022](build-images.md#build.previous-image) runtime environment Docker image, which includes older tooling. For more information about the image and tooling, see [Specifying runtime environment images](build-images.md).
+ GitHub Actions that internally rely on the [`github` context](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) or that reference GitHub-specific resources won't work in CodeCatalyst. For example, the following actions won't work in CodeCatalyst:
  + Actions that attempt to add, change, or update GitHub resources. Examples include actions that update pull requests, or create issues in GitHub.
  + Almost all actions listed in [https://github.com/actions](https://github.com/actions).
+ GitHub Actions that are [Docker container actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#docker-container-actions) will work, but they must be run by the default Docker user (root). Do not run the action as user 1001. (At the time of writing, user 1001 works in GitHub, but not in CodeCatalyst.) For more information, see the [USER](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions#user) topic in [Dockerfile support for GitHub Actions](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions).

For a list of GitHub Actions available through the CodeCatalyst console, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).

## How do I add a GitHub Action (high-level steps)?
<a name="integrations-github-actions-how-to"></a>

The high-level steps to add a GitHub Action to a CodeCatalyst workflow are as follows:

1. In your CodeCatalyst project, you **create a workflow**. The workflow is where you define how to build, test, and deploy your application. For more information, see [Getting started with workflows](workflows-getting-started.md).

1. In the workflow, you **add a curated GitHub Action** or you **add the GitHub Actions** action.

1. You do one of the following:
   + If you chose to add a curated action, configure it. For more information, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
   + If you chose to add a non-curated action, within the **GitHub Actions** action, you **paste the GitHub Action’s YAML code**. You can find this code on the details page of your chosen GitHub Action in the [GitHub Marketplace](https://github.com/marketplace/actions). You will likely need to modify the code slightly to have it work in CodeCatalyst. For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).

1. (Optional) Within the workflow, **you add other actions** like the build and test actions. For more information, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md).

1. You **start the workflow** either manually or automatically through a trigger. The workflow runs the GitHub Action and any other actions in the workflow. For more information, see [Starting a workflow run manually](workflows-manually-start.md).

For detailed steps, see:
+ [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
+ [Adding the 'GitHub Actions' action](integrations-github-action-add.md).

## Does the GitHub Action run in GitHub?
<a name="integrations-github-actions-where-it-runs"></a>

No. The GitHub Action runs in CodeCatalyst, using CodeCatalyst’s [runtime environment image](workflows-working-compute.md).

## Can I use GitHub workflows too?
<a name="integrations-github-actions-workflows-support.title"></a>

No.

## Runtime image used by the 'GitHub Actions' action
<a name="integrations-github-actions-runtime"></a>

The CodeCatalyst **GitHub Actions** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Tutorial: Lint code using a GitHub Action
<a name="integrations-github-action-tutorial"></a>

In this tutorial, you add the [Super-Linter GitHub Action](https://github.com/marketplace/actions/super-linter) to an Amazon CodeCatalyst workflow. The Super-Linter action inspects code, finds areas where the code has errors, formatting issues, and suspicious constructs, and then outputs the results to the CodeCatalyst console). After adding the linter to your workflow, you run the workflow to lint a sample Node.js application (`app.js`). You then fix the reported problems and run the workflow again to see if the fixes worked.

**Tip**  
Consider using Super-Linter to lint YAML files, such as [CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html).

**Topics**
+ [

## Prerequisites
](#integrations-github-action-tutorial-prereqs)
+ [

## Step 1: Create a source repository
](#integrations-github-action-tutorial-create-source-repo)
+ [

## Step 2: Add an app.js file
](#integrations-github-action-tutorial-add-appjs)
+ [

## Step 3: Create a workflow that runs the Super-Linter action
](#integrations-github-action-tutorial-create-workflow)
+ [

## Step 4: Fix problems that the Super-Linter found
](#integrations-github-action-tutorial-fix-probs)
+ [

## Clean up
](#integrations-github-action-tutorial-cleanup)

## Prerequisites
<a name="integrations-github-action-tutorial-prereqs"></a>

Before you begin, you'll need:
+ A CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ An empty project in your CodeCatalyst space called `codecatalyst-linter-project`. Choose the **Start from scratch** option to create this project.

  ```
  ```

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).

## Step 1: Create a source repository
<a name="integrations-github-action-tutorial-create-source-repo"></a>

In this step, you create a source repository in CodeCatalyst. You'll use this repository to store the sample application source file, `app.js`, for this tutorial.

For more information about source repositories, see [Creating a source repository](source-repositories-create.md).

**To create a source repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-linter-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose **Add repository**, and then choose **Create repository**.

1. In **Repository name**, enter:

   ```
   codecatalyst-linter-source-repository
   ```

1. Choose **Create**.

## Step 2: Add an app.js file
<a name="integrations-github-action-tutorial-add-appjs"></a>

In this step, you add an `app.js` file to your source repository. The `app.js` contains function code that has a few mistakes that the linter will find.

**To add the app.js file**

1. In the CodeCatalyst console, choose your project, `codecatalyst-linter-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**.

1. From the list of source repositories, choose your repository, `codecatalyst-linter-source-repository`.

1. In **Files**, choose **Create file**.

1. In the text box, enter the following code:

   ```
   // const axios = require('axios')
   // const url = 'http://checkip.amazonaws.com/';
   let response;
   /**
    *
    * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
    * @param {Object} event - API Gateway Lambda Proxy Input Format
    *
    * Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html 
    * @param {Object} context
    *
    * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
    * @returns {Object} object - API Gateway Lambda Proxy Output Format
    *
    */
   exports.lambdaHandler = async (event, context) => {
     try {
       // const ret = await axios(url);
       response = {
         statusCode: 200,
         'body': JSON.stringify({
           message: 'hello world'
           // location: ret.data.trim()
         })
       }
     } catch (err) {
       console.log(err)
       return err
     }
   
       return response
   }
   ```

1. For **File name**, enter `app.js`. Keep the other default options.

1. Choose **Commit**.

   You have now created a file called `app.js`.

## Step 3: Create a workflow that runs the Super-Linter action
<a name="integrations-github-action-tutorial-create-workflow"></a>

In this step, you create a workflow that runs the Super-Linter action when you push code to your source repository. The workflow consists of the following building blocks, which you define in a YAML file:
+ **A trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ **A 'GitHub Actions' action** – On trigger, the **GitHub Actions** action runs the Super-Linter action, which in turn inspects all files in your source repository. If the linter finds an issue, the workflow action fails. 

**To create a workflow that runs the Super-Linter action**

1. In the CodeCatalyst console, choose your project, `codecatalyst-linter-project`.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 

1. Choose **Create workflow**.

1. For **Source repository**, choose `codecatalyst-linter-source-repository`.

1. For **Branch**, choose `main`.

1. Choose **Create**.

1. Delete the YAML sample code.

1. Add the following YAML:

   ```
   Name: codecatalyst-linter-workflow
   SchemaVersion: "1.0"
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     SuperLinterAction:
       Identifier: aws/github-actions-runner@v1
       Configuration:
         Steps:
           github-action-code
   ```

   In the preceding code, replace *github-action-code* with the Super-Linter action code, as instructed in the following steps of this procedure.

1. Go to the [Super-Linter page](https://github.com/marketplace/actions/super-linter) in the GitHub Marketplace.

1. Under `steps:`(lowercase), find the code and paste it into the CodeCatalyst workflow under `Steps:` (uppercase).

   Adjust the GitHub Action code to conform to CodeCatalyst standards, as shown in the following code.

   Your CodeCatalyst workflow now looks like this:

   ```
   Name: codecatalyst-linter-workflow
   SchemaVersion: "1.0"
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     SuperLinterAction:
       Identifier: aws/github-actions-runner@v1
       Configuration:
         Steps:
           - name: Lint Code Base
             uses: github/super-linter@v4
             env:
               VALIDATE_ALL_CODEBASE: "true"
               DEFAULT_BRANCH: main
   ```

1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing.

1. Choose **Commit**, enter a **Commit message**, select your `codecatalyst-linter-source-repository` **Repository**, and choose **Commit** again.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow.

**To view the workflow run in progress**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created: `codecatalyst-linter-workflow`.

1. In the workflow diagram, choose **SuperLinterAction**.

1. Wait for the action to fail. This failure is expected because the linter found problems in the code.

1. Leave the CodeCatalyst console open and go to [Step 4: Fix problems that the Super-Linter found](#integrations-github-action-tutorial-fix-probs).

## Step 4: Fix problems that the Super-Linter found
<a name="integrations-github-action-tutorial-fix-probs"></a>

The Super-Linter should have found problems in the `app.js` code, as well as the `README.md` file included in your source repository.

**To fix the problems the linter found**

1. In the CodeCatalyst console, choose the **Logs** tab, and then choose **Lint Code Base**.

   The logs that the Super-Linter action generated are displayed.

1. In the Super-Linter logs, scroll down to around line 90, where you find the start of the problems. They look similar to the following: 

   ```
   /github/workspace/hello-world/app.js:3:13: Extra semicolon.
   /github/workspace/hello-world/app.js:9:92: Trailing spaces not allowed.
   /github/workspace/hello-world/app.js:21:7: Unnecessarily quoted property 'body' found.
   /github/workspace/hello-world/app.js:31:1: Expected indentation of 2 spaces but found 4.
   /github/workspace/hello-world/app.js:32:2: Newline required at end of file but not found.
   ```

1. Fix `app.js` and `README.md` in your source repository and commit your changes. 
**Tip**  
To fix the `README.md`, add `markdown` to the code block, like this:  

   ```
   ```markdown
   Setup examples:
   ...
   ```
   ```

   Your changes start another workflow run automatically. Wait for the workflow to finish. If you fixed all the problems, the workflow should succeed.

## Clean up
<a name="integrations-github-action-tutorial-cleanup"></a>

Clean up in CodeCatalyst to remove traces of this tutorial from your environment.

**To clean up in CodeCatalyst**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Delete `codecatalyst-linter-source-repository`.

1. Delete `codecatalyst-linter-workflow`.

In this tutorial, you learned how to add the Super-Linter GitHub Action to a CodeCatalyst workflow in order to lint some code.

# Adding the 'GitHub Actions' action
<a name="integrations-github-action-add"></a>

A ***GitHub Actions*** action is a *CodeCatalyst action* that wraps a GitHub Action and makes it compatible with CodeCatalyst workflows.

For more information, see [Integrating with GitHub Actions](integrations-github-actions.md).

To add the **GitHub Actions** action to a workflow, follow these steps.

**Tip**  
For a tutorial that shows you how to use the **GitHub Actions** action, see [Tutorial: Lint code using a GitHub Action](integrations-github-action-tutorial.md).

------
#### [ Visual ]

**To add the 'GitHub Actions' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **GitHub**.

1. Search for the **GitHub Actions** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **GitHub Actions**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['GitHub Actions' action YAML](github-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'GitHub Actions' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **GitHub**.

1. Search for the **GitHub Actions** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **GitHub Actions**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['GitHub Actions' action YAML](github-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## 'GitHub Actions' action definition
<a name="integrations-github-action-add-definition"></a>

The **GitHub Actions** action is defined as a set of YAML properties inside your workflow definition file. For information about these properties, see ['GitHub Actions' action YAML](github-action-ref.md) in the [Workflow YAML definition](workflow-reference.md).

# Adding a curated GitHub Action
<a name="integrations-github-action-add-curated"></a>

A *curated GitHub Action* is a GitHub Action that is made available in the CodeCatalyst console, and serves as an example of how to use a GitHub Action inside a CodeCatalyst workflow.

Curated GitHub Actions are wrapped in the CodeCatalyst-authored [**GitHub Actions** action](integrations-github-action-add.md), identified by the `aws/github-actions-runner@v1` identifier. For example, here's what the curated GitHub Action, [TruffleHog OSS](https://github.com/marketplace/actions/trufflehog-oss), looks like: 

```
Actions:
  TruffleHogOSS_e8:
    Identifier: aws/github-actions-runner@v1
    Inputs:
      Sources:
        - WorkflowSource # This specifies that the action requires this Workflow as a source
    Configuration:
      Steps:
        - uses: trufflesecurity/trufflehog@v3.16.0
          with:
            path: ' ' # Required; description: Repository path
            base: ' ' # Required; description: Start scanning from here (usually main branch).
            head: ' ' # Optional; description: Scan commits until here (usually dev branch).
            extra_args: ' ' # Optional; description: Extra args to be passed to the trufflehog cli.
```

In the previous code, the CodeCatalyst **GitHub Actions** action (identified by `aws/github-actions-runner@v1`) wraps the TruffleHog OSS action (identified by `trufflesecurity/trufflehog@v3.16.0`), making it work in a CodeCatalyst workflow.

To configure this action, you would replace the empty strings under `with:` with your own values. For example:

```
Actions:
  TruffleHogOSS_e8:
    Identifier: aws/github-actions-runner@v1
    Inputs:
      Sources:
        - WorkflowSource # This specifies that the action requires this Workflow as a source
    Configuration:
      Steps:
        - uses: trufflesecurity/trufflehog@v3.16.0
          with:
            path: ./
            base: main # Required; description: Start scanning from here (usually main branch).
            head: HEAD # Optional; description: Scan commits until here (usually dev branch).
            extra_args: '‐‐debug ‐‐only-verified' # Optional; description: Extra args to be passed to the trufflehog cli.
```

To add a curated GitHub Action to a workflow, use the following procedure. For general information about using GitHub Actions in a CodeCatalyst workflow, see [Integrating with GitHub Actions](integrations-github-actions.md).

**Note**  
If you don't see your GitHub Action among the list of curated actions, you can still add it to your workflow using the **GitHub Actions** action. For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).

------
#### [ Visual ]

**To add a curated GitHub action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **GitHub**.

1. Browse or search for a GitHub Action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose the name of the GitHub Action. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs**, **Configuration**, and **Outputs** tabs, complete the fields according to your needs. For a description of each field, see the ['GitHub Actions' action YAML](github-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) available to the **GitHub Actions** action, as it appears in both the YAML and visual editors.

   For information about the configuration options available to the curated GitHub Action, see its documentation.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add a curated GitHub action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **GitHub**.

1. Browse or search for a GitHub Action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose the name of the GitHub Action. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each property available to the **GitHub Actions** action is provided in the ['GitHub Actions' action YAML](github-action-ref.md).

   For information about the configuration options available to the curated GitHub Action, see its documentation.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Exporting GitHub output parameters
<a name="integrations-github-action-export"></a>

You can use [GitHub output parameters](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter) in your CodeCatalyst workflows.

**Note**  
Another word for *output parameter* is *variable*. Because GitHub uses the term *output parameter* in its documentation, we'll use this term too.

Use the following instructions to export a GitHub output parameter from a GitHub Action so that it is available for use by other CodeCatalyst workflow actions.

**To export a GitHub output parameter**

1. Open a workflow and choose **Edit**. For more information, see [Creating a workflow](workflows-create-workflow.md).

1. In the **GitHub Actions** action that generates the output parameter that you want to export, add an `Outputs` section with an underlying `Variables` property that looks like this:

   ```
   Actions:
     MyGitHubAction:
       Identifier: aws/github-actions-runner@v1
       Outputs:
         Variables:
           - 'step-id_output-name'
   ```

   Replace:
   + *step-id* with value of the `id:` property in the GitHub action's `steps` section.
   + *output-name* with the name of the GitHub output parameter.

**Example**  
The following example shows you how to export a GitHub output parameter called `SELECTEDCOLOR`.

   ```
   Actions:
     MyGitHubAction:
       Identifier: aws/github-actions-runner@v1
       Outputs:
         Variables:
           - 'random-color-generator_SELECTEDCOLOR'
       Configuration:
         Steps:
           - name: Set selected color
             run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
             id: random-color-generator
   ```

# Referencing GitHub output parameters
<a name="integrations-github-action-referencing"></a>

Use the following instructions to reference a GitHub output parameter.

**To reference a GitHub output parameter**

1. Complete the steps in [Exporting GitHub output parameters](integrations-github-action-export.md).

   The GitHub output parameter is now available for use in other actions.

1. Note the output parameter's `Variables` value. It includes an underscore (\$1).

1. Refer to the output parameter using the following syntax:

   ```
   ${action-name.output-name}
   ```

   Replace:
   + *action-name* with the name of the CodeCatalyst **GitHub Action** that produces the output parameter (do not use the GitHub action's `name` or `id`).
   + *output-name* with the output parameter's `Variables` value you noted earlier.

   **Example**

   ```
   BuildActionB:
     Identifier: aws/build@v1
     Configuration:
       Steps:
         - Run: echo ${MyGitHubAction.random-color-generator_SELECTEDCOLOR}
   ```

**Example with context**  
The following example shows you how to set a `SELECTEDCOLOR` variable in `GitHubActionA`, output it, and then refer to it in `BuildActionB`.

   ```
   Actions:
     GitHubActionA:
       Identifier: aws/github-actions-runner@v1
       Configuration:
         Steps:
           - name: Set selected color
             run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
             id: random-color-generator
       Outputs:
         Variables:
         - 'random-color-generator_SELECTEDCOLOR'
         
      BuildActionB:
       Identifier: aws/build@v1
       Configuration:
         Steps:
           - Run: echo ${GitHubActionA.random-color-generator_SELECTEDCOLOR}
   ```

# 'GitHub Actions' action YAML
<a name="github-action-ref"></a>

The following is the YAML definition of the **GitHub Actions** action.

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

Choose a YAML property in the following code to see a description if it.

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.
  action-name:
    Identifier:  aws/github-actions-runner@v1
    DependsOn:
      - dependent-action-name-1
    Compute:
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Inputs:
      Sources:
        - source-name-1
        - source-name-2
      Artifacts:
        - artifact-name
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2   
    Outputs:
      Artifacts:
        - Name: output-artifact-1
          Files: 
            - github-output/artifact-1.jar
            - "github-output/build*"
        - Name: output-artifact-2
          Files:
            - github-output/artifact-2.1.jar
            - github-output/artifact-2.2.jar
      Variables:
        - variable-name-1
        - variable-name-2
      AutoDiscoverReports:
        Enabled: true | false
        ReportNamePrefix: AutoDiscovered
        IncludePaths:
          - "**/*"
        ExcludePaths:
          - node_modules/cdk/junit.xml
        SuccessCriteria:
          PassRate: percent
          LineCoverage: percent
          BranchCoverage: percent
          Vulnerabilities:
            Severity: CRITICAL|HIGH|MEDIUM|LOW|INFORMATIONAL
            Number: whole-number
      Reports:
        report-name-1:
          Format: format
          IncludePaths:
            - "*.xml"
          ExcludePaths:
            - report2.xml
            - report3.xml
          SuccessCriteria:
            PassRate: percent
            LineCoverage: percent
            BranchCoverage: percent
            Vulnerabilities:
              Severity: CRITICAL|HIGH|MEDIUM|LOW|INFORMATIONAL
              Number: whole-number
    Configuration      
      Steps:
        - github-actions-code
```

## action-name
<a name="github.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Corresponding UI: Configuration tab/*action-name*

## Identifier
<a name="github.identifier"></a>

(*action-name*/**Identifier**)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Use `aws/github-actions-runner@v1` for **GitHub Actions** actions.

Corresponding UI: Workflow diagram/*action-name*/**aws/github-actions-runner@v1** label

## DependsOn
<a name="github.depends-on"></a>

(*action-name*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="github.computename"></a>

(*action-name*/**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](compute-sharing.md).

Corresponding UI: *none*

## Fleet
<a name="github.computefleet"></a>

(*action-name*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/**Compute fleet - optional**

## Timeout
<a name="github.timeout"></a>

(*action-name*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Environment
<a name="github.environment"></a>

(*action-name*/**Environment**)

(Optional)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="github.environment.name"></a>

(*action-name*/Environment/**Name**)

(Required if [Environment](#github.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="github.environment.connections"></a>

(*action-name*/Environment/**Connections**)

(Optional)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Name
<a name="github.environment.connections.name"></a>

(*action-name*/Environment/Connections/**Name**)

(Required if [Connections](#github.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Role
<a name="github.environment.connections.role"></a>

(*action-name*/Environment/Connections/**Role**)

(Required if [Connections](#github.environment.connections) is included)

Specify the name of the IAM role that this action uses in order to access and operate in AWS services such as Amazon S3 and Amazon ECR. Make sure this role is added to your AWS account connection in your space. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

**Warning**  
Limit the permissions to those required by the **GitHub Action** action. Using a role with broader permissions might pose a security risk.

Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**

## Inputs
<a name="github.inputs"></a>

(*action-name*/**Inputs**)

(Optional)

The `Inputs` section defines the data that an action needs during a workflow run.

**Note**  
A maximum of four inputs (one source and three artifacts) are allowed per **GitHub Actions** action. Variables do not count towards this total.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see [Example: Referencing files in multiple artifacts](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file).

Corresponding UI: **Inputs** tab

## Sources
<a name="github.inputs.sources"></a>

(*action-name*/Inputs/**Sources**)

(Optional)

Specify the labels that represent the source repositories that will be needed by the action. Currently, the only supported label is `WorkflowSource`, which represents the source repository where your workflow definition file is stored.

If you omit a source, then you must specify at least one input artifact under `action-name/Inputs/Artifacts`.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="github.inputs.artifacts"></a>

(*action-name*/Inputs/**Artifacts**)

(Optional)

Specify artifacts from previous actions that you want to provide as input to this action. These artifacts must already be defined as output artifacts in previous actions.

If you do not specify any input artifacts, then you must specify at least one source repository under `action-name/Inputs/Sources`.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

**Note**  
If the **Artifacts - optional** drop-down list is unavailable (visual editor), or if you get errors in when you validate your YAML (YAML editor), it might be because the action only supports one input. In this case, try removing the source input.

Corresponding UI: Inputs tab/**Artifacts - optional**

## Variables - input
<a name="github.inputs.variables"></a>

(*action-name*/Inputs/**Variables**)

(Optional)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Inputs tab/**Variables - optional**

## Outputs
<a name="github.outputs"></a>

(*action-name*/**Outputs**)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts - output
<a name="github.outputs.artifacts"></a>

(*action-name*/Outputs/**Artifacts**)

(Optional)

Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (\$1). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/**Artifacts**

## Name
<a name="github.outputs.artifacts.name"></a>

(*action-name*/Outputs/Artifacts/**Name**)

(Required if [Artifacts - output](#github.outputs.artifacts) is included)

Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (\$1). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Build artifact name**

## Files
<a name="github.outputs.artifacts.files"></a>

(*action-name*/Outputs/Artifacts/**Files**)

(Required if [Artifacts - output](#github.outputs.artifacts) is included)

Specify the files that CodeCatalyst includes in the artifact that is output by the action. These files are generated by the workflow action when it runs, and are also available in your source repository. File paths can reside in a source repository or an artifact from a previous action, and are relative to the source repository or artifact root. You can use glob patterns to specify paths. Examples:
+ To specify a single file that is in the root of your build location or source repository location, use `my-file.jar`.
+ To specify a single file in a subdirectory, use `directory/my-file.jar` or `directory/subdirectory/my-file.jar`.
+ To specify all files, use `"**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
+ To specify all files and directories in a directory named `directory`, use `"directory/**/*"`. The `**` glob pattern indicates to match any number of subdirectories.
+ To specify all files in a directory named `directory`, but not any of its subdirectories, use `"directory/*"`. 

**Note**  
If your file path includes one or more asterisks (`*`) or other special character, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

**Note**  
You may need to add a prefix to the file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Outputs tab/Artifacts/Add artifact/**Files produced by build**

## Variables - output
<a name="github.outputs.variables"></a>

(*action-name*/Outputs/**Variables**)

(Optional)

Specify the variables that you want the action to export so that they are available for use by subsequent actions.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Outputs tab/Variables/**Add variable**

## variable-name-1
<a name="github.outputs.variables.name"></a>

(*action-name*/Outputs/Variables**variable-name-1**)

(Optional)

Specify the name of a variable that you want the action to export. This variable must already be defined in the `Inputs` or `Steps` section of the same action.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Outputs tab/Variables/Add variable/**Name**

## AutoDiscoverReports
<a name="github.outputs.autodiscover"></a>

(*action-name*/Outputs/**AutoDiscoverReports**)

(Optional)

Defines the configuration for the auto-discovery feature.

When you enable auto-discovery, CodeCatalyst searches all `Inputs` passed into the action as well as all files generated by the action itself, looking for test, code coverage, and software composition analysis (SCA) reports. For each report that is found, CodeCatalyst transforms it into a CodeCatalyst report. A *CodeCatalyst report* is a report that is fully integrated into the CodeCatalyst service and can be viewed and manipulated through the CodeCatalyst console.

**Note**  
By default, the auto-discover feature inspects all files. You can limit which files are inspected using the [IncludePaths](#github.reports.includepaths) or [ExcludePaths](#github.reports.excludepaths) properties. 

Corresponding UI: *none*

## Enabled
<a name="github.outputs.autodiscover.enabled"></a>

(*action-name*/Outputs/AutoDiscoverReports/**Enabled**)

(Optional)

Enable or disable the auto-discovery feature.

Valid values are `true` or `false`.

If `Enabled` is omitted, the default is `true`.

Corresponding UI: Outputs tab/Reports/**Automatically discover reports**

## ReportNamePrefix
<a name="github.outputs.autodiscover.reportnameprefix"></a>

(*action-name*/Outputs/AutoDiscoverReports/**ReportNamePrefix**)

(Required if [AutoDiscoverReports](#github.outputs.autodiscover) is included and enabled)

Specify a prefix that CodeCatalyst prepends to all the reports it finds in order to name their associated CodeCatalyst reports. For example, if you specify a prefix of `AutoDiscovered`, and CodeCatalyst auto-discovers two test reports, `TestSuiteOne.xml` and `TestSuiteTwo.xml`, then the associated CodeCatalyst reports will be named `AutoDiscoveredTestSuiteOne` and `AutoDiscoveredTestSuiteTwo`.

Corresponding UI: Outputs tab/Reports/Automatically discover reports/**Report prefix**

## IncludePaths
<a name="github.reports.includepaths"></a>

(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)

(Required if [AutoDiscoverReports](#github.outputs.autodiscover) is included and enabled, or if [Reports](#github.configuration.reports) is included)

Specify the files and file paths that CodeCatalyst includes when searching for raw reports. For example, if you specify `"/test/report/*"`, CodeCatalyst searches the entire [build image](build-images.md) used by the action looking for the `/test/report/*` directory. When it finds that directory, CodeCatalyst then looks for reports in that directory.

**Note**  
If your file path includes one or more asterisks (`*`) or other special characters, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

If this property is omitted, the default is `"**/*"`, meaning the search includes all files at all paths.

**Note**  
For manually configured reports, `IncludePaths` must be a glob pattern that matches a single file.

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/'Include/exclude paths'/**Include paths**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/'Include/exclude paths'/**Include paths**

## ExcludePaths
<a name="github.reports.excludepaths"></a>

(*action-name*/Outputs/AutoDiscoverReports/**ExcludePaths**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**ExcludePaths**)

(Optional)

Specify the files and file paths that CodeCatalyst excludes when searching for raw reports. For example, if you specify `"/test/my-reports/**/*"`, CodeCatalyst will not search for files in the `/test/my-reports/` directory. To ignore all files in a directory, use the `**/*` glob pattern.

**Note**  
If your file path includes one or more asterisks (`*`) or other special characters, enclose the path with double quotation marks (`""`). For more information about special characters, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/'Include/exclude paths'/**Exclude paths**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/'Include/exclude paths'/**Exclude paths**

## SuccessCriteria
<a name="github.reports.successcriteria"></a>

(*action-name*/Outputs/AutoDiscoverReports/**SuccessCriteria**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/**SuccessCriteria**)

(Optional)

Specify the success criteria for the test, code coverage, software composition analysis (SCA), and static analysis (SA) reports.

For more information, see [Configuring success criteria for reports](test-config-action.md#test.success-criteria).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/**Success criteria**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/**Success criteria**

## PassRate
<a name="github.reports.successcriteria.passrate"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**PassRate**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**PassRate**)

(Optional)

Specify the percentage of tests in a test report that must pass for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. The pass rate criteria are applied only to test reports. For more information about test reports, see [Test reports](test-workflow-actions.md#test-reports).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Pass rate**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Success criteria/**Pass rate**

## LineCoverage
<a name="github.reports.successcriteria.linecoverage"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**LineCoverage**)

(Optional)

Specify the percentage of lines in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Line coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Line coverage**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Success criteria/**Line coverage**

## BranchCoverage
<a name="github.reports.successcriteria.branchcoverage"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**BranchCoverage**)

(Optional)

Specify the percentage of branches in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: `50`, `60.5`. Branch coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Branch coverage**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Success criteria/**Branch coverage**

## Vulnerabilities
<a name="github.reports.successcriteria.vulnerabilities"></a>

(*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**)

Or

(*action-name*/Outputs/Reports/*report-name-1*/SuccessCriteria/**Vulnerabilities**)

(Optional)

Specify the maximum number and severity of vulnerabilities permitted in the SCA report for the associated CodeCatalyst report to be marked as passed. To specify vulnerabilities, you must specify:
+ The minimum severity of the vulnerabilities you want to include in the count. Valid values, from most to least severe, are: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.

  For example, if you choose `HIGH`, then `HIGH` and `CRITICAL` vulnerabilities will be tallied.
+ The maximum number of vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Vulnerabilities criteria are applied only to SCA reports. For more information about SCA reports, see [Software composition analysis reports](test-workflow-actions.md#test-sca-reports).

To specify the minimum severity, use the `Severity` property. To specify the maximum number of vulnerabilities, use the `Number` property.

For more information about SCA reports, see [Quality report types](test-workflow-actions.md#test-reporting).

Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Vulnerabilities**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Success criteria/**Vulnerabilities**

## Reports
<a name="github.configuration.reports"></a>

(*action-name*/Outputs/**Reports** )

(Optional)

A section that specifies the configuration for test reports.

Corresponding UI: Outputs tab/**Reports**

## report-name-1
<a name="github.configuration.reports.report-name-1"></a>

(*action-name*/Outputs/Reports/**report-name-1** )

(Required if [Reports](#github.configuration.reports) is included)

The name you want to give to the CodeCatalyst report that will be generated from your raw reports.

Corresponding UI: Outputs tab/Reports/Manually configure reports/**Report name**

## Format
<a name="github.configuration.reports.name.testresults.format"></a>

(*action-name*/Outputs/Reports/*report-name-1*/**Format**)

(Required if [Reports](#github.configuration.reports) is included)

Specify the file format that you're using for your reports. Possible values are as follows.
+ For test reports:
  + For Cucumber JSON, specify **Cucumber** (visual editor) or `CUCUMBERJSON` (YAML editor).
  + For JUnit XML, specify **JUnit** (visual editor) or `JUNITXML` (YAML editor).
  + For NUnit XML, specify **NUnit** (visual editor) or `NUNITXML` (YAML editor).
  + For NUnit 3 XML, specify **NUnit3** (visual editor) or `NUNIT3XML` (YAML editor).
  + For Visual Studio TRX, specify **Visual Studio TRX** (visual editor) or `VISUALSTUDIOTRX` (YAML editor).
  + For TestNG XML, specify **TestNG** (visual editor) or `TESTNGXML` (YAML editor).
+ For code coverage reports:
  + For Clover XML, specify **Clover** (visual editor) or `CLOVERXML` (YAML editor).
  + For Cobertura XML, specify **Cobertura** (visual editor) or `COBERTURAXML` (YAML editor).
  + For JaCoCo XML, specify **JaCoCo** (visual editor) or `JACOCOXML` (YAML editor).
  + For SimpleCov JSON generated by [simplecov](https://github.com/simplecov-ruby/simplecov), not [simplecov-json](https://github.com/vicentllongo/simplecov-json), specify **Simplecov** (visual editor) or `SIMPLECOV` (YAML editor).
+ For software composition analysis (SCA) reports:
  + For SARIF, specify **SARIF** (visual editor) or `SARIFSCA` (YAML editor).

Corresponding UI: Outputs tab/Reports/Manually configure reports/Add report/*report-name-1*/**Report type** and **Report format**

## Configuration
<a name="github.configuration"></a>

(*action-name*/**Configuration**)

(Required) A section where you can define the configuration properties of the action. 

Corresponding UI: **Configuration** tab

## Steps
<a name="github.configuration.steps"></a>

(*action-name*/Configuration/**Steps**)

(Required) 

Specify your GitHub Action code as it appears on the action's details page in [GitHub Marketplace](https://github.com/marketplace). Add the code following these guidelines:

1. Paste the code from the GitHub Action’s `steps:` section into the `Steps:` section of the CodeCatalyst workflow. The code starts with a dash (-) and looks similar to the following.

   GitHub code to paste:

   ```
   - name: Lint Code Base
     uses: github/super-linter@v4
     env:
       VALIDATE_ALL_CODEBASE: false
       DEFAULT_BRANCH: master
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   ```

1. Review the code you just pasted and modify it as necessary so that it conforms to CodeCatalyst standards. For example, with the preceding code block, you might remove the code in *red italics*, and add the code in **bold**.

   CodeCatalyst workflow yaml:

   ```
   Steps:      
      - name: Lint Code Base
        uses: github/super-linter@v4
        env:
          VALIDATE_ALL_CODEBASE: false
          DEFAULT_BRANCH: mastermain
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   ```

1. For additional code that’s included with the GitHub Action but does not exist inside the `steps:` section, add it to the CodeCatalyst workflow using CodeCatalyst-equivalent code. You can review the [Workflow YAML definition](workflow-reference.md) to gain insight into how you might port your GitHub code to CodeCatalyst. Detailed migration steps are outside the scope of this guide.

Here is an example of how to specify file paths in a **GitHub Actions** action:

```
Steps:
  - name: Lint Code Base
    uses: github/super-linter@v4
    ...
  - run: cd /sources/WorkflowSource/MyFolder/  && cat file.txt
  - run: cd /artifacts/MyGitHubAction/MyArtifact/MyFolder/  && cat file2.txt
```

For more information about specifying file paths, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

Corresponding UI: Configuration tab/**GitHub Actions YAML**

# Configuring compute and runtime images
<a name="workflows-working-compute"></a>

In a CodeCatalyst workflow, you can specify the compute and runtime environment image that CodeCatalyst uses to run workflow actions.

*Compute* refers to the computing engine (the CPU, memory, and operating system) managed and maintained by CodeCatalyst to run workflow actions.

**Note**  
If compute is defined as a property of the workflow, then it can't be defined as a property of any action in that workflow. Similarly, if compute is defined as a property of any action, it can't be defined in the workflow.

A *runtime environment image* is a Docker container within which CodeCatalyst runs workflow actions. The Docker container runs on top of your chosen compute platform, and includes an operating system and extra tools that a workflow action might need, such as the AWS CLI, Node.js, and .tar.

**Topics**
+ [

## Compute types
](#compute.types)
+ [

## Compute fleets
](#compute.fleets)
+ [

## On-demand fleet properties
](#compute.on-demand)
+ [

## Provisioned fleet properties
](#compute.provisioned-fleets)
+ [

# Creating a provisioned fleet
](projects-create-compute-resource.md)
+ [

# Editing a provisioned fleet
](edit-compute-resource.md)
+ [

# Deleting a provisioned fleet
](delete-compute-resource.md)
+ [

# Assigning a fleet or compute to an action
](workflows-assign-compute-resource.md)
+ [

# Sharing compute across actions
](compute-sharing.md)
+ [

# Specifying runtime environment images
](build-images.md)

## Compute types
<a name="compute.types"></a>

CodeCatalyst offers the following compute types:
+ Amazon EC2
+ AWS Lambda

Amazon EC2 offers optimized flexibility during action runs and Lambda offers optimized action start-up speeds. Lambda supports faster workflow action runs due to a lower start-up latency. Lambda allows you to run basic workflows that can build, test, and deploy serverless applications with common runtimes. These runtimes include Node.js, Python, Java, .NET, and Go. However, there are some use-cases which Lambda does not support, and if they impact you, use the Amazon EC2 compute type:
+ Lambda doesn't support runtime environment images from a specified registry.
+ Lambda doesn't support tools that require root permissions. For tools such as `yum` or `rpm`, use the Amazon EC2 compute type or other tools that don't require root permissions.
+ Lambda doesn't support Docker builds or runs. The following actions that use Docker images are not supported: Deploy AWS CloudFormation stack, Deploy to Amazon ECS, Amazon S3 publish, AWS CDK bootstrap, AWS CDK deploy, AWS Lambda invoke , and GitHub Actions. Docker-based GitHub Actions that are running within CodeCatalyst GitHub Actions action are also not supported with Lambda compute. You can use alternatives that don’t require root permissions, such as Podman.
+ Lambda doesn't support writing to files outside `/tmp`. When configuring your workflow actions, you can reconfigure your tools to install or write to `/tmp`. If you have a build action that installs `npm`, make sure you configure it to install to `/tmp`.
+ Lambda doesn't support runtimes longer than 15 minutes.

## Compute fleets
<a name="compute.fleets"></a>

CodeCatalyst offers the following compute fleets:
+ On-demand fleets
+ Provisioned fleets

With on-demand fleets, when a workflow action starts, the workflow provisions the resources it needs. The machines are destroyed when the action finishes. You only pay for the number of minutes that you're running your actions. On-demand fleets are fully managed, and includes automatic scaling capabilities to handle spikes in demand.

CodeCatalyst also offers provisioned fleets which contain machines powered by Amazon EC2 that are maintained by CodeCatalyst. With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. With provisioned fleets, your machines are always running and will incur costs as long they're provisioned.

In order to create, update, or delete a fleet, you must have the **Space administrator** role or the **Project administrator** role.

## On-demand fleet properties
<a name="compute.on-demand"></a>

CodeCatalyst provides the following on-demand fleets:

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-working-compute.html)

**Note**  
The specifications for on-demand fleets will vary depending on your billing tier. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing).

If no fleet is selected, CodeCatalyst uses `Linux.x86-64.Large`.

## Provisioned fleet properties
<a name="compute.provisioned-fleets"></a>

A provisioned fleet contains the following properties: 

**Operating system**  
The operating system. The following operating systems are available:  
+ Amazon Linux 2
+ Windows Server 2022
**Note**  
Windows fleets are only supported in the build action. Other actions do not currently support Windows.

**Architecture**  
The processor architecture. The following architectures are available:  
+ x86\$164
+ Arm64

**Machine type**  
The machine type for each instance. The following machine types are available:      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-working-compute.html)

**Capacity**  
The initial number of machines allocated to the fleet, which defines the number of actions that can run in parallel.

**Scaling mode**  
Defines the behavior when the number of actions exceeds the fleet capacity.    
**Provision additional capacity on demand**  
Additional machines are set up on demand which automatically scale up in response to new actions running, and then scale down to the base capacity as actions finish. This can incur additional costs, since you pay by the minute for each machine running.  
**Wait until additional fleet capacity is available**  
Action runs are placed in a queue until a machine is available. This limits additional costs because no additional machines are allocated.

# Creating a provisioned fleet
<a name="projects-create-compute-resource"></a>

Use the following instructions to create a provisioned fleet.

**Note**  
Provisioned fleets will be deactivated after 2 weeks of inactivity. If used again, they will be re-activated automatically, but this re-activation may cause a latency to occur.

**To create a provisioned fleet**

1. In the navigation pane, choose **CI/CD**, and then choose **Compute**.

1. Choose **Create provisioned fleet**.

1. In the **Provisioned fleet name** text field, enter a name for your fleet.

1. From the **Operating system** drop-down menu, choose the operating system.

1. From the **Machine type** drop-down menu, choose the machine type for your machine.

1. In the **Capacity** text field, enter the maximum number of machines in the fleet.

1. From the **Scaling mode** drop-down menu, choose the desired overflow behavior. For more information about these fields, see [Provisioned fleet properties](workflows-working-compute.md#compute.provisioned-fleets).

1. Choose **Create**.

After creating the provisioned fleet, you are ready to assign it to an action. For more information, see [Assigning a fleet or compute to an action](workflows-assign-compute-resource.md).

# Editing a provisioned fleet
<a name="edit-compute-resource"></a>

Use the following instructions to edit a provisioned fleet.

**Note**  
Provisioned fleets will be deactivated after 2 weeks of inactivity. If used again, they will be re-activated automatically, but this re-activation may cause a latency to occur.

**To edit a provisioned fleet**

1. In the navigation pane, choose **CI/CD**, and then choose **Compute**.

1. In the **Provisioned fleet** list, choose the fleet you want to edit.

1. Choose **Edit**.

1. In the **Capacity** text field, enter the maximum number of machines in the fleet.

1. From the **Scaling mode** drop-down menu, choose the desired overflow behavior. For more information about these fields, see [Provisioned fleet properties](workflows-working-compute.md#compute.provisioned-fleets).

1. Choose **Save**.

# Deleting a provisioned fleet
<a name="delete-compute-resource"></a>

Use the following instructions to delete a provisioned fleet.

**To delete a provisioned fleet**
**Warning**  
Before deleting a provisioned fleet, remove it from all actions by deleting the `Fleet` property from the action's YAML code. Any action that continues to reference a provisioned fleet after it is deleted will fail the next time the action runs.

1. In the navigation pane, choose **CI/CD**, and then choose **Compute**.

1. In the **Provisioned fleet** list, choose the fleet you want to delete.

1. Choose **Delete**.

1. Enter **delete** to confirm the deletion.

1. Choose **Delete**.

# Assigning a fleet or compute to an action
<a name="workflows-assign-compute-resource"></a>

By default, workflow actions use the `Linux.x86-64.Large` on-demand fleet with an Amazon EC2 compute type. To use a provisioned fleet instead, or to use a different on-demand fleet, such as `Linux.x86-64.2XLarge`, use the following instructions.

------
#### [ Visual ]

**Before you begin**
+ If you want to assign a provisioned fleet, you must first create the provisioned fleet. For more information, see [Creating a provisioned fleet](projects-create-compute-resource.md).

**To assign a provisioned fleet or different fleet type to an action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that you want to assign your provisioned fleet or new fleet type to.

1. Choose the **Configuration** tab.

1. In **Compute fleet**, do the following:

   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](workflows-working-compute.md#compute.on-demand).

   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](workflows-working-compute.md#compute.provisioned-fleets).

   If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**Before you begin**
+ If you want to assign a provisioned fleet, you must first create the provisioned fleet. For more information, see [Creating a provisioned fleet](projects-create-compute-resource.md).

**To assign a provisioned fleet or different fleet type to an action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Find the action that you want to assign your provisioned fleet or new fleet type to.

1. In the action, add a `Compute` property and set `Fleet` to the name of your fleet or on-demand fleet type. For more information, see the description of the `Fleet` property in the [Build and test actions YAML](build-action-ref.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Sharing compute across actions
<a name="compute-sharing"></a>

By default, actions in a workflow run on separate instances in a [fleet](workflows-working-compute.md#compute.fleets). This behavior provides actions with isolation and predictability on the state of inputs. The default behavior requires explicit configuration to share context such as files and variables between actions. 

Compute sharing is a capability that allows you to run all the actions in a workflow on the same instance. Using compute sharing can provide faster workflow runtimes because less time is spent provisioning instances. You can also share files (artifacts) between actions without additional workflow configuration.

When a workflow is run using compute sharing, an instance in the default or specified fleet is reserved for the duration of all actions in that workflow. When the workflow run completes, the instance reservation is released.

**Topics**
+ [

## Running multiple actions on shared compute
](#how-to-compute-share)
+ [

## Considerations for compute sharing
](#compare-compute-sharing)
+ [

## Turning on compute sharing
](#compute-sharing-steps)
+ [

## Examples
](#compute-sharing-examples)

## Running multiple actions on shared compute
<a name="how-to-compute-share"></a>

You can use the `Compute` attribute in the definition YAML at the workflow level to specify both the fleet and compute sharing properties of actions. You can also configure compute properties using the visual editor in CodeCatalyst. To specify a fleet, set the name of an existing fleet, set the compute type to **EC2**, and turn on compute sharing.

**Note**  
Compute sharing is only supported if the compute type is set to **EC2**, and it's not supported for the Windows Server 2022 operating system. For more information about compute fleets, compute types, and properties, see [Configuring compute and runtime images](workflows-working-compute.md).

**Note**  
If you're on the Free tier and you specify the `Linux.x86-64.XLarge` or `Linux.x86-64.2XLarge` fleet manually in the workflow definition YAML, the action will still run on the default fleet (`Linux.x86-64.Large`). For more information about compute availability and pricing, see the [table for the tiers options](https://codecatalyst.aws/explore/pricing). 

When compute sharing is turned on, the folder containing the workflow source is automatically copied across actions. You don't need to configure output artifacts and reference them as input artifacts throughout a workflow definition (YAML file). As a workflow author, you need to wire up environment variables using inputs and outputs, just as you would without using compute sharing. If you want to share folders between actions outside the workflow source, consider file caching. For more information, see [Sharing artifacts and files between actions](workflows-working-artifacts.md) and [Caching files between workflow runs](workflows-caching.md).

The source repository where your workflow definition file resides is identified by the label `WorkflowSource`. While using compute sharing, the workflow source is downloaded in the first action that references it and automatically made available for subsequent actions in the workflow run to use. Any changes made to the folder containing the workflow source by an action, such as adding, modifying, or removing files, are also visible in the subsequent actions in the workflow. You can reference files that reside in the workflow source folder in any of your workflow actions, just as you can without using compute sharing. For more information, see [Referencing source repository files](workflows-sources-reference-files.md).

**Note**  
Compute sharing workflows need to specify a strict sequence of actions, so parallel actions can't be set. While output artifacts can be configured at any action in the sequence, input artifacts aren't supported.

## Considerations for compute sharing
<a name="compare-compute-sharing"></a>

You can run workflows with compute sharing in order to accelerate workflow runs and share context between actions in a workflow that use the same instance. Consider the following to determine whether using compute sharing is appropriate for your scenario:


|   | Compute sharing | Without compute sharing | 
| --- | --- | --- | 
|  Compute type  |  Amazon EC2  |  Amazon EC2, AWS Lambda  | 
|  Instance provisioning  |  Actions run on same instance  |  Actions run on separate instances  | 
|  Operating system  |  Amazon Linux 2  |  Amazon Linux 2, Windows Server 2022 (build action only)  | 
|  Referencing files  |  `$CATALYST_SOURCE_DIR_WorkflowSource`, `/sources/WorkflowSource/`  |  `$CATALYST_SOURCE_DIR_WorkflowSource`, `/sources/WorkflowSource/`  | 
|  Workflow structure  |  Actions can only run sequentially  |  Actions can run parallel  | 
|  Accessing data across workflow actions  |  Access cached workflow source (`WorkflowSource`)  |  Access outputs of shared artifacts (requires additional configuration)  | 

## Turning on compute sharing
<a name="compute-sharing-steps"></a>

Use the following instruction to turn on compute sharing for a workflow.

------
#### [ Visual ]

**To turn on compute sharing using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow.

1. Choose **Edit**.

1. Choose **Visual**.

1. Choose **Workflow properties**.

1. From the **Compute type** dropdown menu, choose **EC2**.

1. (Optional) From the **Compute fleet - optional** dropdown menu, choose a fleet you want to use to run workflow actions. You can choose an on-demand fleet or create and choose a provisioned fleet. For more information, see [Creating a provisioned fleet](projects-create-compute-resource.md) and [Assigning a fleet or compute to an action](workflows-assign-compute-resource.md) 

1. Switch the toggle to turn on compute sharing and have actions in the workflow run on the same fleet.

1. (Optional) Choose the run mode for the workflow. For more information, see [Configuring the queuing behavior of runs](workflows-configure-runs.md).

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To turn on compute sharing using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow.

1. Choose **Edit**.

1. Choose **YAML**.

1. Turn on compute sharing setting the `SharedInstance` field to `TRUE` and `Type` to `EC2`. Set `Fleet` to a compute fleet you want to use to run workflow actions. You can choose an on-demand fleet or create and choose a provisioned fleet. For more information, see [Creating a provisioned fleet](projects-create-compute-resource.md) and [Assigning a fleet or compute to an action](workflows-assign-compute-resource.md)

   In a workflow YAML, add code similar to the following:

   ```
     Name: MyWorkflow
     SchemaVersion: "1.0"
     Compute: # Define compute configuration.
       Type: EC2
       Fleet: MyFleet # Optionally, choose an on-demand or provisioned fleet.
       SharedInstance: true # Turn on compute sharing. Default is False.
     Actions:
       BuildFirst:
         Identifier: aws/build@v1
         Inputs:
           Sources:
             - WorkflowSource
         Configuration:
           Steps:
             - Run: ...
             ...
   ```

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## Examples
<a name="compute-sharing-examples"></a>

**Topics**
+ [

### Example: Amazon S3 Publish
](#compute-share-s3)

### Example: Amazon S3 Publish
<a name="compute-share-s3"></a>

The following workflow examples show how to perform the Amazon Amazon S3 Publish action in two ways: first using input artifacts and then using compute sharing. With compute sharing, the input artifacts aren't needed since you can access the cached `WorkflowSource`. Additionally, the output artifact in the Build action is no longer needed. The S3 Publish action is configured to use the explicit `DependsOn` property to maintain sequential actions; the Build action must run successfully in order for the S3 Publish action to run.
+ Without compute sharing, you need to use input artifacts and share the outputs with subsequent actions:

  ```
  Name: S3PublishUsingInputArtifact
  SchemaVersion: "1.0"
  Actions:
    Build:
      Identifier: aws/build@v1
      Outputs:
        Artifacts:
          - Name: ArtifactToPublish
            Files: [output.zip]
      Inputs:
        Sources:
          - WorkflowSource
      Configuration:
        Steps:
          - Run: ./build.sh # Build script that generates output.zip
    PublishToS3:
      Identifier: aws/s3-publish@v1
      Inputs:
        Artifacts:
        - ArtifactToPublish
      Environment:
        Connections:
          - Role: codecatalyst-deployment-role
            Name: dev-deployment-role
        Name: dev-connection
      Configuration:
        SourcePath: output.zip
        DestinationBucketName: amzn-s3-demo-bucket
  ```
+ When using compute sharing by setting `SharedInstance` to `TRUE`, you can run multiple actions on the same instance and share artifacts by specifying a single workflow source. Input artifacts aren't required and can't be specified:

  ```
  Name: S3PublishUsingComputeSharing
  SchemaVersion: "1.0"
  Compute: 
    Type: EC2
    Fleet: dev-fleet
    SharedInstance: TRUE
  Actions:
    Build:
      Identifier: aws/build@v1
      Inputs:
        Sources:
          - WorkflowSource
      Configuration:
        Steps:
          - Run: ./build.sh # Build script that generates output.zip
    PublishToS3:
      Identifier: aws/s3-publish@v1
      DependsOn: 
        - Build
      Environment:
        Connections:
          - Role: codecatalyst-deployment-role
            Name: dev-deployment-role
        Name: dev-connection
      Configuration:
        SourcePath: output.zip
        DestinationBucketName: amzn-s3-demo-bucket
  ```

# Specifying runtime environment images
<a name="build-images"></a>

A *runtime environment image* is a Docker container within which CodeCatalyst runs workflow actions. The Docker container runs on top of your chosen compute platform, and includes an operating system and extra tools that a workflow action might need, such as the AWS CLI, Node.js, and .tar.

By default, workflow actions will run on one of the [active images](#build-curated-images) that are supplied and maintained by CodeCatalyst. Only build and test actions support custom images. For more information, see [Assigning a custom runtime environment Docker image to an action](#build-images-specify).

**Topics**
+ [

## Active images
](#build-curated-images)
+ [

## What if an active image doesn't include the tools I need?
](#build-images-more-tools)
+ [

## Assigning a custom runtime environment Docker image to an action
](#build-images-specify)
+ [

## Examples
](#workflows-working-custom-image-ex)

## Active images
<a name="build-curated-images"></a>

*Active images* are runtime environment images that are fully supported by CodeCatalyst and include preinstalled tooling. There are currently two sets of active images: one released in March 2024, and another released in November 2022.

Whether an action uses a March 2024 or November 2022 image depends on the action:
+ Build and test actions that are added to a workflow on or after March 26, 2024 will include a `Container` section in their YAML definition that explicitly specifies a [March 2024 image](#build.default-image). You can optionally remove the `Container` section to revert back to the [November 2022 image](#build.previous-image).
+ Build and test actions that were added to a workflow prior to March 26, 2024 will *not* include a `Container` section in their YAML definition, and consequently will use a [November 2022 image](#build.previous-image). You can keep the November 2022 image, or you can upgrade it. To upgrade the image, open the action in the visual editor, choose the **Configuration** tab, and then select the March 2024 image from the **Runtime environment docker image** drop-down list. This selection will add a `Container` section to the action's YAML definition that is populated with the appropriate March 2024 image.
+ All other actions will use either a [November 2022 image](#build.previous-image) or a [March 2024 image](#build.default-image). For more information, see the action's documentation. 

**Topics**
+ [

### March 2024 images
](#build.default-image)
+ [

### November 2022 images
](#build.previous-image)

### March 2024 images
<a name="build.default-image"></a>

The March 2024 images are the latest images provided by CodeCatalyst. There is one March 2024 image per compute type/fleet combination.

The following table shows the tools installed on each March 2024 image.


**March 2024 image tools**  

| Tool | CodeCatalyst Amazon EC2 for Linux x86\$164 - `CodeCatalystLinux_x86_64:2024_03` | CodeCatalyst Lambda for Linux x86\$164 - `CodeCatalystLinuxLambda_x86_64:2024_03` | CodeCatalyst Amazon EC2 for Linux Arm64 - `CodeCatalystLinux_Arm64:2024_03` | CodeCatalyst Lambda for Linux Arm64 - `CodeCatalystLinuxLambda_Arm64:2024_03` | 
| --- | --- | --- | --- | --- | 
| AWS CLI | 2.15.17 | 2.15.17 | 2.15.17 | 2.15.17 | 
| AWS Copilot CLI | 1.32.1 | 1.32.1 | 1.32.1 | 1.32.1 | 
| Docker | 24.0.9 | N/A | 24.0.9 | N/A | 
| Docker Compose | 2.23.3 | N/A | 2.23.3 | N/A | 
| Git | 2.43.0 | 2.43.0 | 2.43.0 | 2.43.0 | 
| Go | 1.21.5 | 1.21.5 | 1.21.5 | 1.21.5 | 
| Gradle | 8.5 | 8.5 | 8.5 | 8.5 | 
| Java | Corretto17 | Corretto17 | Corretto17 | Corretto17 | 
| Maven | 3.9.6 | 3.9.6 | 3.9.6 | 3.9.6 | 
| Node.js | 18.19.0 | 18.19.0 | 18.19.0 | 18.19.0 | 
| npm | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.3 | 
| Python | 3.9.18 | 3.9.18 | 3.9.18 | 3.9.18 | 
| Python3 | 3.11.6 | 3.11.6 | 3.11.6 | 3.11.6 | 
| pip | 22.3.1 | 22.3.1 | 22.3.1 | 22.3.1 | 
| .NET | 8.0.100 | 8.0.100 | 8.0.100 | 8.0.100 | 

### November 2022 images
<a name="build.previous-image"></a>

There is one November 2022 image per compute type/fleet combination. There is also a November 2022 Windows image available with the build action if you've configured a [provisioned fleet](workflows-working-compute.md#compute.fleets).

The following table shows the tools installed on each November 2022 image.


**November 2022 image tools**  

| Tool | CodeCatalyst Amazon EC2 for Linux x86\$164 - `CodeCatalystLinux_x86_64:2022_11` | CodeCatalyst Lambda for Linux x86\$164 - `CodeCatalystLinuxLambda_x86_64:2022_11` | CodeCatalyst Amazon EC2 for Linux Arm64 - `CodeCatalystLinux_Arm64:2022_11` | CodeCatalyst Lambda for Linux Arm64 - `CodeCatalystLinuxLambda_Arm64:2022_11` | CodeCatalyst Amazon EC2 for Windows x86\$164 - `CodeCatalystWindows_x86_64:2022_11` | 
| --- | --- | --- | --- | --- | --- | 
| AWS CLI | 2.15.17 | 2.15.17 | 2.15.17 | 2.15.17 | 2.13.19 | 
| AWS Copilot CLI | 0.6.0 | 0.6.0 | N/A | N/A | 1.30.1 | 
| Docker | 23.01 | N/A | 23.0.1 | N/A | N/A | 
| Docker Compose | 2.16.0 | N/A | 2.16.0 | N/A | N/A | 
| Git | 2.40.0 | 2.40.0 | 2.39.2 | 2.39.2 | 2.42.0 | 
| Go | 1.20.2 | 1.20.2 | 1.20.1 | 1.20.1 | 1.19 | 
| Gradle | 8.0.2 | 8.0.2 | 8.0.1 | 8.0.1 | 8.3 | 
| Java | Corretto17 | Corretto17 | Corretto17 | Corretto17 | Corretto17 | 
| Maven | 3.9.4 | 3.9.4 | 3.9.0 | 3.9.0 | 3.9.4 | 
| Node.js | 16.20.2 | 16.20.2 | 16.19.1 | 16.14.2 | 16.20.0 | 
| npm | 8.19.4 | 8.19.4 | 8.19.3 | 8.5.0 | 8.19.4 | 
| Python | 3.9.15 | 2.7.18 | 3.11.2 | 2.7.18 | 3.9.13 | 
| Python3 | N/A | 3.9.15 | N/A | 3.11.2 | N/A | 
| pip | 22.2.2 | 22.2.2 | 23.0.1 | 23.0.1 | 22.0.4 | 
| .NET | 6.0.407 | 6.0.407 | 6.0.406 | 6.0.406 | 6.0.414 | 

## What if an active image doesn't include the tools I need?
<a name="build-images-more-tools"></a>

If none of the [active images](#build-curated-images) supplied by CodeCatalyst include the tools you need, you have a couple of options:
+ You can provide a custom runtime environment Docker image that includes the necessary tools. For more information, see [Assigning a custom runtime environment Docker image to an action](#build-images-specify).
**Note**  
 If you want to provide a custom runtime environment Docker image, make sure that your custom image has Git installed in it. 
+ You can have your workflow's build or test action install the tools you need.

  For example, you could include the following instructions in the `Steps` section of the build or test action's YAML code:

  ```
  Configuration:
    Steps:
      - Run: ./setup-script
  ```

  The *setup-script* instruction would then run the following script to install the Node package manager (npm):

  ```
  #!/usr/bin/env bash
  echo "Setting up environment"
  
  touch ~/.bashrc
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
  source ~/.bashrc 
  nvm install v16.1.0
  source ~/.bashrc
  ```

  For more information about the build action YAML, see [Build and test actions YAML](build-action-ref.md).

## Assigning a custom runtime environment Docker image to an action
<a name="build-images-specify"></a>

If you don't want to use an [Active image](#build-curated-images) supplied by CodeCatalyst, you can provide a custom runtime environment Docker image. If you want to provide a custom image, make sure it has Git installed in it. The image can reside in Docker Hub, Amazon Elastic Container Registry, or any public repository.

To learn how to create a custom Docker image, see [Containerize an application](https://docs.docker.com/get-started/02_our_app/) in the Docker documentation.

Use the following instructions to assign your custom runtime environment Docker image to an action. After specifying an image, CodeCatalyst deploys it to your compute platform when the action starts.

**Note**  
The following actions do not support custom runtime environment Docker images: **Deploy CloudFormation stack**, **Deploy to ECS**, and **GitHub Actions**. custom runtime environment Docker images also do not support the **Lambda** compute type.

------
#### [ Visual ]

**To assign a custom runtime environment Docker image using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that will use your custom runtime environment Docker image.

1. Choose the **Configuration** tab.

1. Near the bottom, fill out the following fields.

   **Runtime environment Docker image - optional**

   Specify the registry where your image is stored. Valid values include:
   + `CODECATALYST` (YAML editor)

     The image is stored in the CodeCatalyst registry.
   + **Docker Hub** (visual editor) or `DockerHub` (YAML editor)

     The image is stored in the Docker Hub image registry.
   + **Other registry** (visual editor) or `Other` (YAML editor)

     The image is stored in a custom image registry. Any publicly available registry can be used.
   + **Amazon Elastic Container Registry** (visual editor) or `ECR` (YAML editor)

     The image is stored in an Amazon Elastic Container Registry image repository. To use an image in an Amazon ECR repository, this action needs access to Amazon ECR. To enable this access, you must create an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that includes the following permissions and custom trust policy. (You can modify an existing role to include the permissions and policy, if you want.)

     The IAM role must include the following permissions in its role policy:
     + `ecr:BatchCheckLayerAvailability`
     + `ecr:BatchGetImage`
     + `ecr:GetAuthorizationToken`
     + `ecr:GetDownloadUrlForLayer`

     The IAM role must include the following custom trust policy:

     For more information about creating IAM roles, see [Creating a role using custom trust policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) in the *IAM User Guide*.

     Once you have created the role, you must assign it to the action through an environment. For more information, see [Associating an environment with an action](deploy-environments-add-app-to-environment.md).

   **ECR image URL**, **Docker Hub image** or **Image URL**

   Specify one of the following:
   + If you are using a `CODECATALYST` registry, set the image to one of the of the following [active images](#build-curated-images):
     + `CodeCatalystLinux_x86_64:2024_03`
     + `CodeCatalystLinux_x86_64:2022_11`
     + `CodeCatalystLinux_Arm64:2024_03`
     + `CodeCatalystLinux_Arm64:2022_11`
     + `CodeCatalystLinuxLambda_x86_64:2024_03`
     + `CodeCatalystLinuxLambda_x86_64:2022_11`
     + `CodeCatalystLinuxLambda_Arm64:2024_03`
     + `CodeCatalystLinuxLambda_Arm64:2022_11`
     + `CodeCatalystWindows_x86_64:2022_11`
   + If you are using a Docker Hub registry, set the image to the Docker Hub image name and optional tag.

     Example: `postgres:latest`
   + If you are using an Amazon ECR registry, set the image to the Amazon ECR registry URI.

     Example: `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo`
   + If you are using a custom registry, set the image to the value expected by the custom registry.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To assign a custom runtime environment Docker image using the YAML editor**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Find the action that you want to assign a runtime environment Docker image to.

1. In the action, add a `Container` section and underlying `Registry` and `Image` properties. For more information, see the description of the `Container`, `Registry` and `Image` properties in the [Actions](workflow-reference.md#actions-reference) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

## Examples
<a name="workflows-working-custom-image-ex"></a>

The following examples show how to assign a custom runtime environment Docker image to an action in the workflow definition file.

**Topics**
+ [

### Example: Using a custom runtime environment Docker image to add support for Node.js 18 with Amazon ECR
](#workflows-working-custom-image-ex-ecr-node18)
+ [

### Example: Using a custom runtime environment Docker image to add support for Node.js 18 with Docker Hub
](#workflows-working-custom-image-ex-docker-node18)

### Example: Using a custom runtime environment Docker image to add support for Node.js 18 with Amazon ECR
<a name="workflows-working-custom-image-ex-ecr-node18"></a>

The following example shows how to use a custom runtime environment Docker image to add support for Node.js 18 with [Amazon ECR](https://gallery.ecr.aws/amazonlinux/amazonlinux).

```
Configuration:
  Container:
    Registry: ECR
    Image: public.ecr.aws/amazonlinux/amazonlinux:2023
```

### Example: Using a custom runtime environment Docker image to add support for Node.js 18 with Docker Hub
<a name="workflows-working-custom-image-ex-docker-node18"></a>

The following example shows how to use a custom runtime environment Docker image to add support for Node.js 18 with [Docker Hub](https://hub.docker.com/_/node).

```
Configuration:
  Container:
    Registry: DockerHub
    Image: node:18.18.2
```

# Connecting source repositories to workflows
<a name="workflows-sources"></a>

A *source*, also called an *input source*, is a source repository to which a [workflow action](workflows-actions.md) connects in order to obtain the files it needs to carry out its operations. For example, a workflow action might connect to a source repository to obtain application source files in order to build an application.

CodeCatalyst workflows support the following sources:
+ CodeCatalyst source repositories – For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).
+ GitHub repositories, Bitbucket repositories, and GitLab project repositories – For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md).

**Topics**
+ [

# Specifying a workflow file's source repository
](workflows-sources-specify-workflow-def.md)
+ [

# Specifying a workflow action's source repository
](workflows-sources-specify-action.md)
+ [

# Referencing source repository files
](workflows-sources-reference-files.md)
+ [

# 'BranchName' and 'CommitId' variables
](workflows-sources-variables.md)

# Specifying a workflow file's source repository
<a name="workflows-sources-specify-workflow-def"></a>

Use the following instructions to specify the CodeCatalyst source repository where you want to store your workflow definition file. If you'd rather specify a GitHub repository, Bitbucket repository, or GitLab project repository, see instead [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md).

The source repository where your workflow definition file resides is identified by the label, `WorkflowSource`.

**Note**  
You specify the source repository where your workflow definition file resides when you first commit your workflow definition file. After this commit, the repository and workflow definition file are linked together permanently. The only way to change the repository after the initial commit is to re-create the workflow in a different repository.

**To specify the source repository that will store the workflow definition file**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow** and create the workflow. For more information, see [Creating a workflow](workflows-create-workflow.md).

   During the workflow creation process, you can specify the CodeCatalyst repository, branch, and folder where you want to store your workflow definition file.

# Specifying a workflow action's source repository
<a name="workflows-sources-specify-action"></a>

Use the following instructions to specify a source repository to use with a workflow action. On startup, the action bundles the files at the configured source repository into an artifact, downloads the artifact to the [runtime environment Docker image](build-images.md) where the action is running, and then completes its processing using the downloaded files.

**Note**  
Currently, within a workflow action, you can only specify one source repository, which is the source repository where the workflow definition file resides (in the `.codecatalyst/workflows/` directory or one of its subdirectories). This source repository is represented by the label `WorkflowSource`.

------
#### [ Visual ]

**To specify the source repository that an action will use (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action where you want to specify the source.

1. Choose **Inputs**.

1. In **Sources - optional** do the following:

   Specify the labels that represent the source repositories that will be needed by the action. Currently, the only supported label is `WorkflowSource`, which represents the source repository where your workflow definition file is stored.

   If you omit a source, then you must specify at least one input artifact under `action-name/Inputs/Artifacts`.

   For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To specify the source repository that an action will use (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In an action, add code similar to the following:

   ```
   action-name:
    Inputs:
      Sources:
        - WorkflowSource
   ```

   For more information, see the description of the `Sources` property in [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Referencing source repository files
<a name="workflows-sources-reference-files"></a>

If you have files that reside in a source repository, and you need to refer to these files in one of your workflow actions, complete the following procedure.

**Note**  
See also [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).

**To reference a file stored in a source repository**
+ In the action where you want to reference a file, add code similar to the following:

  ```
  Actions:
    My-action:
      Inputs:
        Sources:
          - WorkflowSource
        Configuration:
          Steps:
          - run: cd my-app && cat file1.jar
  ```

  In the previous code, the action looks in the `my-app` directory in the root of the `WorkflowSource` source repository to find and display the `file1.jar` file.

# 'BranchName' and 'CommitId' variables
<a name="workflows-sources-variables"></a>

The CodeCatalyst source produces and sets `BranchName` and `CommitId` variables when your workflow runs. These are known as *predefined variables*. See the following table for information about these variables.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  CommitId  |  The commit ID representing the state of the repository at the time the workflow run started. Example: `example3819261db00a3ab59468c8b` See also: [Example: Referencing the "CommitId" predefined variable](workflows-predefined-examples.md#workflows-working-with-variables-ex-refer-action)  | 
|  BranchName  |  The name of the branch against which the workflow run started. Examples: `main`, `feature/branch`, `test-LiJuan` See also: [Example: Referencing the "BranchName" predefined variable](workflows-predefined-examples.md#workflows-working-with-variables-ex-branch)  | 

# Connecting package repositories to workflows
<a name="workflows-packages"></a>

A *package* is a bundle that includes both software and the metadata that is required to install the software and resolve any dependencies. CodeCatalyst supports the npm package format.

A package consists of:
+ A name (for example, `webpack` is the name of a popular npm package)
+ An optional [namespace](packages-concepts.md#packages-concepts-package-namespaces) (for example, `@types` in `@types/node`)
+ A set of [versions](packages-concepts.md#packages-concepts-package-versions) (for example, `1.0.0`, `1.0.1`, `1.0.2`)
+ Package-level metadata (for example, npm dist tags)

In CodeCatalyst, you can publish packages to and consume packages from CodeCatalyst package repositories in your workflows. You can configure a build or test action with a CodeCatalyst package repository to automatically configure an action's npm client to push and pull packages from the specified repository.

For more information about packages, see [Publish and share software packages in CodeCatalyst](packages.md).

**Note**  
Currently, build and test actions support CodeCatalyst package repositories.

**Topics**
+ [

# Tutorial: Pull from a package repository
](packages-tutorial.md)
+ [

# Specifying CodeCatalyst package repositories in workflows
](workflows-package-specify-action.md)
+ [

# Using authorization tokens in workflow actions
](workflows-package-export-token.md)
+ [

# Examples: Package repositories in workflows
](workflows-working-packages-ex.md)

# Tutorial: Pull from a package repository
<a name="packages-tutorial"></a>

In this tutorial, you learn how to create a workflow that runs an application whose dependencies are pulled from a [CodeCatalyst package repository](packages-concepts.md#packages-concepts-repository). The application is a simple Node.js app that prints a 'Hello World' message to the CodeCatalyst logs. The application has a single dependency: the [lodash](https://www.npmjs.com/package/lodash) npm package. The `lodash` package is used to transform a `hello-world` string to `Hello World`. You will use version 4.17.20 of this package.

After setting up your application and workflow, you configure CodeCatalyst to block additional versions of `lodash` from being imported into the CodeCatalyst package repository from the public external registry ([npmjs.com](https://www.npmjs.com/)). You then test that additional versions of `lodash` are blocked successfully.

By the end of this tutorial, you should have a good understanding of how a workflow interacts with package repositories, both inside and outside CodeCatalyst, in order to retrieve packages. You should also understand the behind-the-scenes interactions that occur between npm, your package repository, your workflow, and your application's `package.json` file. 

**Topics**
+ [

## Prerequisites
](#packages-tutorial-prereqs)
+ [

## Step 1: Create a source repository
](#packages-tutorial-source-repo)
+ [

## Step 2: Create the CodeCatalyst and gateway package repositories
](#packages-tutorial-package-repo)
+ [

## Step 3: Create the 'Hello World' application
](#packages-tutorial-create-app)
+ [

## Step 4: Create a workflow that runs 'Hello World'
](#packages-tutorial-create-workflow)
+ [

## Step 5: Verify the workflow
](#packages-tutorial-verify)
+ [

## Step 6: Block imports from npmjs.com
](#packages-tutorial-block)
+ [

## Step 7: Test the blocking feature
](#packages-tutorial-test-block)
+ [

## Clean up
](#packages-tutorial-cleanup)

## Prerequisites
<a name="packages-tutorial-prereqs"></a>

Before you begin:
+ You need a CodeCatalyst **Space**. For more information, see [Creating a space](spaces-create.md).
+ In your CodeCatalyst space, you need an empty project called:

  ```
  codecatalyst-package-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).

## Step 1: Create a source repository
<a name="packages-tutorial-source-repo"></a>

In this step, you create a source repository in CodeCatalyst. This repository stores the tutorial's source files, such as the `index.js` and `package.json` files.

For more information about source repositories, see [Creating a source repository](source-repositories-create.md).

**To create a source repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-package-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose **Add repository**, and then choose **Create repository**.

1. In **Repository name**, enter:

   ```
   hello-world-app
   ```

1. Choose **Create**.

## Step 2: Create the CodeCatalyst and gateway package repositories
<a name="packages-tutorial-package-repo"></a>

In this step, you create a package repository in your CodeCatalyst project, and connect it to a gateway repository, also in your CodeCatalyst project. You later import the tutorial's dependency, `lodash`, from npmjs.com into both repositories.

The gateway repository is the 'glue' that connects your package repository in CodeCatalyst to the public npmjs.com.

For more information about package repositories, see [Publish and share software packages in CodeCatalyst](packages.md).

**Note**  
This tutorial uses the terms *CodeCatalyst package repository* and *gateway repository* to refer to the two repositories that you create in CodeCatalyst in the following procedure.

**To create CodeCatalyst package and gateway repositories**

1. In the navigation pane, choose **Packages**. 

1. Choose **Create package repository**.

1. In **Repository name**, enter:

   ```
   codecatalyst-package-repository
   ```

1. Choose **\$1 Select upstream repositories**.

1. Choose **Gateway repositories**.

1. In the **npm-public-registry-gateway** box, choose **Create**.

1. Choose **Select**.

1. Choose **Create**.

   CodeCatalyst creates a package repository called `codecatalyst-package-repository` which is connected to a gateway repository. The gateway repository is connected to the npmjs.com registry.

## Step 3: Create the 'Hello World' application
<a name="packages-tutorial-create-app"></a>

In this step, you create a 'Hello World' Node.js application and import its dependency (`lodash`) into your gateway and CodeCatalyst package repositories.

To create the application, you need a development machine with Node.js and the associated `npm` client installed.

This tutorial assumes you'll be using a CodeCatalyst Dev Environment as your development machine. Although you don't have to use a CodeCatalyst Dev Environment, it is recommended because it provides a clean working environment, has Node.js and `npm` preinstalled, and is easy to delete when you have finished the tutorial. For more information about CodeCatalyst Dev Environments, see [Creating a Dev Environment](devenvironment-create.md).

Use the following instructions to launch a CodeCatalyst Dev Environment and use it to create the 'Hello World' application.

**To launch a CodeCatalyst Dev Environment**

1. In the navigation pane, choose **Code**, and then choose **Dev Environments**. 

1. Near the top choose **Create Dev Environment**, and then choose **AWS Cloud9 (in browser)**.

1. Make sure that **Repository** is set to `hello-world-app` and **Existing branch** is set to `main`. Choose **Create**.

   Your Dev Environment launches in a new browser tab, and your repository (`hello-world-app`) is cloned into it.

1. Leave both CodeCatalyst browser tabs open, and go to the next procedure.

**To create the 'Hello World' Node.js application**

1. Go to your Dev Environment.

1. At the terminal prompt, change to the `hello-world-app` source repository root directory:

   ```
   cd hello-world-app
   ```

1. Initialize a Node.js project:

   ```
   npm init -y
   ```

   The initialization creates a `package.json` file in the root directory of `hello-world-app`.

1. Connect the npm client in your Dev Environment to your CodeCatalyst package repository:

   1. Switch to the CodeCatalyst console.

   1. In the navigation pane, choose **Packages**.

   1. Choose `codecatalyst-package-repository`.

   1. Choose **Connect to repository**.

   1. Choose **Create token**. A personal access token (PAT) is created for you.

   1. Choose **Copy** to copy the commands.

   1. Switch to your Dev Environment.

   1. Make sure you're in the `hello-world-app` directory.

   1. Paste the commands. They look similar to the following:

      ```
      npm set registry=https://packages.us-west-2.codecatalyst.aws/npm/ExampleCompany/codecatalyst-package-project/codecatalyst-package-repository/ --location project
      npm set //packages.us-west-2.codecatalyst.aws/npm/ExampleCompany/codecatalyst-package-project/hello-world-app/:_authToken=username:token-secret
      ```

1. Import `lodash` version 4.17.20:

   ```
   npm install lodash@v4.17.20 --save --save-exact
   ```

   npm looks for `lodash` version 4.17.20 in the following locations, in the following order:
   + In the Dev Environment. It can't find it here.
   + In the CodeCatalyst package repository. It can't find it here.
   + In the gateway repository. It can't find it here.
   + In npmjs.com. It finds it here.

   npm imports `lodash` into the gateway repository, the CodeCatalyst package repository, and the Dev Environment.
**Note**  
If you had not connected the npm client to your CodeCatalyst package repository in step 4, then npm would have pulled `lodash` directly from npmjs.com and would not have imported the package to either repository.

   npm also updates your `package.json` file with the `lodash` dependency, and creates a `node_modules` directory containing `lodash` and all its dependencies.

1. Test that `lodash` was successfully imported to your Dev Environment. Enter:

   ```
   npm list
   ```

   The following message appears, indicating a successful import:

   ```
   `-- lodash@4.17.20
   ```

1. (Optional) Open `hello-world-app/package.json` and verify that the lines in ***red bold*** were added:

   ```
   {
     "name": "hello-world-app",
     "version": "1.0.0",
     "description": "",
     "main": "index.js",
     "scripts": {
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     dependencies": {
       "lodash": "4.17.20"
     }
   }
   ```

1. In `/hello-world-app`, create a file called `index.js` with the following contents:
**Tip**  
You can use the side navigation in your Dev Environment to create this file.

   ```
   // Importing lodash library
   const _ = require('lodash');
   
   // Input string
   const inputString = 'hello-world';
   
   // Transforming the string using lodash
   const transformedString = _.startCase(inputString.replace('-', ' '));
   
   // Outputting the transformed string to the console
   console.log(transformedString);
   ```

**To test that 'lodash' was imported to your gateway and CodeCatalyst package repositories**

1. Switch to the CodeCatalyst console.

1. In the navigation pane, choose **Packages**.

1. Choose **npm-public-registry-gateway**.

1. Make sure `lodash` is displayed. The **Latest version** column indicates `4.17.20`.

1. Repeat this procedure for the `codecatalyst-package-repository`. You might need to refresh the browser window to see the imported package.

**To test 'Hello World' in your Dev Environment**

1. Switch to your Dev Environment.

1. Make sure you're still in the `hello-world-app` directory, and then run the application:

   ```
   node index.js
   ```

   A `Hello World` message appears. Node.js ran the application using the `lodash` package that you downloaded to your Dev Environment in a previous step.

**To ignore the 'node\$1modules' directory and commit 'Hello World'**

1. Ignore the `node_modules` directory. Enter:

   ```
   echo "node_modules/" >> .gitignore
   ```

   It is a best practice to avoid committing this directory. Also, committing this directory will interfere with later steps in this tutorial.

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add the Hello World application"
   git push
   ```

   The 'Hello World' application and project files are added to your source repository.

## Step 4: Create a workflow that runs 'Hello World'
<a name="packages-tutorial-create-workflow"></a>

In this step, you create a workflow that runs the 'Hello World' application using the `lodash` dependency. The workflow includes a single *action*, or task, called `RunHelloWorldApp`. The `RunHelloWorldApp` action includes the following noteworthy commands and sections:
+ **`Packages`**

  This section indicates the name of the CodeCatalyst package repository that the action must connect to when running `npm install`.
+ **`- Run: npm install`** 

  This command tells npm to install the dependencies specified in the `package.json` file. The only dependency specified in the `package.json` file is `lodash`. npm looks for `lodash` in the following locations:
  + In the Docker image running the action. It can't find it here.
  + In the CodeCatalyst package repository. It finds it here.

  After npm finds `lodash`, it imports it to the Docker image running the action.
+ **`- Run: npm list`**

  This command prints out which version of `lodash` was downloaded to the Docker image running the action.
+ **`- Run: node index.js`**

  This command runs the 'Hello World' application using the dependency specified in the `package.json` file.

Notice that the `RunHelloWorldApp` action is a build action, as indicated by the `aws/build@v1` identifier near the top of the workflow. For more information about the build action, see [Building with workflows](build-workflow-actions.md).

Use the following instructions to create a workflow that pulls the `lodash` dependency from your CodeCatalyst package repository and then runs your 'Hello World' application.

**To create a workflow**

1. Switch to the CodeCatalyst console.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. For **Source repository**, choose `hello-world-app`.

1. For **Branch**, choose `main`.

   The workflow definition file is will be created in the chosen source repository and branch.

1. Choose **Create**.

1. Choose **YAML** near the top.

1. Delete the YAML sample code.

1. Add the following YAML code:

   ```
   Name: codecatalyst-package-workflow
   SchemaVersion: "1.0"
   
   # Required - Define action configurations.
   Actions:
     RunHelloWorldApp:
       # Identifies the action. Do not modify this value.
       Identifier: aws/build@v1
       Compute:
         Type: Lambda
       Inputs:
         Sources:
           - WorkflowSource # This specifies your source repository. 
       Configuration:
         Steps:
           - Run: npm install
           - Run: npm list
           - Run: node index.js
         Container: # This specifies the Docker image that runs the action.
           Registry: CODECATALYST
           Image: CodeCatalystLinuxLambda_x86_64:2024_03
       Packages:
         NpmConfiguration:
           PackageRegistries:
             - PackagesRepository: codecatalyst-package-repository
   ```

   In the preceding code, replace *codecatalyst-package-repository* with the name of the CodeCatalyst package repository that you created in [Step 2: Create the CodeCatalyst and gateway package repositories](#packages-tutorial-package-repo).

   For information about the properties in this file, see the [Build and test actions YAML](build-action-ref.md).

1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing.

1. Choose **Commit**.

1. On the **Commit workflow** dialog box, enter the following:

   1. For **Workflow file name**, keep the default, `codecatalyst-package-workflow`.

   1. For **Commit message**, enter:

      ```
      add initial workflow file
      ```

   1. For **Repository**, choose **hello-world-app**.

   1. For **Branch name**, choose **main**.

   1. Choose **Commit**.

   You have now created a workflow.

**To run the workflow**

1. Next to the workflow you just created (`codecatalyst-package-workflow`), choose **Actions** and then choose **Run**.

   A workflow run starts.

1. In the green notification at the top, on the right, choose the link to the run. The link looks similar to `View Run-1234`.

   A workflow diagram appears, showing who started the run and the **RunHelloWorldApp** action.

1. Choose the **RunHelloWorldApp** action box to watch the action's progress. 

1. When the run finishes, go to [Step 5: Verify the workflow](#packages-tutorial-verify).

## Step 5: Verify the workflow
<a name="packages-tutorial-verify"></a>

In this step, you verify that the workflow successfully ran the 'Hello World' application with its `lodash` dependency.

**To verify that the 'Hello World' application ran using its dependency**

1. In the workflow diagram, choose the **RunHelloWorldApp** box.

   A list of log messages appear.

1. Expand the `node index.js` log message.

   The following message appears:

   ```
   [Container] 2024/04/24 21:15:41.545650 Running command node index.js
   Hello World
   ```

   The appearance of `Hello Word` (instead of `hello-world`) indicates that the `lodash` dependency was successfully used.

1. Expand the `npm list` log.

   A message similar to the following appears:

   ```
   └── lodash@4.17.20
   ```

   This message indicates that `lodash` version 4.17.20 was downloaded to the Docker image running the workflow action.

## Step 6: Block imports from npmjs.com
<a name="packages-tutorial-block"></a>

 Now that `lodash` version 4.17.20 is present in your gateway and CodeCatalyst package repositories, you can block imports of other versions. Blocking prevents you from accidentally importing later (or earlier) versions of `lodash`, which might contain malicious code. For more information, see [Editing package origin controls](package-origin-controls.md) and [Dependency substitution attacks](package-origin-controls.md#dependency-substitution-attacks).

Use the following instructions to block imports of `lodash` into your gateway repository. When you block packages at the gateway, they are also blocked at downstream locations.

**To block imports to your gateway repository**

1. In the navigation pane, choose **Packages**.

1. Choose **npm-publish-registry-gateway**.

1. Choose `lodash`.

1. Near the top, choose **Origin controls**.

1. Under **Upstream**, choose **Block**.

1. Choose **Save**.

   You have now blocked imports into your gateway repository (and downstream repositories and computers) from npmjs.com.

## Step 7: Test the blocking feature
<a name="packages-tutorial-test-block"></a>

In this section, you verify that the blocking you set up in [Step 6: Block imports from npmjs.com](#packages-tutorial-block) is working. You start by configuring 'Hello World' to request version 4.17.2**1** of `lodash` instead of the one available in your gateway repository, which is 4.17.2**0**. You then check that the application cannot pull version 4.17.21 from nmpjs.com, indicating a successful blockage. As a final test, you unblock imports to your gateway repository, and check that the application can successfully pull version 4.17.21 of `lodash`.

Use the following set of procedures to test the blocking feature.

**Before you begin**

1. Switch to your Dev Environment.

1. Pull the `codecatalyst-package-workflow.yaml` file that you created using the CodeCatalyst console earlier:

   ```
   git pull
   ```

**To configure 'Hello World' to request version 4.17.21 of 'lodash'**

1. Open `/hello-world-app/package.json`.

1. Change the `lodash` version to 4.17.21 as shown in ***red bold***:

   ```
   {
     "name": "hello-world-app",
     "version": "1.0.0",
     "description": "",
     "main": "index.js",
     "scripts": {
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     "dependencies": {
       "lodash": "4.17.21"
     }
   }
   ```

   There is now a mismatch between the version in the `package.json` file (4.17.21) and the version in the gateway and CodeCatalyst package repositories (4.17.20).

1. Add, commit, and push:

   ```
   git add .
   git commit -m "update package.json to use lodash 4.17.21"
   git push
   ```

**To test that 'Hello World' cannot pull version 4.17.21 of 'lodash'**

1. Run the workflow with the version mismatch:

   1. Switch to the CodeCatalyst console.

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Next to `codecatalyst-package-workflow`, choose **Actions**, and then choose **Run.**

      npm looks in `package.json` for dependencies and sees that version 4.17.21 of `lodash` is required by 'Hello World'. npm looks for the dependency in the following locations, in the following order:
      + In the Docker image running the action. It can't find it here.
      + In the CodeCatalyst package repository. It can't find it here.
      + In the gateway repository. It can't find it here.
      + In npmjs.com. It finds it here.

      After npm finds version 4.17.21 in npmjs.com, it tries to import it into the gateway repository, but because you set up the gateway to block imports of `lodash`, the import does not occur.

      Because the import does not occur, the workflow fails.

1. Verify that the workflow failed:

   1. In the green notification at the top, on the right, choose the link to the run. The link looks similar to `View Run-2345`.

   1. In the workflow diagram, choose the **RunHelloWorldApp** box.

   1. Expand the `npm install` log message.

      The following message appears:

      ```
      [Container] 2024/04/25 17:20:34.995591 Running command npm install
      npm ERR! code ETARGET
      npm ERR! notarget No matching version found for lodash@4.17.21.
      npm ERR! notarget In most cases you or one of your dependencies are requesting
      npm ERR! notarget a package version that doesn't exist.
      
      npm ERR! A complete log of this run can be found in: /tmp/.npm/_logs/2024-05-08T22_03_26_493Z-debug-0.log
      ```

      The error indicates that version 4.17.21 couldn't be found. This is expected because you blocked it.

**To unblock imports from npmjs.com**

1. In the navigation pane, choose **Packages**.

1. Choose **npm-publish-registry-gateway**.

1. Choose `lodash`.

1. Near the top, choose **Origin controls**.

1. Under **Upstream**, choose **Allow**.

1. Choose **Save**.

   You have now unblocked imports of `lodash`.

   Your workflow can now import version 4.17.21 of `lodash`.

**To test that imports from npmjs.com are unblocked**

1. Run your workflow again. This time the workflow should succeed because the import of 4.17.21 should now work. To run the workflow again:

   1. Choose **CI/CD** and then choose **Workflows**.

   1. Next to `codecatalyst-package-workflow`, choose **Actions** and choose **Run**.

   1. In the green notification at the top, on the right, choose the link to the run. The link looks similar to `View Run-3456`.

      A workflow diagram appears, showing who started the run and the **RunHelloWorldApp** action.

   1. Choose the **RunHelloWorldApp** action box to watch the action's progress. 

   1. Expand the `npm list` log message and verify that a message similar to the following appears:

      ```
      └── lodash@4.17.21
      ```

      This message indicates that `lodash` version 4.17.21 was downloaded.

1. Verify that version 4.17.21 was imported to your CodeCatalyst and gateway repositories:

   1. In the navigation pane, choose **Packages**.

   1. Choose **npm-public-registry-gateway**.

   1. Find `lodash` and make sure the version is `4.17.21`.
**Note**  
Although version 4.17.20 is not listed on this page, you can find it by choosing `lodash` and then choosing **Versions** near the top.

   1. Repeat these steps to check that version 4.17.21 was imported to `codecatalyst-package-repository`.

## Clean up
<a name="packages-tutorial-cleanup"></a>

Clean up the files and services used in this tutorial to avoid being charged for them.

**To clean up the packages tutorial**

1. Delete the `codecatalyst-package-project`:

   1. In the CodeCatalyst console, nagivate to the `codecatalyst-package-project` project if you're not there already.

   1. In the navigation pane, choose **Project settings**.

   1. Choose **Delete project**, enter **delete**, and choose **Delete project**.

      CodeCatalyst deletes all project resources, including the source, gateway, and CodeCatalyst package repositories. The Dev Environment is also deleted.

1. Delete the PAT token:

   1. Choose your username on the right, and then choose **My settings**.

   1. Under **Personal access tokens**, choose the token you created in this tutorial and choose **Delete**.

In this tutorial, you learned how to create a workflow that runs an application that pulls its dependencies from a CodeCatalyst package repository. You also learned how to block and unblock packages from entering your gateway and CodeCatalyst package repositories.

# Specifying CodeCatalyst package repositories in workflows
<a name="workflows-package-specify-action"></a>

In CodeCatalyst, you can add a CodeCatalyst package repository to your build and test actions in your workflow. Your package repository must be configured with a package format, such as npm. You can also choose to include a sequence of scopes for your selected package repository.

Use the following instructions to specify a package configuration to use with a workflow action.

------
#### [ Visual ]

**To specify the package configuration that an action will use (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the **Build** or **Test** action with which you want to configure with a package repository.

1. Choose **Packages**.

1. From the **Add configuration** dropdown menu, choose the package configuration you want to use with your workflow actions.

1. Choose **Add package repository**.

1. In the **Package repository** dropdown menu, specify the name of your CodeCatalyst *package repository* that you want the action to use.

   For more information about package repositories, see [Package repositories](packages-concepts.md#packages-concepts-repository).

1. (Optional) In **Scopes - optional**, specify a sequence of *scopes* that you want to define in your package registry.

   When defining scopes, the specified package repository is configured as the registry for all listed scopes. If a package with the scope is requested through the npm client, it will use that repository instead of the default. Each scope name must be prefixed with "@".

   If `Scopes` is omitted, then the specified package repository is configured as the default registry for all packages used by the action.

   For more information about scopes, see [Package namespaces](packages-concepts.md#packages-concepts-package-namespaces) and [Scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope).

1. Choose **Add**.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To specify the package configuration that an action will use (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a **Build** or **Test** action, add code similar to the following:

   ```
   action-name:
    Configuration:
       Packages:
           NpmConfiguration:
             PackageRegistries:
               - PackagesRepository: package-repository
                 Scopes:
                   - "@scope"
   ```

   For more information, see the description of the `Packages` property in [Build and test actions YAML](build-action-ref.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Using authorization tokens in workflow actions
<a name="workflows-package-export-token"></a>

You can use a token provided by the workflow action to manually configure a package manager to authenticate with CodeCatalyst package repositories. CodeCatalyst makes this token available as an environment variable for you to reference in your actions.


| Environment variable | Value | 
| --- | --- | 
|  CATALYST\$1MACHINE\$1RESOURCE\$1NAME  |  The user identity of the authorization token.  | 
|  CATALYST\$1PACKAGES\$1AUTHORIZATION\$1TOKEN  |  The value of the authorization token.  | 

**Note**  
Note that these environment variables will only be populated if you have configured your action to export the authorization token.

Use the following instructions to use an authorization token with a workflow action.

------
#### [ Visual ]

**To use an exported authorization token with an action (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the **Build** or **Test** action with which you want to configure with a package repository.

1. Choose **Packages**.

1. Turn on **Export authorization token**.

------
#### [ YAML ]

**To use an exported authorization token with an action (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a **Build** or **Test** action, add code similar to the following:

   ```
   Actions:
     action-name:
       Packages:
         ExportAuthorizationToken: true
   ```

   You can reference the `$CATALYST_MACHINE_RESOURCE_NAME` and `$CATALYST_PACKAGES_AUTHORIZATION_TOKEN` environment variables in the `Steps` section of your YAML. For more information, refer to [Example: Manually configuring `pip` to authenticate with CodeCatalyst](workflows-working-packages-ex.md#workflows-working-packages-pypi-token).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Examples: Package repositories in workflows
<a name="workflows-working-packages-ex"></a>

The following examples show how to reference packages in the workflow definition file.

**Topics**
+ [

## Example: Defining packages with `NpmConfiguration`
](#workflows-working-packages-ex-basic)
+ [

## Example: Overriding the default registry
](#workflows-working-packages-ex-overriding-registry)
+ [

## Example: Overriding scopes in your package registry
](#workflows-working-packages-ex-overriding-scopes)
+ [

## Example: Manually configuring `pip` to authenticate with CodeCatalyst
](#workflows-working-packages-pypi-token)

## Example: Defining packages with `NpmConfiguration`
<a name="workflows-working-packages-ex-basic"></a>

The following example shows how to define a package with `NpmConfiguration` in your workflow definition file.

```
Actions:
  Build:
  Identifier: aws/build-beta@v1
  Configuration:
    Packages:
        NpmConfiguration:
          PackageRegistries:
            - PackagesRepository: main-repo
            - PackagesRepository: scoped-repo
              Scopes:
                - "@scope1"
```

This example configures the npm client as such:

```
default: main-repo
@scope1: scoped-repo
```

In this example, there are two repositories defined. The default registry is set as `main-repo` as it is defined without a scope. Scope `@scope1` is configured in `PackageRegistries` for `scoped-repo`.

## Example: Overriding the default registry
<a name="workflows-working-packages-ex-overriding-registry"></a>

The following example shows you how to override the default registry.

```
NpmConfiguration:
  PackageRegistries:
    - PackagesRepository: my-repo-1
    - PackagesRepository: my-repo-2
    - PackagesRepository: my-repo-3
```

This example configures the npm client as such:

```
default: my-repo-3
```

If you specify multiple default repositories, the last repository will take priority. In this example, the last repository listed is `my-repo-3`, meaning that npm will connect to `my-repo-3`. This overrides the repositories `my-repo-1` and `my-repo-2`.

## Example: Overriding scopes in your package registry
<a name="workflows-working-packages-ex-overriding-scopes"></a>

The following example shows you how to override a scope in your package registry.

```
NpmConfiguration:
  PackageRegistries:
    - PackagesRepository: my-default-repo
    - PackagesRepository: my-repo-1
      Scopes:
        - "@scope1"
        - "@scope2"
    - PackagesRepository: my-repo-2
      Scopes:
        - "@scope2"
```

This example configures the npm client as such:

```
default: my-default-repo
@scope1: my-repo-1
@scope2: my-repo-2
```

If you include overriding scopes, the last repository will take priority. In this example, the last time that scope `@scope2` is configured in `PackageRegistries` is for `my-repo-2`. This overrides the scope `@scope2` configured for `my-repo-1`.

## Example: Manually configuring `pip` to authenticate with CodeCatalyst
<a name="workflows-working-packages-pypi-token"></a>

The following example shows you how to reference CodeCatalyst authorization environment variables in a build action.

```
Actions:
  Build:
    Identifier: aws/build@v1.0.0
    Configuration:
      Steps:
        - Run: pip config set global.index-url https://$CATALYST_MACHINE_RESOURCE_NAME:$CATALYST_PACKAGES_AUTHORIZATION_TOKEN@codecatalyst.aws/pypi/my-space/my-project/my-repo/simple/
    Packages:
      ExportAuthorizationToken: true
```

# Invoking a Lambda function using a workflow
<a name="lam-invoke-action"></a>

This section describes how to invoke a AWS Lambda function using a CodeCatalyst workflow. To accomplish this, you must add the **AWS Lambda invoke** action to your workflow. The **AWS Lambda invoke** action invokes the Lambda function that you specify.

In addition to invoking your function, the **AWS Lambda invoke** action also converts each top-level key in the response payload received from the Lambda function into a [workflow output variable](workflows-working-with-variables.md). These variables can then be referenced in subsequent workflow actions. If you don't want all top-level keys to be converted to variables, you can use filters to specify the exact ones. For more information, see [ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters) property description in the ['AWS Lambda invoke' action YAML](lam-invoke-action-ref.md). 

**Topics**
+ [

## When to use this action
](#lam-invoke-action-when-to-use)
+ [

## Runtime image used by the 'AWS Lambda invoke' action
](#lam-invoke-action-runtime)
+ [

# Example: Invoke a Lambda function
](lam-invoke-action-example-workflow.md)
+ [

# Adding the 'AWS Lambda invoke' action
](lam-invoke-action-add.md)
+ [

# 'AWS Lambda invoke' variables
](lam-invoke-action-variables.md)
+ [

# 'AWS Lambda invoke' action YAML
](lam-invoke-action-ref.md)

## When to use this action
<a name="lam-invoke-action-when-to-use"></a>

Use this action if you want to add functionality to your workflow that is encapsulated in, and performed by, a Lambda function.

For example, you might want your workflow to send a `Build started` notification to a Slack channel before starting a build of your application. In this case, your workflow would include an **AWS Lambda invoke** action to invoke a Lambda to send out the Slack notification, and a [build action](build-add-action.md) to build your application.

As another example, you might want your workflow to conduct a vulnerability scan on your application before it is deployed. In this case, you would use a build action to build your application, an **AWS Lambda invoke** action to invoke a Lambda to scan for vulnerabilities, and a deploy action to deploy the scanned application.

## Runtime image used by the 'AWS Lambda invoke' action
<a name="lam-invoke-action-runtime"></a>

The **AWS Lambda invoke** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Example: Invoke a Lambda function
<a name="lam-invoke-action-example-workflow"></a>

The following example workflow includes the **AWS Lambda invoke** action, along with a deploy action. The workflow sends out a Slack notification indicating that a deployment has started, and then deploys an application into AWS using an CloudFormation template. The workflow consists of the following building blocks that run sequentially:
+ A **trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ An **AWS Lambda invoke** action (`LambdaNotify`) – On trigger, this action invokes the `Notify-Start` Lambda function in the specified AWS account and Region (`my-aws-account`, and `us-west-2`). On invocation, the Lambda function sends a Slack notification indicating a deployment has started.
+ A **Deploy CloudFormation stack** action (`Deploy`) – On completion of the **AWS Lambda invoke** action, the **Deploy CloudFormation stack** action runs the template (`cfn-template.yml`) to deploy your application stack. For more information about the **Deploy CloudFormation stack** action, see [Deploying an CloudFormation stack](deploy-action-cfn.md).

**Note**  
The following workflow example is for illustrative purposes, and will not work without additional configuration.

**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies required by the **AWS Lambda invoke** and **Deploy CloudFormation stack** actions. For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). For more information about the permissions and trust policies required by the **AWS Lambda invoke** and **Deploy CloudFormation stack** actions, see the description of the `Role` property in the ['AWS Lambda invoke' action YAML](lam-invoke-action-ref.md) and ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md).

```
Name: codecatalyst-lamda-invoke-workflow
SchemaVersion: 1.0

Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  LambdaNotify:
    Identifier: aws/lambda-invoke@v1
    Environment:
      Name: my-production-environment
      Connections:
        - Name: my-aws-account
          Role: codecatalyst-lambda-invoke-role
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Function: Notify-Start
      AWSRegion: us-west-2
        
  Deploy:
    Identifier: aws/cfn-deploy@v1
    Environment:
      Name: my-production-environment
      Connections:
        - Name: my-aws-account
          Role: codecatalyst-deploy-role
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      name: my-application-stack
      region: us-west-2
      role-arn: arn:aws:iam::111122223333:role/StackRole
      template: ./cfn-template.yml
      capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
```

# Adding the 'AWS Lambda invoke' action
<a name="lam-invoke-action-add"></a>

 Use the following instructions to add the **AWS Lambda invoke** action to your workflow. 

**Prerequisite**  
Before you begin, make sure your AWS Lambda function and associated Lambda execution role are ready and available in AWS. For more information, see the [Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) topic in the *AWS Lambda Developer Guide*.

------
#### [ Visual ]

**To add the 'AWS Lambda invoke' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS Lambda invoke** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **AWS Lambda invoke**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs**, **Configuration**, and **Outputs** tabs, complete the fields according to your needs. For a description of each field, see the ['AWS Lambda invoke' action YAML](lam-invoke-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'AWS Lambda invoke' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **AWS Lambda invoke** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **AWS Lambda invoke**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['AWS Lambda invoke' action YAML](lam-invoke-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# 'AWS Lambda invoke' variables
<a name="lam-invoke-action-variables"></a>

By default, the **AWS Lambda invoke** action produces one variable per top-level key in the Lambda response payload.

For example, if the response payload looks like this:

```
responsePayload = {
  "name": "Saanvi",
  "location": "Seattle",
  "department": {
    "company": "Amazon",
    "team": "AWS"
  }
}
```

...then the action would generate the following variables.


| Key | Value | 
| --- | --- | 
|  name  |  Saanvi  | 
|  location  |  Seattle  | 
|  department  |  \$1"company": "Amazon", "team": "AWS"\$1  | 

**Note**  
You can change which variables are generated using the `ResponseFilters` YAML property. For more information, see the [ResponseFilters](lam-invoke-action-ref.md#lam.invoke.response.filters) in the ['AWS Lambda invoke' action YAML](lam-invoke-action-ref.md).

The variables produced and set by the 'AWS Lambda invoke' action at run time are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).

# 'AWS Lambda invoke' action YAML
<a name="lam-invoke-action-ref"></a>

The following is the YAML definition of the **AWS Lambda invoke** action. To learn how to use this action, see [Invoking a Lambda function using a workflow](lam-invoke-action.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  LambdaInvoke\$1nn: 
    Identifier: aws/lambda-invoke@v1
    DependsOn:
      - dependent-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - request-payload
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Configuration:
      Function: my-function|function-arn
      AWSRegion: us-west-2
      # Specify RequestPayload or RequestPayloadFile, but not both.
      RequestPayload: '{"firstname": "Li", lastname: "Jean", "company": "ExampleCo", "team": "Development"}'
      RequestPayloadFile: my/request-payload.json
      ContinueOnError: true|false
      LogType: Tail|None
      ResponseFilters: '{"name": ".name", "company": ".department.company"}'
    Outputs:
      Artifacts:
        - Name: lambda_artifacts
          Files: 
            - "lambda-response.json"
```

## LambdaInvoke
<a name="lam.invoke.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `Lambda_Invoke_Action_Workflow_nn`.

Corresponding UI: Configuration tab/**Action name**

## Identifier
<a name="lam.invoke.identifier"></a>

(*LambdaInvoke*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/lambda-invoke@v1`.

Corresponding UI: Workflow diagram/LambdaInvoke\$1nn/**aws/lambda-invoke@v1** label

## DependsOn
<a name="lam.invoke.dependson"></a>

(*LambdaInvoke*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="lam.invoke.computename"></a>

(*LambdaInvoke*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="lam.invoke.computetype"></a>

(*LambdaInvoke*/Compute/**Type**)

(Required if [Compute](#lam.invoke.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/**Compute type**

## Fleet
<a name="lam.invoke.computefleet"></a>

(*LambdaInvoke*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/**Compute fleet**

## Timeout
<a name="lam.invoke.timeout"></a>

(*LambdaInvoke*/**Timeout**)

(Required)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Inputs
<a name="lam.invoke.inputs"></a>

(*LambdaInvoke*/**Inputs**)

(Required)

The `Inputs` section defines the data that the **AWS Lambda invoke** action needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed per **AWS Lambda invoke** action. Variables do not count towards this total.

Corresponding UI: **Inputs** tab

## Sources
<a name="lam.invoke.inputs.sources"></a>

(*LambdaInvoke*/Inputs/**Sources**)

(Required if [RequestPayloadFile](#lam.invoke.request.payload.file) is provided)

If you want to pass a request payload JSON file to the **AWS Lambda invoke** action, and this payload file is stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your request payload file is not contained within a source repository, it must reside in an artifact generated by another action.

For more information about the payload file, see [RequestPayloadFile](#lam.invoke.request.payload.file).

**Note**  
Instead of specifying a payload file, you can add the payload's JSON code directly to the action using the `RequestPayload` property. For more information, see [RequestPayload](#lam.invoke.request.payload). 

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="lam.invoke.inputs.artifacts"></a>

(*LambdaInvoke*/Inputs/**Artifacts**)

(Required if [RequestPayloadFile](#lam.invoke.request.payload.file) is provided)

If you want to pass a request payload JSON file to the **AWS Lambda invoke** action, and this payload file is contained in an [output artifact](build-action-ref.md#build.outputs.artifacts) from a previous action, specify that artifact here.

For more information about the payload file, see [RequestPayloadFile](#lam.invoke.request.payload.file).

**Note**  
Instead of specifying a payload file, you can add the payload's JSON code directly to the action using the `RequestPayload` property. For more information, see [RequestPayload](#lam.invoke.request.payload). 

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Variables - input
<a name="lam.invoke.inputs.variables"></a>

(*LambdaInvoke*/Inputs/**Variables**)

(Optional)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Inputs tab/**Variables - optional**

## Environment
<a name="lam.invoke.environment"></a>

(*LambdaInvoke*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="lam.invoke.environment.name"></a>

(*LambdaInvoke*/Environment/**Name**)

(Required if [Environment](#lam.invoke.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="lam.invoke.environment.connections"></a>

(*LambdaInvoke*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="lam.invoke.environment.connections.name"></a>

(*LambdaInvoke*/Environment/Connections/**Name**)

(Required if [Connections](#lam.invoke.environment.connections) is included)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="lam.invoke.environment.connections.role"></a>

(*LambdaInvoke*/Environment/Connections/**Role**)

(Required if [Connections](#lam.invoke.environment.connections) is included)

Specify the name of the IAM role that the **AWS Lambda invoke** action uses to access AWS and invoke your Lambda function. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.
+ The following custom trust policy:

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Configuration
<a name="lam.invoke.configuration"></a>

(*LambdaInvoke*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## Function
<a name="lam.invoke.function"></a>

(*LambdaInvoke*/Configuration/**Function**)

(Required)

Specify the AWS Lambda function that this action will invoke. You can specify the name of the function, or its Amazon Resource Name (ARN). You can find the name or ARN in the Lambda console.

**Note**  
The AWS account where the Lambda function resides can be different from the account specified under `Connections:`.

Corresponding UI: Configuration tab/**Function**

## AWSRegion
<a name="lam.invoke.region"></a>

(*LambdaInvoke*/Configuration/**AWSRegion**)

(Required)

Specify the AWS Region where your AWS Lambda function resides. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the *AWS General Reference*.

Corresponding UI: Configuration tab/**Destination bucket - optional**

## RequestPayload
<a name="lam.invoke.request.payload"></a>

(*LambdaInvoke*/Configuration/**RequestPayload**)

(Optional)

If you want to pass a request payload to the **AWS Lambda invoke** action, specify the request payload here, in JSON format.

Example request payload:

```
'{ "key": "value" }'
```

If you do not want to pass a request payload to your Lambda function, then omit this property.

**Note**  
You can specify either `RequestPayload` or `RequestPayloadFile`, but not both.

For more information about the request payload, see the [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) topic in the *AWS Lambda API Reference*.

Corresponding UI: Configuration tab/**Request payload - optional**

## RequestPayloadFile
<a name="lam.invoke.request.payload.file"></a>

(*LambdaInvoke*/Configuration/**RequestPayloadFile**)

(Optional)

If you want to pass a request payload to the **AWS Lambda invoke** action, specify the path to this request payload file here. The file must be in JSON format.

The request payload file can reside in a source repository or an artifact from a previous action. The file path is relative to the source repository or artifact root.

If you do not want to pass a request payload to your Lambda function, then omit this property.

**Note**  
You can specify either `RequestPayload` or `RequestPayloadFile`, but not both.

For more information about the request payload file, see the [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) topic in the *AWS Lambda API Reference*.

Corresponding UI: Configuration tab/**Request payload file - optional**

## ContinueOnError
<a name="lam.invoke.continue"></a>

(*LambdaInvoke*/Configuration/**RequestPayloadFile**)

(Optional)

Specify whether you want to mark the **AWS Lambda invoke** action as succeeded even if the invoked AWS Lambda function fails. Consider setting this property to `true` to allow subsequent actions in your workflow to start despite the Lambda failure.

The default is to fail the action if the Lambda function fails ("off" in the visual editor or `false` in the YAML editor).

Corresponding UI: Configuration tab/**Continue on error**

## LogType
<a name="lam.invoke.log.type"></a>

(*LambdaInvoke*/Configuration/**LogType**)

(Optional)

Specify whether you want to include error logs in the response from the Lambda function after it is invoked. You can view these logs in the **Lambda invoke** action's **Logs** tab in the CodeCatalyst console. Possible values are:
+ `Tail` – return logs
+ `None` – do not return logs

The default is **Tail**.

For more information about the log type, see the [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) topic in the *AWS Lambda API Reference*.

For more information about viewing logs, see [Viewing workflow run status and details](workflows-view-run.md).

Corresponding UI: Configuration tab/**Log type**

## ResponseFilters
<a name="lam.invoke.response.filters"></a>

(*LambdaInvoke*/Configuration/**ResponseFilters**)

(Optional)

Specify which keys in the Lambda response payload you want to convert to output variables. You can then reference the output variables in subsequent actions in your workflow. For more information about variables in CodeCatalyst, see [Using variables in workflows](workflows-working-with-variables.md).

For example, if your response payload looks like this:

```
responsePayload = {
  "name": "Saanvi",
  "location": "Seattle",
  "department": {
    "company": "Amazon",
    "team": "AWS"
  }
}
```

...and your response filters look like this:

```
Configuration:
  ...
  ResponseFilters: '{"name": ".name", "company": ".department.company"}'
```

...then the action generates the following output variables:


| Key | Value | 
| --- | --- | 
|  name  |  Saanvi  | 
|  company  |  Amazon  | 

You can then reference the `name` and `company` variables in subsequent actions.

If you do not specify any keys in `ResponseFilters`, then the action converts each top-level key in the Lambda response into an output variable. For more information, see ['AWS Lambda invoke' variables](lam-invoke-action-variables.md).

Consider using response filters to limit the generated output variables to only those you actually want to use.

Corresponding UI: Configuration tab/**Response filters - optional**

## Outputs
<a name="lam.invoke.outputs"></a>

(*LambdaInvoke*/**Outputs**)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts
<a name="lam.invoke.outputs.artifacts"></a>

(*LambdaInvoke*/Outputs/**Artifacts**)

(Optional)

Specify the artifacts generated by the action. You can reference these artifacts as input in other actions.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/Artifacts/**Build artifact name**

## Name
<a name="lam.invoke.outputs.artifacts.name"></a>

(*LambdaInvoke*/Outputs/Artifacts/**Name**)

(Optional)

Specify the name of the artifact that will contain the Lambda response payload that is returned by the Lambda function. The default value is `lambda_artifacts`. If you do not specify an artifact, then the Lambda response payload can be viewed in the action's logs, which are available on the **Logs** tab for the action in the CodeCatalyst console. For more information about viewing logs, see [Viewing workflow run status and details](workflows-view-run.md).

Corresponding UI: Outputs tab/Artifacts/**Build artifact name**

## Files
<a name="lam.invoke.outputs.artifacts.files"></a>

(*LambdaInvoke*/Outputs/Artifacts/**Files**)

(Optional)

Specify the files to include in the artifact. You must specify `lambda-response.json` so that the Lambda response payload file will be included.

Corresponding UI: Outputs tab/Artifacts/**Files produced by build**

# Modifying an Amazon ECS task definition
<a name="render-ecs-action"></a>

This section describes how to update the `image` field in an Amazon Elastic Container Service (Amazon ECS) [task definition file](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions) using a CodeCatalyst workflow. To accomplish this, you must add the **Render Amazon ECS task definition** action to your workflow. This action updates the image field in the task definition file with a Docker image name that is supplied by your workflow at runtime.

**Note**  
You can also use this action to update the task definition’s `environment` field with environment variables.

**Topics**
+ [

## When to use this action
](#render-ecs-action-when-to-use)
+ [

## How the 'Render Amazon ECS task definition' action works
](#render-ecs-action-how-it-works)
+ [

## Runtime image used by the 'Render Amazon ECS task definition' action
](#render-ecs-action-runtime)
+ [

# Example: Modify an Amazon ECS taskdef
](render-ecs-action-example-workflow.md)
+ [

# Adding the 'Render Amazon ECS task definition' action
](render-ecs-action-add.md)
+ [

# Viewing the updated task definition file
](render-ecs-action-view.md)
+ [

# 'Render Amazon ECS task definition' variables
](render-ecs-action-variables.md)
+ [

# 'Render Amazon ECS task definition' action YAML
](render-ecs-action-ref.md)

## When to use this action
<a name="render-ecs-action-when-to-use"></a>

Use this if you have a workflow that builds and tags a Docker image with dynamic content, such as a commit ID or timestamp. 

Do not use this action if your task definition file contains an image value that always stays the same. In this case, you can manually enter the name of your image into the task definition file.

## How the 'Render Amazon ECS task definition' action works
<a name="render-ecs-action-how-it-works"></a>

You must use the **Render Amazon ECS task definition** action with the **build** and **Deploy to Amazon ECS** actions in your workflow. Together, these actions work as follows:

1. The **build** action builds your Docker image and tags it with a name, a commit ID, timestamp, or other dynamic content. For example, your build action might look like this:

   ```
   MyECSWorkflow
     Actions:
       BuildAction:
         Identifier: aws/build@v1
         ...
         Configuration:
           Steps:
           # Build, tag, and push the Docker image...
             - Run: docker build -t MyDockerImage:${WorkflowSource.CommitId} .
             ...
   ```

   In the preceding code, the `docker build -t` directive indicates to build the Docker image and tag it with the commit ID at action runtime. The generated image name might look like this:

   `MyDockerImage:a37bd7e`

1. The **Render Amazon ECS task definition** action adds the dynamically generated image name, `MyDockerImage:a37bd7e`, to your task definition file, like this:

   ```
   {
       "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
       "containerDefinitions": [
           {
               "name": "codecatalyst-ecs-container",
               "image":  MyDockerImage:a37bd7e, 
               "essential": true,
               ...
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ]
           }
       ],
   ...
   }
   ```

   Optionally, you can also have the **Render Amazon ECS task definition** action add environment variables to the task definition, like this:

   ```
   {
     "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
     "containerDefinitions": [
       {
         "name": "codecatalyst-ecs-container",
         "image":  MyDockerImage:a37bd7e,
         ...
         "environment": [
           {
             name": "ECS_LOGLEVEL",
             value": "info"
           }
         ]
       }
     ],
   ...
   }
   ```

   For more information about environment variables, see [Specifying environment variables](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html) in the *Amazon Elastic Container Service Developer Guide*.

1. The **Deploy to Amazon ECS** action registers the updated task definition file with Amazon ECS. Registering the updated task definition file deploys the new image, `MyDockerImage:a37bd7e` into Amazon ECS.

## Runtime image used by the 'Render Amazon ECS task definition' action
<a name="render-ecs-action-runtime"></a>

The **Render Amazon ECS task definition** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Example: Modify an Amazon ECS taskdef
<a name="render-ecs-action-example-workflow"></a>

The following is an example of a full workflow that includes the **Render Amazon ECS task definition** action, along with build and deploy actions. The workflow’s purpose is to build and deploy a Docker image into your Amazon ECS cluster. The workflow consists of the following building blocks that run sequentially:
+ A **trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). 
+ A **build** action (`BuildDocker`) – On trigger, the action builds the Docker image using the Dockerfile, tags it with a commit ID, and pushes the image to Amazon ECR. For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ A **Render Amazon ECS task definition** action (`RenderTaskDef`) – On completion of the build action, this action updates an existing `taskdef.json` located in the root of your source repository with an `image` field value that includes the correct commit ID. It saves the updated file with a new file name (`task-definition-random-string.json`) and then creates an output artifact that contains this file. The render action also generates a variable called `task-definition` and sets it to the name of the new task definition file. The artifact and variable will be used the deploy action, which is next.
+ A **Deploy to Amazon ECS** action (`DeployToECS`) – On completion of the **Render Amazon ECS task definition** action, the **Deploy to Amazon ECS** action looks for the output artifact generated by the render action (`TaskDefArtifact`), finds the `task-definition-random-string.json` file inside of it, and registers it with your Amazon ECS service. The Amazon ECS service then follows the instructions in the `task-definition-random-string.json` file to run Amazon ECS tasks—and associated Docker image containers—inside your Amazon ECS cluster. 

```
Name: codecatalyst-ecs-workflow
SchemaVersion: 1.0

Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  BuildDocker:
    Identifier: aws/build@v1
    Environment:
      Name: codecatalyst-ecs-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-ecs-build-role
    Inputs:
      Variables:
        - Name: REPOSITORY_URI
          Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
        - Name: IMAGE_TAG
          Value: ${WorkflowSource.CommitId}
    Configuration:
      Steps:
        #pre_build:
        - Run: echo Logging in to Amazon ECR...
        - Run: aws --version
        - Run: aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-2.amazonaws.com
        #build:
        - Run: echo Build started on `date`
        - Run: echo Building the Docker image...
        - Run: docker build -t $REPOSITORY_URI:latest .
        - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
        #post_build:
        - Run: echo Build completed on `date`
        - Run: echo Pushing the Docker images...
        - Run: docker push $REPOSITORY_URI:latest
        - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
        
  RenderTaskDef:
    DependsOn: 
      - BuildDocker
    Identifier: aws/ecs-render-task-definition@v1
    Inputs:
      Variables:
        - Name: REPOSITORY_URI
          Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
        - Name: IMAGE_TAG
          Value: ${WorkflowSource.CommitId}
    Configuration:      
      task-definition: taskdef.json
      container-definition-name: codecatalyst-ecs-container
      image: $REPOSITORY_URI:$IMAGE_TAG 
    # The output artifact contains the updated task definition file. 
    # The new file is prefixed with 'task-definition'.
    # The output variable is set to the name of the updated task definition file. 
    Outputs:
      Artifacts:
        - Name: TaskDefArtifact
          Files: 
            - "task-definition*"
      Variables:
        - task-definition
        
  DeployToECS:
    Identifier: aws/ecs-deploy@v1
    Environment:
      Name: codecatalyst-ecs-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-ecs-deploy-role
    #Input artifact contains the updated task definition file.
    Inputs:
      Sources: []
      Artifacts:
        - TaskDefArtifact
    Configuration:
      region: us-east-2
      cluster: codecatalyst-ecs-cluster
      service: codecatalyst-ecs-service
      task-definition: ${RenderTaskDef.task-definition}
```

# Adding the 'Render Amazon ECS task definition' action
<a name="render-ecs-action-add"></a>

 Use the following instructions to add the **Render Amazon ECS task definition** action to your workflow. 

**Prerequisite**  
Before you begin, make sure you have a workflow that includes a build action that dynamically generates a Docker image. See the preceding [example workflow](render-ecs-action-example-workflow.md) for details.

------
#### [ Visual ]

**To add the 'Render Amazon ECS task definition' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Render Amazon ECS task definition** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Render Amazon ECS task definition**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Render Amazon ECS task definition' action YAML](render-ecs-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'Render Amazon ECS task definition' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Render Amazon ECS task definition** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Render Amazon ECS task definition**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Render Amazon ECS task definition' action YAML](render-ecs-action-ref.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

**Next steps**

After adding the render action, add the **Deploy to Amazon ECS** action to your workflow following the instructions in [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md). While adding the deploy action, do the following:

1. In the **Inputs** tab of the deploy action, in **Artifacts - optional**, select the artifact that was generated by the render action. It contains the updated task definition file.

   For more information about artifacts, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

1. In the **Configuration** tab of the deploy action, in the **Task definition** field, specify the following action variable: `${action-name.task-definition}` where *action-name* is the name of your render action, for example, `RenderTaskDef`. The render action sets this variable to the new name of the task definition file.

   For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

   For more information about how to configure the deploy action, see the preceding [example workflow](render-ecs-action-example-workflow.md).

# Viewing the updated task definition file
<a name="render-ecs-action-view"></a>

You can view the name and contents of the updated task definition file.

**To view the name of the updated task definition file, after the **Render Amazon ECS task definition** action has processed it.**

1. Find the run that includes a completed render action:

   1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

   1. Choose your project.

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

   1. Choose a run that includes the completed render action.

1. In the workflow diagram, choose the render action.

1. Choose **Outputs**.

1. Choose **Variables**.

1. The task definition file name is displayed. It looks similar to `task-definition--259-0a2r7gxlTF5X-.json`.

**To view the contents of the updated task definition file**

1. Find the run that includes a completed render action:

   1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

   1. Choose your project.

   1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

   1. Choose a run that includes the completed render action.

1. In the workflow run, at the top, next to **Visual** and **YAML**, choose **Workflow outputs**.

1. In the **Artifacts** section, choose **Download** next to the artifact that contains the updated task definition file. This artifact will have a **Produced by** column set to the name of your render action.

1. Open the .zip file to view the task definition .json file.

# 'Render Amazon ECS task definition' variables
<a name="render-ecs-action-variables"></a>

The **Render Amazon ECS task definition** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  task-definition  |  The name given to the task definition file that was updated by the **Render Amazon ECS task definition** action. The name follows the format `task-definition-random-string.json`. Example: `task-definition--259-0a2r7gxlTF5Xr.json`  | 

# 'Render Amazon ECS task definition' action YAML
<a name="render-ecs-action-ref"></a>

The following is the YAML definition of the **Render Amazon ECS task definition** action. To learn how to use this action, see [Modifying an Amazon ECS task definition](render-ecs-action.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

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

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  ECSRenderTaskDefinition\$1nn: 
    Identifier: aws/ecs-render-task-definition@v1
    DependsOn:
      - build-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - task-definition-artifact
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2
    Configuration 
      task-definition: task-definition-path
      container-definition-name: container-definition-name
      image: docker-image-name
      environment-variables:
        - variable-name-1=variable-value-1
        - variable-name-2=variable-value-2
    Outputs:
      Artifacts:
        - Name: TaskDefArtifact
          Files: "task-definition*"
      Variables:
        - task-definition
```

## ECSRenderTaskDefinition
<a name="render.ecs.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `ECSRenderTaskDefinition_nn`.

Corresponding UI: Configuration tab/**Action name**

## Identifier
<a name="render.ecs.identifier"></a>

(*ECSRenderTaskDefinition*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/ecs-render-task-definition@v1`.

Corresponding UI: Workflow diagram/ECSRenderTaskDefinition\$1nn/**aws/ecs-render-task-definition@v1** label

## DependsOn
<a name="render.ecs.dependson"></a>

(*ECSRenderTaskDefinition*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="render.ecs.computename"></a>

(*ECSRenderTaskDefinition*/**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](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="render.ecs.computetype"></a>

(*ECSRenderTaskDefinition*/Compute/**Type**)

(Required if [Compute](#render.ecs.computename) is included)

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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/**Compute type**

## Fleet
<a name="render.ecs.computefleet"></a>

(*ECSRenderTaskDefinition*/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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/**Compute fleet**

## Timeout
<a name="render.ecs.timeout"></a>

(*ECSRenderTaskDefinition*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Inputs
<a name="render.ecs.inputs"></a>

(*ECSRenderTaskDefinition*/**Inputs**)

(Optional)

The `Inputs` section defines the data that the `ECSRenderTaskDefinition` needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed per **Render Amazon ECS task definition** action. Variables do not count towards this total.

Corresponding UI: **Inputs** tab

## Sources
<a name="render.ecs.inputs.sources"></a>

(*ECSRenderTaskDefinition*/Inputs/**Sources**)

(Required if your task definition file is stored in a source repository)

If your task definition file is stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your task definition file is not contained within a source repository, it must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="render.ecs.inputs.artifacts"></a>

(*ECSRenderTaskDefinition*/Inputs/**Artifacts**)

(Required if your task definition file is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the task definition file that you want to deploy is contained in an artifact generated by a previous action, specify that artifact here. If your task definition file is not contained within an artifact, it must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Variables - input
<a name="render.ecs.inputs.variables"></a>

(*ECSRenderTaskDefinition*/Inputs/**Variables**)

(Required)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Inputs tab/**Variables - optional**

## Configuration
<a name="render.ecs.configuration"></a>

(*ECSRenderTaskDefinition*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## task-definition
<a name="render.ecs.task.definition"></a>

(*ECSRenderTaskDefinition*/Configuration/**task-definition**)

(Required)

Specify the path to an existing task definition file. If the file resides in your source repository, the path is relative to the source repository root folder. If your file resides in an artifact from a previous workflow action, the path is relative to the artifact root folder. For more information about task definition files, see [Task definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html#welcome-task-definitions) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Task definition**

## container-definition-name
<a name="render.ecs.container.name"></a>

(*ECSRenderTaskDefinition*/Configuration/**container-definition-name**)

(Required)

Specify the name of the container where your Docker image will run. You can find this name in the `containerDefinitions`, `name` field in your task definition file. For more information, see [Name](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_name) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Container name**

## image
<a name="render.ecs.image"></a>

(*ECSRenderTaskDefinition*/Configuration/**image**)

(Required)

Specify the name of the Docker image that you want the **Render Amazon ECS task definition** action to add to your task definition file. The action adds this name to the `containerDefinitions`, `image` field in your task definition file. If a value already exists in the `image` field, then the action overwrites it. You can include variables in the image name.

Examples:

If you specify `MyDockerImage:${WorkflowSource.CommitId}`, the action adds `MyDockerImage:commit-id` to the task definition file, where *commit-id* is a commit ID generated at runtime by the workflow.

If you specify `my-ecr-repo/image-repo:$(date +%m-%d-%y-%H-%m-%s)`, the action adds *my-ecr-repo*/image-repo:*date \$1%m-%d-%y-%H-%m-%s* to the task definition file, where *my-ecr-repo* is the URI of an Amazon Elastic Container Registry (ECR) and *date \$1%m-%d-%y-%H-%m-%s* is a timestamp in the format `month-day-year-hour-minute-second` generated at runtime by the workflow.

For more information about the `image` field, see [Image](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_image) in the *Amazon Elastic Container Service Developer Guide*. For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

Corresponding UI: Configuration tab/**Image name**

## environment-variables
<a name="render.ecs.environment.variables"></a>

(*ECSRenderTaskDefinition*/Configuration/**environment-variables**)

(Required)

Specify environment variables that you want the **Render Amazon ECS task definition** action to add to your task definition file. The action adds the variables to the `containerDefinitions`, `environment` field in your task definition file. If variables already exist in the file, the action overwrites the values of existing variables and adds any new variables. For more information about Amazon ECS environment variables, see [Specifying environment variables](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html) in the *Amazon Elastic Container Service Developer Guide*.

Corresponding UI: Configuration tab/**Environment variables - optional**

## Outputs
<a name="render.ecs.outputs"></a>

(*ECSRenderTaskDefinition*/**Outputs**)

(Required)

Defines the data that is output by the action during a workflow run.

Corresponding UI: **Outputs** tab

## Artifacts
<a name="render.ecs.outputs.artifacts"></a>

(*ECSRenderTaskDefinition*/Outputs/**Artifacts**)

(Required)

Specify the artifacts generated by the action. You can reference these artifacts as input in other actions.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Outputs tab/**Artifacts**

## Name
<a name="render.ecs.outputs.artifacts.name"></a>

(*ECSRenderTaskDefinition*/Outputs/Artifacts/**Name**)

(Required)

Specify the name of the artifact that will contain the updated task definition file. The default value is `MyTaskDefinitionArtifact`. You must then specify this artifact as input into the **Deploy to Amazon ECS** action. To understand how to add this artifact as input to the **Deploy to Amazon ECS** action, see [Example: Modify an Amazon ECS taskdef](render-ecs-action-example-workflow.md).

Corresponding UI: Outputs tab/Artifacts/**Name**

## Files
<a name="render.ecs.outputs.artifacts.files"></a>

(*ECSRenderTaskDefinition*/Outputs/Artifacts/**Files**)

(Required)

Specify the files to include in the artifact. You must specify `task-definition-*` so that the updated task definition file, which starts with `task-definition-`, will be included.

Corresponding UI: Outputs tab/Artifacts/**Files**

## Variables
<a name="render.ecs.outputs.variables"></a>

(*ECSRenderTaskDefinition*/Outputs/**Variables**)

(Required)

Specify the name of a variable to be set by the render action. The render action will set this variable's value to the name of the updated task definition file (for example, `task-definition-random-string.json`). You must then specify this variable in the **Deploy to Amazon ECS** action's **Task definition** (visual editor) or `task-definition` (yaml editor) property. To understand how to add this variable to the **Deploy to Amazon ECS** action, see [Example: Modify an Amazon ECS taskdef](render-ecs-action-example-workflow.md) .

Default: `task-definition`

Corresponding UI: Outputs tab/Variables/**Name** field

# Using variables in workflows
<a name="workflows-working-with-variables"></a>

 A *variable* is a key-value pair that contains information that you can reference in your Amazon CodeCatalyst workflow. The value portion of the variable is replaced with an actual value when the workflow runs.

There are two types of variable that you can use in a workflow:
+ **User-defined variables** – These are key-value pairs that you define.
+ **Predefined variables** – These are key-value pairs that are emitted by a workflow automatically. There is no need for you to define them.

For more information about workflows, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md).

**Note**  
CodeCatalyst also supports [GitHub output parameters](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter), which behave like variables and can be referenced in other actions. For more information, see [Exporting GitHub output parameters](integrations-github-action-export.md) and [Referencing GitHub output parameters](integrations-github-action-referencing.md)

**Topics**
+ [

# Using user-defined variables
](workflows-using-variables.md)
+ [

# Using predefined variables
](workflows-using-predefined-variables.md)

# Using user-defined variables
<a name="workflows-using-variables"></a>

*User-defined variables* are key-value pairs that you define. There are two types:
+ **Plaintext variables**, or simply **variables** – These are key-value pairs that you define in plaintext within the workflow definition file.
+ **Secrets** – These are key-value pairs that you define on a separate **Secrets** page of the Amazon CodeCatalyst console. The *key* (name) is a public label, and the *value* contains the information you want to keep private. You only specify the key in the workflow definition file. Use secrets in place of passwords and other sensitive information in the workflow definition file.

**Note**  
For brevity, this guide uses the term *variable* to mean *plaintext variable*.

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Topics**
+ [

# Examples of variables
](workflows-working-with-variables-ex.md)
+ [

# Defining a variable
](workflows-working-with-variables-define-input.md)
+ [

# Defining a secret
](workflows-working-with-variables-define-secret.md)
+ [

# Exporting a variable so that other actions can use it
](workflows-working-with-variables-export-input.md)
+ [

# Referencing a variable in the action that defines it
](workflows-working-with-variables-reference-input.md)
+ [

# Referencing a variable output by another action
](workflows-working-with-variables-reference-action.md)
+ [

# Referencing a secret
](workflows-working-with-variables-reference-secret.md)

# Examples of variables
<a name="workflows-working-with-variables-ex"></a>

The following examples show how to define and reference variables in the workflow definition file.

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Topics**
+ [

## Example: Defining a variable using the Inputs property
](#workflows-working-with-variables-ex-define-inputs)
+ [

## Example: Defining a variable using the Steps property
](#workflows-working-with-variables-ex-define-steps)
+ [

## Example: Exporting a variable using the Outputs property
](#workflows-working-with-variables-ex-export-outputs)
+ [

## Example: Referencing a variable defined in the same action
](#workflows-working-with-variables-ex-refer-current)
+ [

## Example: Referencing a variable defined in another action
](#workflows-working-with-variables-ex-refer-other)
+ [

## Example: Referencing a secret
](#workflows-working-with-variables-ex-refer-secret)

## Example: Defining a variable using the Inputs property
<a name="workflows-working-with-variables-ex-define-inputs"></a>

The following example shows you how to define two variables, `VAR1` and `VAR2`, in an `Inputs` section.

```
Actions:
  Build:
    Identifier: aws/build@v1
    Inputs:
      Variables:
      - Name: VAR1
        Value: "My variable 1"
      - Name: VAR2
        Value: "My variable 2"
```

## Example: Defining a variable using the Steps property
<a name="workflows-working-with-variables-ex-define-steps"></a>

The following example shows you how to define a `DATE` variable in the `Steps` section explicitly.

```
Actions:
  Build:
    Identifier: aws/build@v1
    Configuration:    
      Steps:
        - Run: DATE=$(date +%m-%d-%y)
```

## Example: Exporting a variable using the Outputs property
<a name="workflows-working-with-variables-ex-export-outputs"></a>

The following example shows you how to define two variables, `REPOSITORY-URI` and `TIMESTAMP`, and export them using the `Outputs` section.

```
Actions:
  Build:
    Identifier: aws/build@v1
    Inputs:
      Variables:
        - Name: REPOSITORY-URI
          Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
    Configuration:
      Steps:
        - Run: TIMESTAMP=$(date +%m-%d-%y-%H-%m-%s) 
    Outputs:
      Variables:
        - REPOSITORY-URI
        - TIMESTAMP
```

## Example: Referencing a variable defined in the same action
<a name="workflows-working-with-variables-ex-refer-current"></a>

The following example shows you how to specify a `VAR1` variable in `MyBuildAction`, and then reference it in the same action using `$VAR1`.

```
Actions:
  MyBuildAction:
    Identifier: aws/build@v1
    Inputs:
      Variables:
        - Name: VAR1
          Value: my-value
    Configuration:
      Steps:
        - Run: $VAR1
```

## Example: Referencing a variable defined in another action
<a name="workflows-working-with-variables-ex-refer-other"></a>

The following example shows you how to specify a `TIMESTAMP` variable in `BuildActionA`, export it using the `Outputs` property, and then reference it in `BuildActionB` using `${BuildActionA.TIMESTAMP}`.

```
Actions:
  BuildActionA:
    Identifier: aws/build@v1
    Configuration:    
      Steps:
        - Run: TIMESTAMP=$(date +%m-%d-%y-%H-%m-%s) 
    Outputs:
      Variables:
        - TIMESTAMP
  BuildActionB:
    Identifier: aws/build@v1
    Configuration:
      Steps:
        - Run: docker build -t my-ecr-repo/image-repo:latest .      
        - Run: docker tag my-ecr-repo/image-repo:${BuildActionA.TIMESTAMP}
        
        # Specifying just '$TIMESTAMP' here will not work 
        # because TIMESTAMP is not a variable 
        # in the BuildActionB action.
```

## Example: Referencing a secret
<a name="workflows-working-with-variables-ex-refer-secret"></a>

The following example shows you how to reference a `my-password` secret. The `my-password` is the secret's key. This secret's key and corresponding password value must be specified on the **Secrets** page of the CodeCatalyst console prior to being used in the workflow definition file. For more information, see [Masking data using secrets](workflows-secrets.md).

```
Actions:
  BuildActionA:
    Identifier: aws/build@v1
    Configuration:    
      Steps:
        - Run: curl -u LiJuan:${Secrets.my-password} https://example.com
```

# Defining a variable
<a name="workflows-working-with-variables-define-input"></a>

You can define variables in two ways:
+ In the `Inputs` section of a workflow action – see [To define a variable in the 'Inputs' section](#workflows-to-define-variable-input)
+ In the `Steps` section of a workflow action – see [To define a variable in the 'Steps' section](#workflows-to-define-variable-steps)
**Note**  
The `Steps` method only works with the CodeCatalyst build, test, and **GitHub Actions** actions, because these are the only actions that include a `Steps` section.

For examples, see [Examples of variables](workflows-working-with-variables-ex.md).

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

------
#### [ Visual ]

**To define a variable in the 'Inputs' section (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action where you want to set the variable.

1. Choose **Inputs**.

1. In **Variables - optional**, choose **Add variable**, and then do the following:

   Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

   For more information about variables, including examples, see [Using variables in workflows](workflows-working-with-variables.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To define a variable in the 'Inputs' section (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a workflow action, add code similar to the following:

   ```
   action-name:
     Inputs:
       Variables:
         - Name: variable-name
           Value: variable-value
   ```

   For more examples, see [Examples of variables](workflows-working-with-variables-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

------
#### [ Visual ]

**To define a variable in the 'Steps' section (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action where you want to set the variable.

1. Choose **Configuration**.

1. In **Shell commands** or **GitHub Actions YAML**, whichever is available, define a variable in the action's `Steps`, either explicitly or implicitly.
   + To define the variable explicitly, include it in a bash command directly to the `Steps` section.
   + To define a variable implicitly, specify it in a file that's referenced in the action's `Steps` section.

     For examples, see [Examples of variables](workflows-working-with-variables-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for the action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To define a variable in the 'Steps' section (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a workflow action, define a variable in the action's `Steps` section, either explicitly or implicitly.
   + To define the variable explicitly, include it in a bash command directly to the `Steps` section.
   + To define a variable implicitly, specify it in a file that's referenced in the action's `Steps` section.

     For examples, see [Examples of variables](workflows-working-with-variables-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for the action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Defining a secret
<a name="workflows-working-with-variables-define-secret"></a>

You define a secret on the **Secrets** page of the CodeCatalyst console. For more information, see [Masking data using secrets](workflows-secrets.md).

For example, you might define a secret that looks like this:
+ Name (key): **my-password**
+ Value: **^\$1H3\$1\$1b9**

After the secret is defined, you can specify the secret's key (**my-password**) in the workflow definition file. For an example of how to do this, see [Example: Referencing a secret](workflows-working-with-variables-ex.md#workflows-working-with-variables-ex-refer-secret).

# Exporting a variable so that other actions can use it
<a name="workflows-working-with-variables-export-input"></a>

Use the following instructions to export a variable from an action so that you can reference it in other actions.

Before you export a variable, note the following:
+ If you only need to reference the variable within the action where it's defined, then you don't need to export it.
+ Not all actions support exporting variables. To determine whether your action supports this feature, run through the visual editor instructions that follow, and see if the action includes a **Variables** button on the **Outputs** tab. If yes, exporting variables is supported. 
+ To export a variable from a GitHub Action, see [Exporting GitHub output parameters](integrations-github-action-export.md).

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Prerequisite**  
Make sure you have defined the variable you want to export. For more information, see [Defining a variable](workflows-working-with-variables-define-input.md).

------
#### [ Visual ]

**To export a variable (visual editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. In the workflow diagram, choose the action that you want to export the variable from.

1. Choose **Outputs**.

1. In **Variables - optional**, choose **Add variable**, and then do the following:

   Specify the name of a variable that you want the action to export. This variable must already be defined in the `Inputs` or `Steps` section of the same action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To export a variable (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the action that you want to export the variable from, add code similar to the following:

   ```
   action-name:
     Outputs:
       Variables:
         - Name: variable-name
   ```

   For more examples, see [Examples of variables](workflows-working-with-variables-ex.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Referencing a variable in the action that defines it
<a name="workflows-working-with-variables-reference-input"></a>

Use the following instructions to reference a variable in the action that defines it.

**Note**  
To reference a variable generated by a GitHub Action, see [Referencing GitHub output parameters](integrations-github-action-referencing.md).

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Prerequisite**  
Make sure you have defined the variable you want to reference. For more information, see [Defining a variable](workflows-working-with-variables-define-input.md).

------
#### [ Visual ]

*Not available. Choose YAML to view the YAML instructions.*

------
#### [ YAML ]

**To reference a variable in the action that defines it**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the CodeCatalyst action that defines the variable that you want to refer to, add the variable using the following bash syntax:

   ```
   $variable-name
   ```

   For example:

   ```
   MyAction:
       Configuration:
         Steps:
           - Run: $variable-name
   ```

   For more examples, see [Examples of variables](workflows-working-with-variables-ex.md). For more information, see the reference information for your action in the [Workflow YAML definition](workflow-reference.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Referencing a variable output by another action
<a name="workflows-working-with-variables-reference-action"></a>

Use the following instructions to reference variables output by other actions.

**Note**  
 To reference a variable output from a GitHub Action, see [Referencing GitHub output parameters](integrations-github-action-referencing.md).

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Prerequisite**  
Make sure you have exported the variable you want to reference. For more information, see [Exporting a variable so that other actions can use it](workflows-working-with-variables-export-input.md).

------
#### [ Visual ]

*Not available. Choose YAML to view the YAML instructions.*

------
#### [ YAML ]

**To reference a variable output by another action (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In the CodeCatalyst action, add a reference to the variable using the following syntax:

   ```
   ${action-group-name.action-name.variable-name}
   ```

   Replace:
   + *action-group-name* with the name of the action group that contains the action that outputs variable.
**Note**  
You can omit *action-group-name* if there is no action group, or if the variable is produced by an action in the same action group.
   + *action-name* with the name of the action that outputs the variable.
   + *variable-name* with the name of the variable.

   For example:

   ```
   MySecondAction:
       Configuration:
         Steps:
           - Run: ${MyFirstAction.TIMESTAMP}
   ```

   For more examples, see [Examples of variables](workflows-working-with-variables-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Referencing a secret
<a name="workflows-working-with-variables-reference-secret"></a>

For instructions on referencing a secret in the workflow definition file, see [Using a secret](workflows-secrets.using.md).

For an example, see [Example: Referencing a secret](workflows-working-with-variables-ex.md#workflows-working-with-variables-ex-refer-secret).

# Using predefined variables
<a name="workflows-using-predefined-variables"></a>

*Predefined variables* are key-value pairs that are emitted by a workflow automatically, and made available for you to use in workflow actions. 

For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md).

**Topics**
+ [

# Examples of referencing predefined variables
](workflows-predefined-examples.md)
+ [

# Referencing a predefined variable
](workflows-working-with-variables-reference-output-vars.md)
+ [

# Determining which predefined variables your workflow emits
](workflows-working-with-variables-determine-output-vars.md)
+ [

# List of predefined variables
](workflow-ref-action-variables.md)

# Examples of referencing predefined variables
<a name="workflows-predefined-examples"></a>

The following examples show how to reference predefined variables in the workflow definition file.

For more information about predefined variables, see [Using predefined variables](workflows-using-predefined-variables.md).

**Topics**
+ [

## Example: Referencing the "CommitId" predefined variable
](#workflows-working-with-variables-ex-refer-action)
+ [

## Example: Referencing the "BranchName" predefined variable
](#workflows-working-with-variables-ex-branch)

## Example: Referencing the "CommitId" predefined variable
<a name="workflows-working-with-variables-ex-refer-action"></a>

The following example shows you how to refer to the `CommitId` predefined variable in the `MyBuildAction` action. The `CommitId` variable is output automatically by CodeCatalyst. For more information, see [List of predefined variables](workflow-ref-action-variables.md).

Although the example shows the variable being used in the build action, you can use `CommitId` in any action.

```
MyBuildAction:
    Identifier: aws/build@v1
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Steps:
      #Build Docker image and tag it with a commit ID
        - Run: docker build -t image-repo/my-docker-image:latest .
        - Run: docker tag image-repo/my-docker-image:${WorkflowSource.CommitId}
```

## Example: Referencing the "BranchName" predefined variable
<a name="workflows-working-with-variables-ex-branch"></a>

The following example shows you how to refer to the `BranchName` predefined variable in the `CDKDeploy` action. The `BranchName` variable is output automatically by CodeCatalyst. For more information, see [List of predefined variables](workflow-ref-action-variables.md).

Although the example shows the variable being used in the **AWS CDK deploy** action, you can use `BranchName` in any action.

```
CDKDeploy:
    Identifier: aws/cdk-deploy@v2
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      StackName: app-stack-${WorkflowSource.BranchName}
```

# Referencing a predefined variable
<a name="workflows-working-with-variables-reference-output-vars"></a>

You can reference predefined variables in any action within an Amazon CodeCatalyst workflow.

Use the following instructions to reference a predefined variable in a workflow.

For more information about predefined variables, see [Using predefined variables](workflows-using-predefined-variables.md).

**Prerequisite**  
Determine the name of the predefined variable you want to reference, such as `CommitId`. For more information, see [Determining which predefined variables your workflow emits](workflows-working-with-variables-determine-output-vars.md).

------
#### [ Visual ]

*Not available. Choose YAML to view the YAML instructions.*

------
#### [ YAML ]

**To reference a predefined variable (YAML editor)**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. In a CodeCatalyst action, add the predefined variable reference using the following syntax:

   ```
   ${action-group-name.action-name-or-WorkflowSource.variable-name}
   ```

   Replace:
   + *action-group-name* with the name of the action group.
**Note**  
You can omit *action-group-name* if there is no action group, or if the variable is produced by an action in the same action group.
   + *action-name-or-WorkflowSource* with:

     The name of the action that outputs the variable.

     or

     `WorkflowSource`, if the variable is the `BranchName` or `CommitId` variable.
   + *variable-name* with the name of the variable.

   For example:

   ```
   MySecondAction:
       Configuration:
         Steps:
           - Run: echo ${MyFirstECSAction.cluster}
   ```

   Another example:

   ```
   MySecondAction:
       Configuration:
         Steps:
           - Run: echo ${WorkflowSource.CommitId}
   ```

   For more examples, see [Examples of referencing predefined variables](workflows-predefined-examples.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# Determining which predefined variables your workflow emits
<a name="workflows-working-with-variables-determine-output-vars"></a>

Use the following procedure to determine which predefined variables a workflow emits when it runs. You can then reference these variables within the same workflow. 

For more information about predefined variables, see [Using predefined variables](workflows-using-predefined-variables.md).

**To determine the predefined variables that your workflow emits**
+ Do one of the following:
  + **Run the workflow once**. After the run finishes, the variables emitted by the workflow are displayed on the **Variables** tab of the run details page. For more information, see [Viewing workflow run status and details](workflows-view-run.md).
  + **Consult the [List of predefined variables](workflow-ref-action-variables.md)**. This reference lists the variable name (key) and value for each predefined variable.

**Note**  
The maximum total size of a workflow's variables is listed in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). If the total size exceeds the maximum, the action that occurs after the maximum is reached may fail.

# List of predefined variables
<a name="workflow-ref-action-variables"></a>

Consult the following sections to view the predefined variables produced automatically by CodeCatalyst actions as part of a workflow run.

For more information about predefined variables, see [Using predefined variables](workflows-using-predefined-variables.md).

**Note**  
This list only includes predefined variables emitted by the CodeCatalyst source and [CodeCatalyst actions](workflows-actions.md#workflows-actions-types). If you're using other types of actions, such as GitHub Actions or CodeCatalyst Labs actions, see instead [Determining which predefined variables your workflow emits](workflows-working-with-variables-determine-output-vars.md).

**List**

**Note**  
Not all CodeCatalyst actions produce predefined variables. If the action is not in the list, then it does not produce variables.
+ ['BranchName' and 'CommitId' variables](workflows-sources-variables.md)
+ ['Deploy CloudFormation stack' variables](deploy-action-cfn-variables.md)
+ ['Deploy to Amazon ECS' variables](deploy-action-ecs-variables.md)
+ ['Deploy to Kubernetes cluster' variables](deploy-action-eks-variables.md)
+ ['AWS CDK deploy' variables](cdk-dep-action-variables.md)
+ ['AWS CDK bootstrap' variables](cdk-boot-action-variables.md)
+ ['AWS Lambda invoke' variables](lam-invoke-action-variables.md)
+ ['Render Amazon ECS task definition' variables](render-ecs-action-variables.md)

# Masking data using secrets
<a name="workflows-secrets"></a>

There may be times when you need to use sensitive data, such as authentication credentials, in your workflows. Storing these values in plaintext anywhere in your repository should be avoided because anyone with access to the repository which contains the secret can see them. Similarly, these values shouldn't be used directly in any workflow definitions because they will be visible as files in your repository. With CodeCatalyst, you can protect these values by adding a secret to your project, and then referencing the secret in your workflow definition file. Note that you can have a maximum of five secrets per action.

**Note**  
Secrets can only be used to replace passwords and sensitive information in the workflow definition file.

**Topics**
+ [

# Creating a secret
](workflows-secrets.creating.md)
+ [

# Editing a secret
](workflows-secrets.editing.md)
+ [

# Using a secret
](workflows-secrets.using.md)
+ [

# Deleting a secret
](workflows-secrets.deleting.md)

# Creating a secret
<a name="workflows-secrets.creating"></a>

Use the following procedure to create a secret. The secret contains the sensitive information that you want to hide from view.

**Note**  
Secrets are visible to actions and are not masked when written to a file.

**To create a secret**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Secrets**.

1. Choose **Create secret**.

1. Enter the following information:  
**Name**  
Enter a name for your secret.  
**Value**  
Enter the value for the secret. This is the sensitive information that you want to hide from view. By default, the value is not displayed. To display the value, choose **Show value**.  
**Description**  
(Optional) Enter a description for your secret.

1. Choose **Create**.

# Editing a secret
<a name="workflows-secrets.editing"></a>

Use the following procedure to edit a secret.

**To edit a secret**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Secrets**.

1. In the secrets list, choose the secret that you want to edit.

1. Choose **Edit**.

1. Edit the following properties:  
**Value**  
Enter the value for the secret. This is the value that you want to hide from view. By default, the value is not displayed.  
**Description**  
(Optional) Enter a description for your secret.

1. Choose **Save**.

# Using a secret
<a name="workflows-secrets.using"></a>

To use a secret in a workflow action, you must obtain the reference identifier of the secret and use that identifier in the workflow action.

**Topics**
+ [

## Obtaining the identifier of a secret
](#workflows-using-secrets.get-identifier)
+ [

## Referencing a secret in a workflow
](#workflows-using-secrets.using-identifier)

## Obtaining the identifier of a secret
<a name="workflows-using-secrets.get-identifier"></a>

Use the following procedure to obtain the reference identifier of the secret. You'll add this identifier to your workflow.

**To obtain the reference identifier of the secret**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Secrets**.

1. In the list of secrets, find the secret that you want to use.

1. In the **Reference ID** column, copy the identifier of the secret. The following is the syntax for the **Reference ID**:

   ```
   ${Secrets.<name>}
   ```

## Referencing a secret in a workflow
<a name="workflows-using-secrets.using-identifier"></a>

Use the following procedure to reference a secret in a workflow.

**To reference a secret**

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Modify the YAML to use the identifier of the secret. For example, to use a user name and password that are stored as secrets with the `curl` command, you would use a `Run` command similar to the following:

   ```
   - Run: curl -u <username-secret-identifier>:<password-secret-identifier> https://example.com
   ```

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

# Deleting a secret
<a name="workflows-secrets.deleting"></a>

Use the following procedure to delete a secret and the secret reference identifier.

**Note**  
Before deleting a secret, we recommend that you remove the secret's reference identifier from all workflow actions. If you delete the secret without deleting the reference identifier, the action will fail the next time it runs. 

**To delete a secret's reference identifier from a workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. Search the workflow for the following string:

   ```
   ${Secrets.
   ```

   This finds all reference identifiers of all secrets.

1. Delete the reference identifier of the chosen secret, or replace it with a plaintext value.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

**To delete a secret**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. In the navigation pane, choose **CI/CD**, and then choose **Secrets**.

1. In the secrets list, choose the secret you want to delete.

1. Choose **Delete**.

1. Enter **delete** to confirm the deletion.

1. Choose **Delete**.

# Viewing a workflow's status
<a name="workflows-view-status"></a>

You might want to view the status of a workflow to see if there are any workflow configuration issues you need to address, or to troubleshoot runs that fail to start. CodeCatalyst evaluates the workflow status every time you create or update the workflow's underlying [workflow definition file](workflows-concepts.md#workflows-concepts-workflows-def). 

**Note**  
You can also view the workflow's *run* status, which is different from the workflow status. For more information, see [Viewing workflow run status and details](workflows-view-run.md).

For a list of possible workflow states, see [Workflow states in CodeCatalyst](workflows-workflow-status.md).

**To view the status of a workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

   The status is displayed with the workflow in the list.

1. (Optional) Choose the name of the workflow, and find the **Workflow definition** field. It shows the workflow status.

# Quotas for workflows in CodeCatalyst
<a name="workflows-quotas"></a>

The following table describes quotas and limits for workflows in Amazon CodeCatalyst.

For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md).


|  |  | 
| --- |--- |
| Maximum number of workflows per space |  800  | 
| Maximum workflow definition file size |  256 KB  | 
| Maximum number of workflow files processed in a single source event |  50  | 
| Maximum number of files processed in a single source event |  4,000  | 
| Maximum number of active fleets per space |  10  | 
| Maximum number of active compute instances per fleet |  20  | 
| Maximum number of input artifacts per action |  10  | 
| Maximum number of output artifacts per action |  10  | 
| Maximum total size of a single action's output variables |  120 KB  | 
| Maximum length of an output variable value  |  500 characters or more, depending on the action that emits the value.   Values may be truncated if they exceed the action's limit.   | 
| Maximum number of days to keep artifacts generated during a workflow run |  30  | 
| Maximum number of reports per action |  50  | 
| Maximum number of test cases per test report |  20,000  | 
| Maximum number of files per code coverage report |  20,000  | 
| Maximum number of software composition analysis findings per report |  20,000  | 
| Maximum number of files per static analysis report |  20,000  | 
| Maximum number of concurrent workflow runs per space |  100  | 
| Maximum number of actions per workflow |  50  | 
| Maximum number of actions running concurrently per workflow |  50  | 
| Maximum number of actions running concurrently per space |  200  | 
| Maximum amount of time an action can run |  For the build and test actions, the timeout is 8 hours. For all other actions, the timeout is 1 hour.  | 
| Maximum number of environments associated with an AWS account per space |  5,000  | 
| Maximum number of secrets per action |  5  | 
| Maximum number of secrets per space |  500,000  | 

# Workflow run states
<a name="workflows-view-run-status"></a>

A workflow run can be in one of the following states:
+ **Succeeded** – The workflow run was processed successfully.
+ **Failed** – One or more actions in the workflow run failed.
+ **In progress** – The workflow run is currently being processed.
+ **Stopped** – A person stopped the workflow run while it was in progress.
+ **Stopping** – The workflow run is currently being stopped.
+ **Cancelled** – The workflow run was canceled by CodeCatalyst because the associated workflow was deleted or updated while the run was in progress.
+ **Superseded** – Only occurs if you have configured [superseded run mode](workflows-configure-runs.md#workflows-configure-runs-superseded). The workflow run was canceled by CodeCatalyst because a later workflow run superseded it.

# Workflow states in CodeCatalyst
<a name="workflows-workflow-status"></a>

A workflow can have one of the following states:
+ **Valid** – The workflow is runnable and can be activated by [triggers](workflows-add-trigger.md#workflows-add-trigger.title).

  For a workflow to be marked as valid, both of the following conditions must be true:
  + The workflow definition file must be valid.
  + The workflow must have no triggers, no push triggers, or a push trigger that runs using the files on the current branch. For more information, see [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md).
+ **Not valid** – The workflow's definition file is not valid. The workflow cannot be run manually, or automatically through triggers. Workflows that are not valid appear with a **Workflow definition has *n* errors** message (or similar) in the CodeCatalyst console.

  For a workflow to be marked as not valid, the following condition must be true:
  + The workflow definition file must be misconfigured.

    To fix a misconfigured workflow definition file, see [How do I fix "Workflow definition has *n* errors" errors?](troubleshooting-workflows.md#troubleshooting-workflows-asterisks).
+ **Inactive** – The workflow definition is valid but cannot be run manually, or automatically through triggers.

  For a workflow to be marked as inactive, both of the following conditions must be true:
  + The workflow definition file must be valid.
  + The workflow definition file must include a push trigger that specifies a branch that is different from the one that the workflow definition file is currently on. For more information, see [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md).

    To switch a workflow from **Inactive** to **Active**, see [How do I fix "Workflow is inactive" messages?](troubleshooting-workflows.md#troubleshooting-workflows-inactive).
**Note**  
If there are a lot of workflows in the **Inactive** state, you can filter them from view. To filter out inactive workflows, choose the **Filter workflows** field at the top of the **Workflows** page, choose **Status**, choose **Status \$1= Does not equal**, and choose **INACTIVE**.

**Note**  
If the workflow specifies a resource that you later remove (for example, a package repository), CodeCatalyst won't detect this change and will continue to mark the workflow as valid. These types of issues will be caught when the workflow runs.

# Workflow YAML definition
<a name="workflow-reference"></a>

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](source-repositories.md). 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](workflow.md#workflow.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\$1F**. The element will be listed with its associated YAML property.

**Topics**
+ [

## Example of a workflow definition file
](#workflow.anatomy)
+ [

## Syntax guidelines and conventions
](#workflow.terms.syntax.conv)
+ [

## Top-level properties
](#workflow.top.level)

## Example of a workflow definition file
<a name="workflow.anatomy"></a>

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](workflow.md#workflow.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 .
  Test:
    Identifier: aws/managed-test@v1
    DependsOn: 
      - Build
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Steps:
        - Run: npm install
        - Run: npm run test
```

## Syntax guidelines and conventions
<a name="workflow.terms.syntax.conv"></a>

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
<a name="workflow.syntax.conv"></a>

The workflow definition file is written in YAML and follows the [YAML 1.1 specification](https://yaml.org/spec/), 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 (\$1). 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
<a name="workflow.terms"></a>

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
  ```

## Top-level properties
<a name="workflow.top.level"></a>

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
<a name="workflow.name"></a>

(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 (\$1). 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
<a name="workflow.schemaversion"></a>

(Required)

The schema version of the workflow definition. Currently, the only valid value is `1.0`.

Corresponding UI: *none*

### RunMode
<a name="workflow.runmode"></a>

(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 the queuing behavior of runs](workflows-configure-runs.md).

Corresponding UI: visual editor/Workflow properties/Advanced/**Run mode**

### Compute
<a name="compute-reference"></a>

(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](compute-sharing.md).

For more information about compute, see [Configuring compute and runtime images](workflows-working-compute.md).

Corresponding UI: *none*

```
Name: MyWorkflow
SchemaVersion: 1.0
...
Compute:  
  Type: EC2 | Lambda
  Fleet: fleet-name
  SharedInstance: true | false
```

#### Type
<a name="workflow.compute.type"></a>

(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 [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: visual editor/Workflow properties/Advanced/**Compute type**

#### Fleet
<a name="workflow.compute.fleet"></a>

(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](workflows-working-compute.md#compute.on-demand).

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](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

For more information about compute fleets, see [Compute fleets](workflows-working-compute.md#compute.fleets).

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

#### SharedInstance
<a name="workflow.compute.sharedinstance"></a>

(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:
+ `TRUE` means that the runtime environment image is shared between workflow actions.
+ `FALSE` means that a separate runtime environment image is started and used for each action in a workflow, so you can't share resources such as artifacts and variables without extra configuration.

For more information about compute sharing, see [Sharing compute across actions](compute-sharing.md).

Corresponding UI: *none*

### Triggers
<a name="triggers-reference"></a>

(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](workflows-add-trigger.md).

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
<a name="workflow.triggers.type"></a>

(Triggers/**Type**)

(Required if `Triggers` is set)

Specify 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 a change is pushed to your source repository. The workflow run will use the files in the branch that you're pushing *to* (that is, the destination branch).
+ **Pull request** (visual editor) or `PULLREQUEST` (YAML editor)

  A pull request trigger starts a workflow run when a pull request is opened, updated, or closed in your source repository. The workflow run will use the files in the branch that you're pulling *from* (that is, the source branch).
+ **Schedule** (visual editor) or `SCHEDULE` (YAML editor)

  A schedule trigger starts workflow runs on a schedule defined by a cron expression that you specify. A separate workflow run will start for each branch in your source repository using the branch's files. (To limit the branches that the trigger activates on, use the **Branches** field (visual editor) or `Branches` property (YAML editor).)

  When configuring a schedule trigger, follow these guidelines:
  + Only use one schedule trigger per workflow.
  + If you've defined multiple workflows in your CodeCatalyst space, we recommend that you schedule no more than 10 of them to start concurrently.
  + Make sure you configure the trigger's cron expression with adequate time between runs. For more information, see [Expression](#workflow.triggers.expression).

For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

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

#### Events
<a name="workflow.triggers.events"></a>

(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:
+ **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. The `CLOSED` event's behavior is tricky, and is best understood through an example. See [Example: A trigger with a pull, branches, and a 'CLOSED' event](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close) for more information.
+ **New revision is made to pull request** (visual editor) or `REVISION` (YAML editor)

  The workflow run is started when a revision to a pull request is created. The first revision is created when the pull request is created. After that, a new revision is created every time someone pushes a new commit to the source branch specified in the pull request. If you include the `REVISION` event in your pull request trigger, you can omit the `OPEN` event, since `REVISION` is a superset of `OPEN`.

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

For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

Corresponding UI: visual editor/workflow diagram/Triggers/**Events for pull request**

#### Branches
<a name="workflow.triggers.branches"></a>

(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 with `main`.

The branches to specify are different depending on the trigger type:
+ For a push trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the files in the matched branch.

  Examples: `main.*`, `mainline`
+ For a pull request trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the workflow definition file and source files in the **source** branch (*not* the matched branch).

  Examples: `main.*`, `mainline`, `v1\-.*` (matches branches that start with `v1-`)
+ For a schedule trigger, specify the branches that contain the files that you want your scheduled run to use. One workflow run will start per matched branch, using the the workflow definition file and source files in the matched branch.

  Examples: `main.*`, `version\-1\.0`

**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:  
The branch you're pushing *to* (for push triggers). For more information, see [Example: A simple code push trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple).
The branch you're pulling *from* (for pull request triggers). For more information, see [Example: A simple pull request trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple).
All branches (for schedule triggers). One workflow run will start per branch in your source repository. For more information, see [Example: A simple schedule trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple).

For more information about branches and triggers, see [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md).

For more examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md).

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

#### FilesChanged
<a name="workflow.triggers.files-changed"></a>

(Triggers/**FilesChanged**)

(Optional if the trigger `Type` is set to `PUSH`, or `PULLREQUEST`. Not supported if the trigger `Type` is set to `SCHEDULE`.)

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](workflows-add-trigger-examples.md).

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

#### Expression
<a name="workflow.triggers.expression"></a>

(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  |  ?  |  \$1  |  MON-FRI  |  \$1  |  Runs a workflow at midnight (UTC\$10) every Monday through Friday.  | 
|  0  |  2  |  \$1  |  \$1  |  ?  |  \$1  |  Runs a workflow at 2:00 am (UTC\$10) every day.  | 
|  15  |  22  |  \$1  |  \$1  |  ?  |  \$1  |  Runs a workflow at 10:15 pm (UTC\$10) every day.  | 
|  0/30  |  22-2  |  ?  |  \$1  |  SAT-SUN  |  \$1  |  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\$10).  | 
|  45  |  13  |  L  |  \$1  |  ?  |  2023-2027  |  Runs a workflow at 1:45 pm (UTC\$10) 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:
+ Specify a single cron expression per `SCHEDULE` trigger.
+ Enclose the cron expression in double-quotes (`"`) in the YAML editor.
+ Specify the time in Coordinated Universal Time (UTC). Other time zones are not supported.
+ Configure at least 30 minutes between runs. A faster cadence is not supported.
+ Specify the *days-of-month* or *days-of-week* field, but not both. If you specify a value or an asterisk (`*`) in one of the fields, you must use a question mark (`?`) in the other. The asterisk means 'all' and the question mark means 'any'.

 For more examples of cron expressions and information about wildcards like `?`, `*`, and `L`, see the [Cron expressions reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html) 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](workflows-add-trigger-examples.md).

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

### Actions
<a name="actions-reference"></a>

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 [Action types](workflows-actions.md#workflows-actions-types). The [Action types](workflows-actions.md#workflows-actions-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
<a name="workflow.actions.name"></a>

(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](#workflow.syntax.conv).

For more information about naming practices for actions, including restrictions, see the [action-or-gate-name](#workflow.actions.name). 

Corresponding UI: visual editor/*action-name*/Configuration tab/**Action name** or **Action display name**

#### action-group-name
<a name="workflow.action-groups"></a>

(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](#workflow.syntax.conv).

For more information about action groups, see [Grouping actions into action groups](workflows-group-actions.md).

Corresponding UI: *none*