Using predefined variables - Amazon CodeCatalyst

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.

You can use predefined variables in any workflow action.

Referencing a predefined variable

Use the following instructions to reference a predefined variable.

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.

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

  2. Choose your project.

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

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

  5. Choose Edit.

  6. Choose YAML.

  7. 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 predefined variables. For more information, see the Workflow YAML definition for your action.

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

  9. Choose Commit, enter a commit message, and choose Commit again.

Determining which predefined variables your workflow emits

You can determine which predefined variables your workflow emits in two ways:

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

  • Consult the List of predefined variables. 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. If the total size exceeds the maximum, the action that occurs after the maximum is reached may fail.

Examples of predefined variables

The following examples show how to reference predefined variables in the workflow definition file.

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.

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.

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@v1 Inputs: Sources: - WorkflowSource Configuration: StackName: app-stack-${WorkflowSource.BranchName}