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 variables in workflows 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 *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 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 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 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 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 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 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 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 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 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 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 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 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 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 *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 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 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 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 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 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 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)