Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Pipeline values and parameters

3 months ago7 min read
Cloud
Server v4.x
Server v3.x
On This Page

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 parameters key at the top level of a configuration. Users can pass parameters into 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.

VariableVCSTypeValueCloudServer

pipeline.id

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

A globally unique id representing for the pipeline.

pipeline.number

GitHub App, GitHub OAuth, Bitbucket, GitLab

Integer

A project unique integer id for the pipeline.

pipeline.project.git_url

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

The URL where the current project is hosted. For example, https://github.com/circleci/circleci-docs.

pipeline.project.type

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

The lower-case name of the VCS provider, for example, github, bitbucket.

pipeline.git.tag

GitHub App, GitHub OAuth, Bitbucket, GitLab

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.

pipeline.git.branch

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

The name of the git branch that was pushed to trigger the pipeline.

pipeline.git.revision

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

The long (40-character) git SHA that is being built.

pipeline.git.base_revision

GitHub OAuth, Bitbucket

String

The long (40-character) git SHA of the build prior to the one being built. Note: While in most cases pipeline.git.base_revision will be the SHA of the pipeline that ran before your currently running pipeline, there are some caveats. When the build is the first build for a branch, the variable will not be present. In addition, if the build was triggered via the API, the variable will not be present.

pipeline.trigger_source

GitHub App, GitHub OAuth, Bitbucket, GitLab

String

The source that triggers the pipeline, current values are webhook, api, scheduled_pipeline.

pipeline.schedule.name

GitHub OAuth, Bitbucket

String

The name of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggered by other sources.

pipeline.schedule.id

GitHub OAuth, Bitbucket

String

The unique id of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggered by other sources.

pipeline.trigger_parameters.circleci.trigger_type

GitHub App, GitLab

GitHub App, GitLab

pipeline.trigger_parameters.circleci.event_time

GitHub App, GitLab

Timestamp CircleCI received the event

pipeline.trigger_parameters.circleci.event_type

GitHub App, GitLab

  • GitLab: push, merge request

  • GitHub App: push

pipeline.trigger_parameters.circleci.project_id

GitHub App, GitLab

CircleCI project ID

pipeline.trigger_parameters.circleci.actor_id

GitHub App, GitLab

CircleCI user ID

pipeline.trigger_parameters.gitlab.type

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.type

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.project_id

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.project_id

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.ref

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.ref

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.checkout_sha

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.checkout_sha

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.user_id

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.user_id

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.user_name

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.user_name

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.user_username

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.user_username

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.user_avatar

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.user_avatar

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.repo_name

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.repo_name

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.repo_url

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.repo_url

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.web_url

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.web_url

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_sha

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_sha

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_title

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_title

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_message

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_message

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_timestamp

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_timestamp

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_author_name

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_author_name

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.commit_author_email

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.commit_author_email

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.total_commits_count

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.total_commits_count

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.branch

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.branch

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.default_branch

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.github_app.default_branch

GitHub App

See GitHub documentation for webhook events and payloads.

pipeline.trigger_parameters.gitlab.x_gitlab_event_id

GitLab

See GitLab documentation for webhooks and webhook events.

pipeline.trigger_parameters.gitlab.is_fork_merge_request

GitLab

See GitLab documentation for webhooks and webhook events.

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_URL

When 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

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

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

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 from the web app, and the parameter has not been declared in the configuration file, the pipeline will fail with the error Unexpected argument(s).

  1. Use the project filter to select the desired project.

  2. Use the branch filter to select the branch on which you want to run the new pipeline.

  3. Click the Trigger Pipeline button (towards the top right corner of the page).

  4. Use the Add Parameters dropdown to specify the type, name, and value of your desired parameters.

  5. Click Trigger Pipeline.

Parameters can also be called when setting up a scheduled pipeline in the web app. The parameters are part of the trigger form in Project Settings  Triggers. Any parameter set up as a part of a scheduled pipeline 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. This is because 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: echo << parameters.message >>

Even though the print command is called from the cat-file job, the file parameter would not be in scope inside the print job. 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: message.

Pipeline value scope

Pipeline values, the pipeline-wide values that are provided by CircleCI (e.g. << 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

When using setup workflows to pass control of the pipeline to a second configuration, all pipeline parameters that are declared in the setup workflow must also be declared, with the same defaults, in the second configuration.

When the setup workflow passes control to a second configuration, the parameters passed to the setup workflow will be merged in with any parameters specified in the setup workflow, before being passed to the second configuration. When using dynamic configuration, the second configuration must tolerate receiving any parameters that the setup workflow’s code passes, as well as any parameters that the setup workflow could accept.

If there are name conflicts between pipeline parameters specified in a setup workflow and those specified in an API request when triggering a pipeline, the continuation process will fail, and the pipeline will error.

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 steps

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


Suggest an edit to this page

Make a contribution
Learn how to contribute