Pipeline values and parameters
20 hours ago
Introduction
Pipeline values and parameters can be used to create reusable pipeline configurations.
-
Pipeline values represent pipeline metadata that can be used throughout the configuration.
-
Pipeline parameters are typed pipeline variables that are declared in the
parameterskey at the top level of a configuration. Users can passparametersinto their pipelines when triggering a new run of a pipeline through the API or web app.
Pipeline values
Pipeline values are available to all pipeline configurations and can be used without previous declaration.
For a full list of values and built-in environment variables, see the Project Values and Variables guide.
Check your project slug to discover which GitHub integration you have set up:
-
Head to the CircleCI web app and select your org from the cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis menu
next to your project and select Project Settings. The project slug is listed on the project settings homepage.-
GitHub App: Project slug starts with
circlecifollowed by UUIDs. For example,circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg). -
GitHub OAuth app: Project slug is human readable. For example,
github/circleci/circleci-demo-workflows.
-
For more information about the differences, see the VCS integration overview.
Pipeline and project identity
These values provide core identifiers for the pipeline itself and the project it belongs to. They are available across all pipeline types and integration methods.
| Variable | Source | Type | Value | Cloud | Server |
|---|---|---|---|---|---|
|
GitHub App |
String |
A globally unique id representing for the pipeline. |
Yes |
Yes |
|
GitHub App |
Integer |
A project unique integer id for the pipeline. |
Yes |
Yes |
|
GitHub App |
String |
The unique ID of the pipeline definition. |
Yes |
Yes |
|
GitHub App |
String |
The URL where the current project is hosted. For example, |
Yes |
Yes |
|
GitHub App |
String |
The lower-case name of the VCS provider, for example, |
Yes |
Yes |
Checkout information
Values prefixed with pipeline.git.* describe the git state of the code CircleCI checks out for the pipeline. These values reflect the code CircleCI checks out and builds. For GitHub App pipelines, this may differ from both the commit or branch that triggered the event and the commit or branch used to fetch the configuration file.
| Variable | Source | Type | Value | Cloud | Server |
|---|---|---|---|---|---|
|
GitHub App |
String |
The name of the git tag that was pushed to trigger the pipeline. If the pipeline was not triggered by a tag, then this is the empty string. |
Yes |
Yes |
|
GitHub App |
String |
The name of the git branch that was pushed to trigger the pipeline. |
Yes |
Yes |
|
GitHub App |
Boolean |
Whether the branch the pipeline was triggered on is the default branch. |
Yes |
Yes (>= v4.7) |
|
GitHub App |
String |
The long (40-character) git SHA that is being built. |
Yes |
Yes |
|
GitHub OAuth |
String |
The long (40-character) git SHA of the build prior to the one being built. Note: While in most cases |
Yes |
Yes |
Configuration source information
Values prefixed with pipeline.config.* describe where the CircleCI configuration file was fetched from. These values are currently only available for GitHub App pipelines where the configuration file can be stored in a separate repository from the one being built. For all other pipeline types, the configuration file always lives in the same repository as the code being checked out so you can use the corresponding pipeline.git.* values instead.
| Variable | Source | Type | Value | Cloud | Server |
|---|---|---|---|---|---|
|
GitHub App |
String |
The name of the repository containing the CircleCI configuration file, in the format |
Yes |
No |
|
GitHub App |
String |
The URL of the repository containing the CircleCI configuration file. |
Yes |
No |
|
GitHub App |
String |
The file path to the CircleCI configuration file used by the pipeline. |
Yes |
No |
|
GitHub App |
String |
The full Git ref used to fetch the CircleCI configuration file, for example |
Yes |
No |
|
GitHub App |
String |
The long (40-character) git SHA of the commit used to fetch the CircleCI configuration file. |
Yes |
No |
Trigger and event information
These values describe how and why the pipeline was triggered, including the event source, timing, and any event-specific data passed by the VCS provider.
|
All |
| Variable | Source | Type | Value | Cloud | Server |
|---|---|---|---|---|---|
|
GitHub App |
String |
The timestamp of when the pipeline was triggered, in ISO 8601 format. |
Yes |
Yes |
|
GitHub App |
String |
The source that triggers the pipeline, current values are |
Yes |
Yes |
|
GitHub OAuth |
String |
The name of the schedule trigger if the pipeline was triggered via schedule. The value will be empty string if the pipeline is triggered by other sources. |
Yes |
Yes |
|
GitHub OAuth |
String |
The unique ID of the schedule if the pipeline was triggered via schedule trigger. Value will be empty string if the pipeline is triggered by other sources. |
Yes |
Yes |
|
GitHub App |
String |
The name of the event that triggered the pipeline. Possible values: |
Yes |
No |
|
GitHub App |
String |
The action associated with the event. This value is always the same as |
Yes |
No |
|
GitHub App |
String |
The SHA of the most recent commit on the branch after the push. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The URL of the most recent commit on the branch. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The full Git ref that was pushed. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The URL of the associated GitHub pull request, if one exists. If there are multiple associated pull requests, one URL is randomly chosen. This value matches environment variable CIRCLE_PULL_REQUEST. |
Yes |
No |
|
GitHub App |
String |
The name of the base (or target) branch of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The SHA of the base branch of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The name of the head branch of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The SHA of the head branch of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
Boolean |
A boolean value indicating whether the pull request is a draft. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The title of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
Integer |
The numeric identifier of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
Boolean |
A boolean value indicating whether the pull request has been merged. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The URL of the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The name of the label applied to the pull request. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The body of the comment that triggered the pipeline, with leading and trailing whitespace removed. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The type of GitHub user that triggered the event. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The avatar URL of the GitHub user who triggered the event. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The login name of the GitHub user who triggered the event. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The name of the repository that triggered the event, without the owner prefix. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The login name of the repository owner. Corresponds to the |
Yes |
No |
|
GitHub App |
String |
The URL of the repository that triggered the event. Corresponds to the |
Yes |
No |
|
Custom webhook |
String |
The body of the payload that was sent with a Custom Webhook. |
Yes |
No |
|
GitHub App |
String |
Use |
Yes |
No |
|
GitHub App |
String |
Use |
Yes |
No |
|
GitHub App |
String |
Use |
Yes |
No |
|
GitHub App |
For push events, use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
No direct replacement is available. If this value is critical to your workflows, contact CircleCI Support. |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
For the checkout commit subject, use |
Yes |
No |
|
|
GitHub App |
For the checkout commit body, use |
Yes |
No |
|
|
GitHub App |
Use |
Yes |
No |
|
|
GitHub App |
For the user who triggered the push event, use |
Yes |
No |
|
|
GitHub App |
For push events, use |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
|
|
GitLab |
See GitLab documentation for webhooks and webhook events. |
Yes |
No |
Deploy information
Values prefixed with pipeline.deploy.* are only available for deployment pipelines. See the Set up a Rollback Pipeline and Set up a Deploy Pipeline guides for more information.
| Variable | Source | Type | Value | Cloud | Server |
|---|---|---|---|---|---|
|
GitHub App |
String |
The name of the component that will be rolled back or deployed. |
Yes |
No |
|
GitHub App |
String |
The name of the environment in which the rollback or deploy will be performed. |
Yes |
No |
|
GitHub App |
String |
The version of the component that needs to be rolled back to or deployed. |
Yes |
No |
|
GitHub App |
String |
The current version of the component that is going to be rolled back or deployed. Can be used to verify that the status of the component matches expectations. |
Yes |
No |
|
GitHub App |
String |
The namespace of the environment that was deployed to. |
Yes |
No |
|
GitHub App |
String |
The reason for the deployment or rollback. |
Yes |
No |
Usage example:
version: 2.1
jobs:
build:
docker:
- image: cimg/node:17.0
environment:
CIRCLE_COMPARE_URL: << pipeline.project.git_url >>/compare/<< pipeline.git.base_revision >>..<<pipeline.git.revision>>
working_directory: ~/main
steps:
- run: echo "This is pipeline ID << pipeline.id >>"
- run: echo $CIRCLE_COMPARE_URLWhen using the above method to set the values in the environment key, note that if the pipeline variable is empty it will be set to <nil>. If you need an empty string instead, Set the Variable in a Shell Command.
Pipeline parameters
Pipeline parameters are declared using the parameters key at the top level of a .circleci/config.yml file. Pipeline parameters can be referenced by value and used as a configuration variable under the scope pipeline.parameters.
Pipeline parameters support the following types:
-
string -
boolean -
integer -
enum
See Parameter Syntax for usage details.
The example below shows a configuration with two pipeline parameters (image-tag and workingdir) defined at the top of the configuration, and then subsequently referenced in the build job:
version: 2.1
parameters:
image-tag:
type: string
default: "current"
workingdir:
type: string
default: "~/main"
jobs:
build:
docker:
- image: cimg/node:<< pipeline.parameters.image-tag >>
environment:
IMAGETAG: << pipeline.parameters.image-tag >>
working_directory: << pipeline.parameters.workingdir >>
steps:
- run: echo "Image tag used was ${IMAGETAG}"
- run: echo "$(pwd) == << pipeline.parameters.workingdir >>"Passing parameters when triggering pipelines via the API
Using server? If you are using CircleCI server, replace https://circleci.com with your server hostname when interacting with the CircleCI API.
|
A pipeline can be triggered with specific parameter values using the API v2 endpoint to trigger a pipeline. This can be done by passing a parameters key in the JSON packet of the POST body.
The API limits the number of parameters that can be passed:
-
100 max entries.
-
128 maximum key length.
-
512 maximum value length.
The parameters key passed in this POST request is NOT secret.
The example below triggers a pipeline with the parameters described in the above configuration example. If you run a command to trigger a pipeline, and the parameter has not been declared in the configuration file, you will receive an error response message, such as Project not found.
| For GitHub App, GitLab or Bitbucket Data Center pipelines, use the Trigger a new pipeline endpoint rather than the endpoint used in this example. |
curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
"parameters": {
"workingdir": "./myspecialdir",
"image-tag": "4.8.2"
}
}' https://circleci.com/api/v2/project/{project_slug}/pipelineTo find your project slug, follow these steps:
-
Head to the CircleCI web app and select your org from the cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis menu
next to your project and select Project Settings. The project slug is listed on the project settings homepage.-
GitHub App: Project slug starts with
circlecifollowed by UUIDs. For example,circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg). -
GitHub OAuth app: Project slug is human readable. For example,
github/circleci/circleci-demo-workflows.
-
Refer to the Getting Started With the API section of the API Developer’s Guide for more guidance on making requests.
Passing parameters when triggering pipelines using the CircleCI web app
In addition to using the API, you can also trigger a pipeline with parameters from the CircleCI web app. If you pass a parameter when triggering a pipeline, and the parameter has not been declared in the configuration file, the pipeline will fail with the error Unexpected argument(s).
-
Use the project filter to select the desired project.
-
Use the branch filter to select the branch on which you want to run the new pipeline.
-
Select Trigger Pipeline (towards the top right corner of the page).
-
Use the Add Parameters dropdown to specify the type, name, and value of your desired parameters.
-
Select Trigger Pipeline.
Parameters can also be passed when setting up a schedule trigger in the web app. The parameters are part of the trigger form in or . Any parameter set up as a part of a schedule trigger will also need to be declared in the configuration file, otherwise the pipeline will fail with the error Unexpected argument(s).
Configuration processing stages
Configuration processing happens in the following stages:
-
Pipeline parameters are resolved and type-checked
-
Pipeline parameters are replaced in the orb statement
-
Orbs are imported
The remaining configuration is processed, element parameters are resolved, type-checked, and substituted.
The scope of parameters in configuration
Pipeline parameters can only be resolved in the .circleci/config.yml file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your .circleci/config.yml file. Access to pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling configuration. This would potentially create a surface area of vulnerability, increasing security risks.
Element parameter scope
Element parameters, which are parameters set in a job, a command, or an executor, use lexical scoping. That is, element parameters are in scope within the element they are defined in. If an element with parameters calls another element with parameters, like in the example below, the inner element does not inherit the scope of the calling element.
version: 2.1
commands:
print:
parameters:
message:
type: string
steps:
- run: echo << parameters.message >>
jobs:
daily-message:
machine:
image: ubuntu-2004:current
resource_class: large
parameters:
message:
type: string
steps:
- print:
message: Printing << parameters.message >>
workflows:
my-workflow:
jobs:
- daily-message:
message: << parameters.message >>Even though the print command is called from the daily-message job, the message parameter would not be in scope inside my-workflow. This ensures that all parameters are always bound to a valid value, and the set of available parameters is always known. Running this would throw a pipeline error of Arguments referenced without declared parameters: parameters.message.
Pipeline value scope
Pipeline values, the pipeline-wide values that are provided by CircleCI (for example, << pipeline.number >>) are always in scope.
Pipeline parameter scope
Pipeline parameters which are defined in configuration are always in scope, with two exceptions:
-
Pipeline parameters are not in scope for the definition of other pipeline parameters, so they cannot depend on one another.
-
Pipeline parameters are not in scope in the body of orbs, even inline orbs, to prevent data leaks.
Pipeline parameters and dynamic configuration
Parameters can be passed from the setup to the continuation workflow using the continue job or command from the continuation orb. To pass these parameters use the parameters parameter from the continue job/command. Any parameters passed in this way must be declared as pipeline parameters in the continuation configuration.
When a pipeline parameter is declared in both the setup and the continuation configurations, the pipeline will error if both the following conditions are met:
-
The pipeline is triggered via the API.
-
The pipeline parameter’s value specified in the API request is different from the default value specified in the setup configuration.
More information on setup workflows can be found in the How Dynamic Config Works section of the Dynamic Configuration overview.
Pipeline parameters and conditional workflows
Use the when clause (or the inverse clause unless) under a workflow declaration, along with a logic statement, to decide whether or not to run that workflow. Logic statements in a when or unless clause should evaluate to a truthy or falsy value.
The most common use of this construct is to use a pipeline parameter as the value, allowing a trigger to pass that parameter to determine which workflows to run. Below is an example configuration using the pipeline parameter run_integration_tests to set whether the workflow integration_tests will run.
version: 2.1
parameters:
run_integration_tests:
type: boolean
default: false
workflows:
integration_tests:
when: << pipeline.parameters.run_integration_tests >>
jobs:
- mytestjob
jobs:
mytestjob:
steps:
- checkout
- ... # job stepsIn this example, the workflow integration_tests is not triggered unless it is explicitly invoked when the pipeline is triggered with the following in the POST body:
{
"parameters": {
"run_integration_tests": true
}
}The when key accepts any truthy or falsy value, not just pipeline parameters, though pipeline parameters will be the primary use of this feature until more are implemented. when also has an inverse clause unless, which inverts truthiness of the condition.