Working with variables - AWS CodePipeline

Working with variables

Some actions in CodePipeline generate variables. To use variables:

  • You assign a namespace to an action to make the variables it produces available to a downstream action configuration.

  • You configure the downstream action to consume the variables generated by the action.

    You can view the details for each action execution to see the values for each output variable that was generated by the action in execution-time.

To see step-by-step examples of using variables:

Configure actions for variables

When you add an action to your pipeline, you can assign it a namespace and configure it to consume variables from previous actions.

Configure actions with variables (console)

This example creates a pipeline with a CodeCommit source action and a CodeBuild build action. The CodeBuild action is configured to consume the variables produced by the CodeCommit action.

If the namespace isn’t specified, the variables are not available for reference in the action configuration. When you use the console to create a pipeline, the namespace for each action is generated automatically.

To create a pipeline with variables
  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

  2. Choose Create pipeline. Enter a name for your pipeline, and then choose Next.

  3. In Source, in Provider, choose CodeCommit. Choose the CodeCommit repository and branch for the source action, and then choose Next.

  4. In Build, in Provider, choose CodeBuild. Choose an existing CodeBuild build project name or choose Create project. On Create build project, create a build project, and then choose Return to CodePipeline.

    Under Environment variables, choose Add environment variables. For example, enter the execution ID with the variable syntax #{codepipeline.PipelineExecutionId} and commit ID with the variable syntax #{SourceVariables.CommitId}.

    Note

    You can enter variable syntax in any action configuration field in the wizard.

  5. Choose Create.

  6. After the pipeline is created, you can view the namespace that was created by the wizard. On the pipeline, choose the icon for the stage you want to view the namespace for. In this example, the source action's auto-generated namespace, SourceVariables, is displayed.

    Example: Action Info Screen
To edit the namespace for an existing action
  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

  2. Choose the pipeline you want to edit, and then choose Edit. For the source stage, choose Edit stage. Add the CodeCommit action.

  3. On Edit action, view the Variable namespace field. If the existing action was created previously or without using the wizard, you must add a namespace. In Variable namespace, enter a namespace name, and then choose Save.

To view output variables
  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

  2. After the pipeline is created and runs successfully, you can view the variables on the Action execution details page. For information, see View variables (console).

Configure actions for variables (CLI)

When you use the create-pipeline command to create a pipeline or the update-pipeline command to edit a pipeline, you can reference/use variables in the configuration of an action.

If the namespace isn't specified, the variables produced by the action are not available to be referenced in any downstream action configuration.

To configure an action with a namespace
  1. Follow the steps in Create a pipeline, stages, and actions to create a pipeline using the CLI. Start an input file to provide the create-pipeline command with the --cli-input-json parameter. In the pipeline structure, add the namespace parameter and specify a name, such as SourceVariables.

    . . . { "inputArtifacts": [], "name": "Source", "region": "us-west-2", "namespace": "SourceVariables", "actionTypeId": { "category": "Source", "owner": "AWS", "version": "1", "provider": "CodeCommit" }, "outputArtifacts": [ . . .
  2. Save the file with a name like MyPipeline.json.

  3. At a terminal (Linux, macOS, or Unix) or command prompt (Windows), run the create-pipeline command and create the pipeline.

    Call the file you created when you run the create-pipeline command. For example:

    aws codepipeline create-pipeline --cli-input-json file://MyPipeline.json
To configure downstream actions to consume variables
  1. Edit an input file to provide the update-pipeline command with the --cli-input-json parameter. In the downstream action, add the variable to the configuration for that action. A variable is made up of a namespace and key, separated by a period. For example, to add variables for the pipeline execution ID and the source commit ID, specify the namespace codepipeline for the variable #{codepipeline.PipelineExecutionId}. Specify the namespace SourceVariables for the variable #{SourceVariables.CommitId}.

    { "name": "Build", "actions": [ { "outputArtifacts": [ { "name": "BuildArtifacts" } ], "name": "Build", "configuration": { "EnvironmentVariables": "[{\"name\":\"Execution_ID\",\"value\":\"#{codepipeline.PipelineExecutionId}\",\"type\":\"PLAINTEXT\"},{\"name\":\"Commit_ID\",\"value\":\"#{SourceVariables.CommitId}\",\"type\":\"PLAINTEXT\"}]", "ProjectName": "env-var-test" }, "inputArtifacts": [ { "name": "SourceArtifact" } ], "region": "us-west-2", "actionTypeId": { "provider": "CodeBuild", "category": "Build", "version": "1", "owner": "AWS" }, "runOrder": 1 } ] },
  2. Save the file with a name like MyPipeline.json.

  3. At a terminal (Linux, macOS, or Unix) or command prompt (Windows), run the create-pipeline command and create the pipeline.

    Call the file you created when you run the create-pipeline command. For example:

    aws codepipeline create-pipeline --cli-input-json file://MyPipeline.json

View output variables

You can view the action execution details to view the variables for that action, specific to each execution.

View variables (console)

You can use the console to view variables for an action.

  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

    The names of all pipelines associated with your AWS account are displayed.

  2. In Name, choose the name of the pipeline.

  3. Choose View history.

  4. After the pipeline runs successfully, you can view the variables produced by the source action. Choose View history. Choose Source in the action list for the pipeline execution to view the action execution details for the CodeCommit action. On the action detail screen, view the variables under Output variables.

    Example: Source output variables
  5. After the pipeline runs successfully, you can view the variables consumed by the build action. Choose View history. In the action list for the pipeline execution, choose Build to view the action execution details for the CodeBuild action. On the action detail page, view the variables under Action configuration. The auto-generated namespace is displayed.

    Example: Action Configuration Variables

    By default, Action configuration displays the variable syntax. You can choose Show resolved configuration to toggle the list to display the values that were produced during the action execution.

    Example: Resolved Action Configuration Variables

View variables (CLI)

You can use the list-action-executions command to view variables for an action.

  1. Use the following command:

    aws codepipeline list-action-executions

    The output shows the outputVariables parameter as shown here.

    "outputVariables": { "BranchName": "main", "CommitMessage": "Updated files for test", "AuthorDate": "2019-11-08T22:24:34Z", "CommitId": "d99b0083cc10EXAMPLE", "CommitterDate": "2019-11-08T22:24:34Z", "RepositoryName": "variables-repo" },
  2. Use the following command:

    aws codepipeline get-pipeline --name <pipeline-name>

    In the action configuration for the CodeBuild action, you can view the variables:

    { "name": "Build", "actions": [ { "outputArtifacts": [ { "name": "BuildArtifact" } ], "name": "Build", "configuration": { "EnvironmentVariables": "[{\"name\":\"Execution_ID\",\"value\":\"#{codepipeline.PipelineExecutionId}\",\"type\":\"PLAINTEXT\"},{\"name\":\"Commit_ID\",\"value\":\"#{SourceVariables.CommitId}\",\"type\":\"PLAINTEXT\"}]", "ProjectName": "env-var-test" }, "inputArtifacts": [ { "name": "SourceArtifact" } ], "region": "us-west-2", "actionTypeId": { "provider": "CodeBuild", "category": "Build", "version": "1", "owner": "AWS" }, "runOrder": 1 } ] },

Example: Use variables in manual approvals

When you specify a namespace for an action, and that action produces output variables, you can add a manual approval that displays variables in the approval message. This example shows you how to add variable syntax to a manual approval message.

  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

    The names of all pipelines associated with your AWS account are displayed. Choose the pipeline you want to add the approval to.

  2. To edit your pipeline, choose Edit. Add a manual approval after the source action. In Action name, enter the name of the approval action.

  3. In Action provider, choose Manual approval.

  4. In URL for review, add the variable syntax for CommitId to your CodeCommit URL. Make sure you use the namespace assigned to your source action. For example, the variable syntax for a CodeCommit action with the default namespace SourceVariables is #{SourceVariables.CommitId}.

    In Comments, in CommitMessage, enter the commit message:

    Please approve this change. Commit message: #{SourceVariables.CommitMessage}
  5. After the pipeline runs successfully, you can view the variable values in the approval message.

Example: Use a BranchName variable with CodeBuild environment variables

When you add a CodeBuild action to your pipeline, you can use CodeBuild environment variables to reference a BranchName output variable from an upstream source action. With an output variable from an action in CodePipeline, you can create your own CodeBuild environment variables for use in your build commands.

This example shows you how to add output variable syntax from a GitHub source action to a CodeBuild environment variable. The output variable syntax in this example represents the GitHub source action output variable for BranchName. After the action runs successfully, the variable resolves to show the GitHub branch name.

  1. Sign in to the AWS Management Console and open the CodePipeline console at http://console.aws.amazon.com/codesuite/codepipeline/home.

    The names of all pipelines associated with your AWS account are displayed. Choose the pipeline you want to add the approval to.

  2. To edit your pipeline, choose Edit. On the stage that contains your CodeBuild action, choose Edit stage.

  3. Choose the icon to edit your CodeBuild action.

  4. On the Edit action page, under Environment variables, enter the following:

    • In Name, enter a name for your environment variable.

    • In Value, enter the variable syntax for your pipeline output variable, which includes the namespace assigned to your source action. For example, the output variable syntax for a GitHub action with the default namespace SourceVariables is #{SourceVariables.BranchName}.

    • In Type, choose Plaintext.

  5. After the pipeline runs successfully, you can see how the resolved output variable is the value in the environment variable. Choose one of the following:

    • CodePipeline console: Choose your pipeline, and then choose History. Choose the most recent pipeline execution.

      • Under Timeline, choose the selector for Source. This is the source action that generates GitHub output variables. Choose View execution details. Under Output variables, view the list of output variables generated by this action.

      • Under Timeline, choose the selector for Build. This is the build action that specifies the CodeBuild environment variables for your build project. Choose View execution details. Under Action configuration, view your CodeBuild environment variables. Choose Show resolved configuration. Your environment variable value is the resolved BranchName output variable from the GitHub source action. In this example, the resolved value is main.

        For more information, see View variables (console).

    • CodeBuild console: Choose your build project and choose the link for your build run. Under Environment variables, your resolved output variable is the value for the CodeBuild environment variable. In this example, the environment variable Name is BranchName and the Value is the resolved BranchName output variable from the GitHub source action. In this example, the resolved value is main.

    Screen shot showing the resolved variable in the console