---
title: "Pipeline values and parameters"
description: "Learn about pipeline values and pipeline parameters, and how to use them in your CircleCI configuration."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-06"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, 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. To insert them into `config.yml` at compile time, see the [Config Templating](https://circleci.com/docs/guides/server/orchestrate/config-templating/) page.

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

### 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | A [globally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) for the pipeline. | **Yes** | **Yes** |
| `pipeline.number` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | Integer | A project-scoped integer identifier for the pipeline. | **Yes** | **Yes** |
| `pipeline.definition.id` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin<br>_(except schedule workflows)_ | String | The unique ID of the pipeline definition. | **Yes** | **Yes** |
| `pipeline.project.git_url` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The lower-case name of the VCS provider, for example, `github`, `bitbucket`. | **Yes** | **Yes** |
| `pipeline.project.slug` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The slug of the project the pipeline definition belongs to. | **Yes** | **Yes** |
| `pipeline.name` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin<br>_(except schedule workflows)_ | String | The name of the pipeline definition. | **Yes** | **No** |
| `pipeline.integration_source` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | Boolean | Whether CircleCI checks out the default branch. | **Yes** | **Yes** (>= v4.7) |
| `pipeline.git.revision` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The long (40-character) git SHA of the commit that CircleCI checks out. | **Yes** | **Yes** |
| `pipeline.git.repo_url` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | String | The URL of the repository. | **Yes** | **No** |
| `pipeline.git.repo_owner` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | String | The VCS username of the repository owner. | **Yes** | **No** |
| `pipeline.git.repo_name` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | String | The name of the repository, without the owner prefix. | **Yes** | **No** |
| `pipeline.git.repo_id` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | String | The unique identifier of the repository. | **Yes** | **No** |
| `pipeline.git.commit.url` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin<br>_(except schedule workflows)_ | String | The URL of the checkout commit. | **Yes** | **Yes** |
| `pipeline.git.commit.subject` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The subject line of the checkout commit message. | **Yes** | **No** |
| `pipeline.git.commit.body` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The body of the checkout commit message. | **Yes** | **No** |
| `pipeline.git.commit.author_login` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>GitLab<br>Cursor Origin | String | The VCS username of the author of the checkout commit. Not available for Bitbucket Cloud because Bitbucket has [deprecated usernames](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/). | **Yes** | **No** |
| `pipeline.git.base_revision` | GitHub OAuth<br>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<br>GitHub App Server<br>Cursor Origin | 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<br>GitHub App Server<br>Cursor Origin | String | The URL of the repository containing the CircleCI configuration file. | **Yes** | **No** |
| `pipeline.config.file_path` | GitHub App<br>GitHub App Server<br>Cursor Origin | String | The file path to the CircleCI configuration file used by the pipeline. | **Yes** | **No** |
| `pipeline.config.ref` | GitHub App<br>GitHub App Server<br>Cursor Origin | 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<br>GitHub App Server<br>Cursor Origin | 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-09-21**. Use the replacement values listed in the table below.

| Variable | Pipeline type | Type | Value | Cloud | Server |
| --- | --- | --- | --- | --- | --- |
| `pipeline.trigger.received_at` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | The timestamp of when the pipeline was triggered, in ISO 8601 format. | **Yes** | **Yes** |
| `pipeline.trigger.id` | GitHub App<br>GitHub App Server<br>Cursor Origin | String | The unique ID of the trigger that initiated the pipeline. | **Yes** | **No** |
| `pipeline.trigger.type` | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | String | The type of trigger that initiated the pipeline. Possible values: `github_app`, `github_server`, `github_oauth`, `bitbucket_cloud`, `bitbucket_dc`, `schedule`, `webhook`, `api`. | **Yes** | **No** |
| `pipeline.trigger_source`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>GitLab<br>Cursor Origin | String | Use `pipeline.trigger.type` instead. | **Yes** | **Yes** |
| `pipeline.schedule.name` | GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | 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<br>Bitbucket Cloud<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | 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<br>GitHub App Server<br>GitHub OAuth<br>Bitbucket Cloud<br>Cursor Origin | 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. | **Yes** | **No** |
| `pipeline.event.github.after` | GitHub App<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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<br>GitHub App Server<br>GitHub OAuth | 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.circleci.trigger_type`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server<br>GitLab | String | Use `pipeline.trigger.type` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.circleci.event_time`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server<br>GitLab | String | Use `pipeline.trigger.received_at` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.circleci.event_type`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server<br>GitLab | String | Use `pipeline.event.name` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.ref`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>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`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.git.revision` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.user_id`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>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`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.sender.login` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.user_username`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.sender.login` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.user_avatar`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.sender.avatar_url` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.repo_name`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.repository.name` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.repo_url`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.repository.url` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.web_url`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.repository.url` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.commit_sha`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.event.github.after` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.commit_title`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.git.commit.subject` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.commit_message`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.git.commit.body` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.commit_timestamp`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>GitHub App Server |  | Use `pipeline.trigger.received_at` instead. | **Yes** | **No** |
| `pipeline.trigger_parameters.github_app.commit_author_name`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>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`<br>**Deprecated** - support ends on 2026-08-01. | GitHub App<br>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** |

Usage example:

```yaml
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](https://circleci.com/docs/guides/server/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:

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

```shell
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 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 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/server/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**.
    

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

```yaml
version: 2.1

commands:
  print:
    parameters:
      message:
        type: string
    steps:
      - run: echo << parameters.message >>

jobs:
  daily-message:
    machine:
      image: ubuntu-2404: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/server/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 [expressions](https://circleci.com/docs/reference/configuration-reference/#using-expressions-in-your-configuration), to decide whether or not to run that workflow. Expressions 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.

```yaml
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:

```json
{
    "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.