> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Pipeline values and parameters ## 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](https://circleci.com/docs/reference/variables/) guide. **Check your project slug to discover which GitHub integration you have set up:** 1. Head to the [CircleCI web app](https://app.circleci.com/home) and select your org from the cards on your user homepage. 2. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help. 3. 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 `circleci` followed 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 [Version Control Systems, Pipeline Types, and Feature Support](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) guide. ### Pipeline and project information 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 Pipeline type Type Value Cloud Server `pipeline.id` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String A [globally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) for the pipeline. **Yes** **Yes** `pipeline.number` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab Integer A project-scoped integer identifier for the pipeline. **Yes** **Yes** `pipeline.definition.id` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab _(except schedule workflows)_ String The unique ID of the pipeline definition. **Yes** **Yes** `pipeline.project.git_url` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The URL where the current project is hosted. For example, `[https://github.com/circleci/circleci-docs](https://github.com/circleci/circleci-docs)`. **Yes** **Yes** `pipeline.project.type` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The lower-case name of the VCS provider, for example, `github`, `bitbucket`. **Yes** **Yes** `pipeline.project.slug` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The slug of the project the pipeline definition belongs to. **Yes** **Yes** `pipeline.name` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center _(except schedule workflows)_ String The name of the pipeline definition. **Yes** **No** `pipeline.integration_source` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The pipeline type, determined by the VCS integration used to check out code. Possible values: `github_app`, `github_server`, `github`, `bitbucket`, `bitbucket_dc`, `gitlab`. **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 and GitHub App Server pipelines, this may differ from the following: * The commit or branch that triggered the event. * The commit or branch used to fetch the configuration file. Variable Pipeline type Type Value Cloud Server `pipeline.git.tag` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The name of the git tag that CircleCI checks out. Empty if the pipeline checks out from a branch. **Yes** **Yes** `pipeline.git.branch` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The name of the git branch that CircleCI checks out. Empty if the pipeline checks out from a tag. **Yes** **Yes** `pipeline.git.branch.is_default` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab Boolean Whether CircleCI checks out the default branch. **Yes** **Yes** (>= v4.7) `pipeline.git.revision` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The long (40-character) git SHA of the commit that CircleCI checks out. **Yes** **Yes** `pipeline.git.repo_url` GitHub App GitHub App Server Bitbucket Data Center String The URL of the repository. **Yes** **No** `pipeline.git.repo_owner` GitHub App GitHub App Server String The VCS username of the repository owner. **Yes** **No** `pipeline.git.repo_name` GitHub App GitHub App Server String The name of the repository, without the owner prefix. **Yes** **No** `pipeline.git.repo_id` GitHub App GitHub App Server Bitbucket Data Center String The unique identifier of the repository. **Yes** **No** `pipeline.git.commit.url` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab _(except schedule workflows)_ String The URL of the checkout commit. **Yes** **Yes** `pipeline.git.commit.subject` GitHub App GitHub App Server GitHub OAuth _(push events only)_ Bitbucket Cloud _(push events only)_ Bitbucket Data Center GitLab String The subject line of the checkout commit message. **Yes** **No** `pipeline.git.commit.body` GitHub App GitHub App Server Bitbucket Cloud _(push events only)_ Bitbucket Data Center GitLab String The body of the checkout commit message. **Yes** **No** `pipeline.git.commit.author_login` GitHub App GitHub App Server GitHub OAuth _(push events only)_ Bitbucket Data Center GitLab String The VCS username of the author of the checkout commit. **Yes** **No** `pipeline.git.base_revision` GitHub OAuth Bitbucket Cloud String The long (40-character) git SHA of the build that ran before the current build. **Note:** While in most cases `pipeline.git.base_revision` will be the SHA of the commit that ran before your currently running pipeline, there are some caveats. When the build runs first for a branch, the variable will not appear. In addition, if you trigger the build via the API, the variable will not appear. **Yes** **Yes** ### Configuration source information Values prefixed with `pipeline.config.*` describe where CircleCI fetched the configuration file from. These values currently only apply to GitHub App and GitHub App Server pipelines where the configuration file can reside in a separate repository from the one CircleCI builds. For all other pipeline types, the configuration file always lives in the same repository as the code CircleCI checks out, so you can use the corresponding `pipeline.git.*` values instead. Variable Pipeline type Type Value Cloud Server `pipeline.config.repository.name` GitHub App GitHub App Server String The name of the repository containing the CircleCI configuration file, in the format `owner/repo-name`. **Yes** **No** `pipeline.config.repository.url` GitHub App GitHub App Server String The URL of the repository containing the CircleCI configuration file. **Yes** **No** `pipeline.config.file_path` GitHub App GitHub App Server String The file path to the CircleCI configuration file used by the pipeline. **Yes** **No** `pipeline.config.ref` GitHub App GitHub App Server String The full Git ref used to fetch the CircleCI configuration file, for example `refs/heads/main` or `refs/tags/v1.0`. **Yes** **No** `pipeline.config.sha` GitHub App GitHub App Server 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 `pipeline.trigger_parameters.circleci.*` and `pipeline.trigger_parameters.github_app.*` values are deprecated and their presence is not guaranteed after **2026-08-01**. Use the replacement values listed in the table below. Variable Pipeline type Type Value Cloud Server `pipeline.trigger.received_at` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String The timestamp of when the pipeline was triggered, in ISO 8601 format. **Yes** **Yes** `pipeline.trigger.id` GitHub App GitHub App Server Bitbucket Data Center String The unique ID of the trigger that initiated the pipeline. **Yes** **No** `pipeline.trigger.type` GitHub App GitHub App Server Bitbucket Cloud Bitbucket Data Center String The type of trigger that initiated the pipeline. Possible values: `github_app`, `bitbucket_dc`, `schedule`, `webhook`, `api`. **Yes** **No** `pipeline.trigger_source` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud Bitbucket Data Center GitLab String Use `pipeline.trigger.type` instead. **Yes** **Yes** `pipeline.schedule.name` GitHub OAuth Bitbucket Cloud String The name of the schedule trigger if the pipeline was triggered via schedule. Empty if the pipeline was not triggered via schedule. **Yes** **Yes** `pipeline.schedule.id` GitHub OAuth Bitbucket Cloud String The unique ID of the schedule if the pipeline was triggered via schedule. Empty if the pipeline was not triggered via schedule. **Yes** **Yes** `pipeline.event.name` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud String The name of the event that triggered the pipeline. Possible values: `custom_webhook`, `api`, `push`, `pull_request`, `schedule`. **Yes** **No** `pipeline.event.action` GitHub App GitHub App Server GitHub OAuth Bitbucket Cloud String The action associated with the event. This value is the same as `pipeline.event.name` except for events that have an `action` subtype: [GitHub `pull_request`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request) events and [Bitbucket Cloud `pullrequest:*`](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/#Pull-request-events) events. Possible values: `custom_webhook`, `api`, `push`, `schedule`, `opened`, `synchronize`, `reopened`, `closed`, `ready_for_review`, `labeled`, `created`, `updated`, `fulfilled`, `rejected`. Read more about [GitHub Trigger Event Options](https://circleci.com/docs/guides/orchestrate/github-trigger-event-options/#supported-trigger-options). **Yes** **No** `pipeline.event.github.after` GitHub App GitHub App Server String The SHA of the most recent commit on the branch after the push. Corresponds to the `after` field on the [GitHub push event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push). Only populated for push events. **Yes** **No** `pipeline.event.github.head_commit.url` GitHub App GitHub App Server String The URL of the most recent commit on the branch. Corresponds to the `head_commit.url` field on the [GitHub push event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push). Only populated for push events. **Yes** **No** `pipeline.event.github.ref` GitHub App GitHub App Server String The full Git ref that was pushed. Corresponds to the `ref` field on the [GitHub push event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push). Only populated for push events. **Yes** **No** `pipeline.event.context.github.pr_url` GitHub App GitHub App Server 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** `pipeline.event.github.pull_request.base.ref` GitHub App GitHub App Server String The name of the base (or target) branch of the pull request. Corresponds to the `pull_request.base.ref` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.base.sha` GitHub App GitHub App Server String The SHA of the base branch of the pull request. Corresponds to the `pull_request.base.sha` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.head.ref` GitHub App GitHub App Server String The name of the head branch of the pull request. Corresponds to the `pull_request.head.ref` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.head.sha` GitHub App GitHub App Server String The SHA of the head branch of the pull request. Corresponds to the `pull_request.head.sha` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.draft` GitHub App GitHub App Server Boolean A boolean value indicating whether the pull request is a draft. Corresponds to the `pull_request.draft` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.title` GitHub App GitHub App Server String The title of the pull request. Corresponds to the `pull_request.title` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.number` GitHub App GitHub App Server Integer The numeric identifier of the pull request. Corresponds to the `pull_request.number` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.merged` GitHub App GitHub App Server Boolean A boolean value indicating whether the pull request has been merged. Corresponds to the `pull_request.merged` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.pull_request.url` GitHub App GitHub App Server String The URL of the pull request. Corresponds to the `pull_request.url` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events. **Yes** **No** `pipeline.event.github.label.name` GitHub App GitHub App Server String The name of the label applied to the pull request. Corresponds to the `label.name` field on the [GitHub pull request event payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request). Only populated for pull request events with the `labeled` action. **Yes** **No** `pipeline.event.github.comment.body` GitHub App GitHub App Server String The body of the comment that triggered the pipeline, with leading and trailing whitespace removed. Corresponds to the `comment.body` field on `issue_comment` and `pull_request_review_comment` GitHub event payloads. Only populated for pipelines triggered by a PR comment. **Yes** **No** `pipeline.event.github.sender.type` GitHub App GitHub App Server String The type of GitHub user that triggered the event. Corresponds to the `sender.type` field on GitHub event payloads. Possible values are `User`, `Organization`, and `Bot`. **Yes** **No** `pipeline.event.github.sender.avatar_url` GitHub App GitHub App Server String The avatar URL of the GitHub user who triggered the event. Corresponds to the `sender.avatar_url` field on GitHub event payloads. **Yes** **No** `pipeline.event.github.sender.login` GitHub App GitHub App Server String The VCS username of the GitHub user who triggered the event. Corresponds to the `sender.login` field on GitHub event payloads. **Yes** **No** `pipeline.event.github.repository.name` GitHub App GitHub App Server String The name of the repository that triggered the event, without the owner prefix. Corresponds to the `repository.name` field on repository-related GitHub event payloads. **Yes** **No** `pipeline.event.github.repository.owner.login` GitHub App GitHub App Server String The VCS username of the repository owner. Corresponds to the `repository.owner.login` field on repository-related GitHub event payloads. **Yes** **No** `pipeline.event.github.repository.url` GitHub App GitHub App Server String The URL of the repository that triggered the event. Corresponds to the `repository.url` field on repository-related GitHub event payloads. **Yes** **No** `pipeline.trigger_parameters.webhook.body` Custom webhook String The body of the payload that was sent with a [Custom Webhook](https://circleci.com/docs/guides/orchestrate/triggers-overview/#trigger-a-pipeline-from-a-custom-webhook). **Yes** **No** `pipeline.trigger_parameters.circleci.trigger_type` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server GitLab String Use `pipeline.trigger.type` instead. **Yes** **No** `pipeline.trigger_parameters.circleci.event_time` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server GitLab String Use `pipeline.trigger.received_at` instead. **Yes** **No** `pipeline.trigger_parameters.circleci.event_type` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server GitLab String Use `pipeline.event.name` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.ref` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server For push events, use `pipeline.event.github.ref`. For pull request events, use `pipeline.event.github.pull_request.head.ref`. **Yes** **No** `pipeline.trigger_parameters.github_app.checkout_sha` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.git.revision` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.user_id` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server No direct replacement is available. If this value is critical to your workflows, contact CircleCI Support. **Yes** **No** `pipeline.trigger_parameters.github_app.user_name` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.sender.login` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.user_username` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.sender.login` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.user_avatar` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.sender.avatar_url` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.repo_name` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.repository.name` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.repo_url` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.repository.url` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.web_url` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.repository.url` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.commit_sha` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.event.github.after` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.commit_title` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.git.commit.subject` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.commit_message` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.git.commit.body` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.commit_timestamp` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server Use `pipeline.trigger.received_at` instead. **Yes** **No** `pipeline.trigger_parameters.github_app.commit_author_name` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server For the user who triggered the push event, use `pipeline.event.github.sender.*`. For the checkout commit author, use `pipeline.git.commit.author_login`. **Yes** **No** `pipeline.trigger_parameters.github_app.branch` **Deprecated** - support ends on 2026-08-01. GitHub App GitHub App Server For push events, use `pipeline.event.github.ref`. For pull request events, use `pipeline.event.github.pull_request.head.ref`. **Yes** **No** `pipeline.trigger_parameters.gitlab.type` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.ref` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.checkout_sha` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.user_id` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.user_name` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.user_username` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.user_avatar` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.repo_name` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.repo_url` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.web_url` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_sha` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_title` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_message` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_timestamp` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_author_name` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.commit_author_email` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.branch` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.default_branch` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.x_gitlab_event_id` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** `pipeline.trigger_parameters.gitlab.is_fork_merge_request` GitLab See GitLab documentation for [webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and [webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). **Yes** **No** ### Deploy information Values prefixed with `pipeline.deploy.*` are only available for deployment pipelines. See the [Set up a Rollback Pipeline](https://circleci.com/docs/guides/deploy/set-up-rollbacks/) and [Set up a Deploy Pipeline](https://circleci.com/docs/guides/deploy/set-up-deploys/) guides for more information. Variable Pipeline type Type Value Cloud Server `pipeline.deploy.component_name` GitHub App GitHub App Server String The name of the component that will be rolled back or deployed. **Yes** **No** `pipeline.deploy.environment_name` GitHub App GitHub App Server String The name of the environment in which the rollback or deploy will be performed. **Yes** **No** `pipeline.deploy.target_version` GitHub App GitHub App Server String The version of the component that needs to be rolled back to or deployed. **Yes** **No** `pipeline.deploy.current_version` GitHub App GitHub App Server String The current version of the component that CircleCI will roll back or deploy. Use this to verify that the component status matches expectations. **Yes** **No** `pipeline.deploy.namespace` GitHub App GitHub App Server String The namespace of the environment that was deployed to. **Yes** **No** `pipeline.deploy.reason` GitHub App GitHub App Server 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 >>..<> 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 ``. If you need an empty string instead, [Set the Variable in a Shell Command](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-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](https://circleci.com/docs/reference/reusing-config/#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](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](https://circleci.com/docs/api/v2/#trigger-a-new-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](https://circleci.com/docs/api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun) 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}/pipeline ````````` **To find your project slug, follow these steps:** 1. Head to the [CircleCI web app](https://app.circleci.com/home) and select your org from the cards on your user homepage. 2. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help. 3. 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 `circleci` followed 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](https://circleci.com/docs/guides/toolkit/api-developers-guide/#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)`. 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. Select **Trigger Pipeline** (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. 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 **Project Settings**  **Triggers** or **Project Settings**  **Project Setup**. 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](https://circleci.com/developer/orbs/orb/circleci/continuation). 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 of the following conditions are met: 1. The pipeline is triggered via the API. 2. 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](https://circleci.com/docs/guides/orchestrate/dynamic-config/#how-dynamic-config-works) section of the Dynamic Configuration overview. ## Pipeline parameters and conditional workflows Use the [`when` clause](https://circleci.com/docs/reference/configuration-reference/#using-when-in-workflows) (or the inverse clause `unless`) under a workflow declaration, along with a [logic statement](https://circleci.com/docs/reference/configuration-reference/#logic-statements), to decide whether or not to run that workflow. Logic statements in a `when` or `unless` clause must 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.