AWS CodePipeline Variables: A Helpful Little Guide
Originally published at https://lukemiller.dev/blog/aws-codepipeline-variables-a-helpful-little-guide/
Ah, AWS, the never ending supply of Lego pieces to build to your heart’s content. Today we’ll talk about a small feature within CodePipeline that I was pleased to find to make my pipelines more dynamic: Action Variables.
TL;DR CodePipeline provides us with action-based variables, for a select number of actions, that allow us to make our pipelines more dynamic. docs
What Are CodePipeline Variables?
I’m assuming you understand that CodePipeline is a series of Stages that are composed of Actions, so we will jump ahead to what Action Variables are.
A select number of CodePipeline Actions are able to output variables after their successful execution. Those variables can then be used by Actions downstream in the pipeline.
Let’s say that we have a Source Stage with an Action, also called Source, which persists a GitHub connection. Following the Source Stage is a Build Stage which is composed of a Build Action that uses CodeBuild.
Our Source Action, after execution, will output variables based on the values associated to the Action. For instance, it will expose a CommitId variable with the value of our GitHub commit hash that triggered this pipeline execution. With that variable available to the Build Action, we could configure CodeBuild to use the CommitId during its operation, perhaps to assist with version labelling or maybe something as simple as logging.
That’s it! They’re variables one Action exposes that a downstream Action can use.
I know, it’s not ground shattering, but it does help in making CodePipeline a bit more dynamic. Some scenarios in which you could use CodePipeline variables could be:
- Referencing CloudFormation template outputs, like StackName, further down in your pipeline
- Dynamically create URLs for review in a Manual Approval action
- Manage multi-environment pipelines
Available Action Variables
Earlier I said that a, “select number of CodePipeline Actions are able to output variables”. That leads us to ask, what variables are available and from what Actions?
The actions and variables available for use can be organized into two categories: Defined and User-Configured.
Defined Variables
For Defined Variables, you can’t change the variable names or their assigned values. These are available out of the box from the Action, and all you need to do is ensure the Action has a Variable Namespace. The one Defined Variables that does not need a namespace defined is the global variable output from CodePipeline itself which provides you the ExecutionId of the pipeline.
These are the Actions with Defined Variables and their variable keys:
User-Configured Variables
These are custom variables where you can specify the variable key and its value, but they are only available on three Actions:
CloudFormation Variables
For CloudFormation, Action Variables keys are the names of any output in your template’s Outputs section, and the value, naturally, is the output’s corresponding value. The following example, though not dynamic or exciting in any way, would output a variable with the key of Version and the value of 12.
Only four of the CloudFormation Actions will map those template Outputs to variables available in CodePipeline. Those actions are:
- CREATE_UPDATE
- REPLACE_ON_FAILURE
- ALWAYS_REPLACE
- CHANGE_SET_EXECUTE
CodeBuild Variables
Similar to the Outputs section of CloudFormation, a CodeBuild’s build spec file allows you to define variables for output. The ‘env’ section can contain a ‘export-variables’ list where you can assign variable key-value pairs. docs
Lambda Variables
Lastly, Lambda allows us to perform the same custom defined variable keys and values by adding them to the params passed into the .putJobSuccessResult() API call. If you are not familiar with how Lambdas work inside CodePipeline, they must return a success or failure response to CodePipeline, so that the pipeline knows how to proceed from the Lambda Action. In a success response, a params object is passed and inside of it we can declare whatever variables our heart desires to expose. docs
Here’s what that looks like for a Lambda running Node.
Using Variables
While only a select number of Actions can produce variables, all Actions can consume variables. To get started using variables all we need to do is just declare a namespace in the output Action and then use the correct syntax to access it in the consuming Action.
Declare An Action’s Variable Namespace
For the Action in which we wish to output a variable, we edit that Action and near the bottom enter a namespace for all of its variables. In the example below, I have a GitHub Action and the namespace is SourceVariables. If you recall, GitHub is an action with Defined Variables, so I cannot create any new variables, but I’ll automatically get the previously outlined list of variable keys available for use.
Use The Proper Syntax Downstream
To use one of my SourceVariables, we just use the proper syntax in the subsequent Actions. The syntax is this:
In our above example, the GitHub Action has SourceVariables entered in the Variable namespace, so our access of the variables would look like #{SourceVariables.<variable key>}. If we wanted to change the namespace to FooBar, we could and then we’d access the variables with #{FooBar.<variable key>}
Examples
Example 1: Source Action Variable Used in CodeBuild Action
To use the Source Action’s variables in the CodeBuild Action, edit our CodeBuild action and add the appropriate environment variable. The Name can be whatever we want, but the Value must match the syntax shown above.
We now can treat the BranchName variable in our buildspec.yml file like we would any other environment variable, and it will resolve to the Source Action repository’s branch name.
Example 2: Source Action Variable Used in Manual Approval
Again, we’ll configure our downstream Action to use the upstream variable. Unlike the previous example, here the variable won’t be added to an environment variables, instead it will be added directly to a string and CodePipeline will handle resolving the value during the pipelines execution.
Another thing we could have done is to enter a dynamic value for the URL for Review section. We could have combined our root GitHub account endpoint with the RepositoryName and the CommitId to dynamically generate a link to the GitHub commit for each pipeline execution.
Verification
If you are working with Action Variables and want to verify they’re output, go to the History of your Pipeline…
…then click on the Execution Id of a successfully ran pipeline execution, and then click on the Action you wish to inspect from the Actions list…
…then scroll down to Output Variables for the list of variables available for use.
Conclusion
There you have it, Action Variables! You can now use the defined variables, configure your own, import them to your heart’s content, and make that CodePipeline of your dreams.
If I missed anything or you have examples of how Action Variables improved your pipelines, please don’t hesitate to reach out.
Thanks!
Originally published at https://lukemiller.dev.
