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).

# 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)