Project values and variables
On This Page
This page is a reference for all built-in values available for use in your CircleCI projects.
Built-in environment variables
The following built-in environment variables are available for CircleCI projects. A few environment variables are available for GitHub and Bitbucket projects that have been deprecated for GitLab SaaS support. If you must continue to use those as environment variables in your GitLab pipelines, refer to the workaround described after the list below.
Environment variables are scoped at the job level. They can be used within the context of a job but do not exist at a pipeline level, therefore they cannot be used for any logic at the pipeline or workflow level.
You cannot use a built-in environment variable to define another environment variable. Instead, you must use a run step to export the new environment variables using BASH_ENV . For more details, see Setting an Environment Variable in a Shell Command. |
Variable | VCS | Type | Value | Cloud | Server |
---|---|---|---|---|---|
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Boolean |
| ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Boolean |
| ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The name of the Git branch currently being built. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Integer | The number of the current job. Job numbers are unique for each job. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The URL for the current job on CircleCI. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The name of the current job. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Integer | For jobs that run with parallelism enabled, this is the index of the current parallel run. The value ranges from 0 to ( | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Integer | For jobs that run with parallelism enabled, this is the number of parallel runs. This is equivalent to the value of | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | An OpenID Connect token signed by CircleCI which includes details about the current job. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | An OpenID Connect token signed by CircleCI which includes details about the current job. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | A unique identifier for the CircleCI organization. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | A unique identifier for the current pipeline. | ||
| GitHub OAuth, Bitbucket | Integer | The number of the associated GitHub or Bitbucket pull request. Only available on forked PRs. | ||
| GitHub OAuth, Bitbucket | String | The name of the GitHub or Bitbucket repository where the pull request was created. Only available on forked PRs. | ||
| GitHub OAuth, Bitbucket | String | The GitHub or Bitbucket username of the user who created the pull request. Only available on forked PRs. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | Integer | The largest job number in a given branch that is less than the current job number. Note: The variable is not always set, and is not deterministic. It is also not set on runner executors. This variable is likely to be deprecated, and CircleCI recommends users to avoid using it. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | A unique identifier for the current project. | ||
| GitHub OAuth, GitHub App, GitLab, Bitbucket | String | The name of the repository of the current project. | ||
| GitHub OAuth, GitHub App, GitLab, Bitbucket | String | The GitHub or Bitbucket username of the current project. | ||
| GitHub OAuth, Bitbucket | String | The URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen. | ||
| GitHub OAuth, Bitbucket | List | Comma-separated list of URLs of the current build’s associated pull requests. | ||
| GitHub OAuth, Bitbucket | String | The URL of your GitHub or Bitbucket repository. | ||
| GitHub OAuth, GitHub App, GitLab, Bitbucket | String | The SHA1 hash of the last commit of the current build. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The name of the git tag, if the current build is tagged. For more information, see the Git tag job execution section of the Workflows page. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The GitHub or Bitbucket username of the user who triggered the pipeline (only if the user has a CircleCI account). | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | A unique identifier for the workflow instance of the current job. This identifier is the same for every job in a given workflow instance. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | A unique identifier for the current job. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | An identifier for the workspace of the current job. This identifier is the same for every job in a given workflow. | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | The value of the | ||
| GitHub OAuth, GitHub App, Bitbucket, GitLab | String | Internal. A directory where internal data related to the job is stored. We do not document the contents of this directory; the data schema is subject to change. |
If you must use the environment variables that are deprecated for GitLab SaaS in your GitLab pipelines, you can recreate this functionality using pipeline values in your configuration file. The following example shows how to set an environment variable CIRCLE_PROJECT_REPONAME
using the environment
key and populating it with the pipeline.trigger_parameters.gitlab.repo_name
value:
build:
docker:
- image: cimg/node:17.0
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
CIRCLE_PROJECT_REPONAME: << pipeline.trigger_parameters.gitlab.repo_name >>
steps:
- run: echo $CIRCLE_PROJECT_REPONAME
Pipeline values
Pipeline values are available to all pipeline configurations and can be used without previous declaration. Pipeline values are scoped at the pipeline level. They are interpolated at compilation time, not workflow/job runtime.
For GitHub users, refer to the GitHub App integration or GitHub OAuth app integration guides to check which integration type applies to you. |
Variable | VCS | Type | Value | Cloud | Server |
---|---|---|---|---|---|
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | A globally unique id representing for the pipeline. | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | Integer | A project unique integer id for the pipeline. | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | The URL where the current project is hosted. For example, | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | The lower-case name of the VCS provider, for example, | ||
| 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. | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | The name of the git branch that was pushed to trigger the pipeline. | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | The long (40-character) git SHA that is being built. | ||
| GitHub OAuth, Bitbucket | String | The long (40-character) git SHA of the build prior to the one being built. Note: While in most cases | ||
| GitHub App, GitHub OAuth, Bitbucket, GitLab | String | The source that triggers the pipeline, current values are | ||
| 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. | ||
| 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. | ||
| GitHub App, GitLab | GitHub App, GitLab | |||
| GitHub App, GitLab | Timestamp CircleCI received the event | |||
| GitHub App, GitLab |
| |||
| GitHub App, GitLab | CircleCI project ID | |||
| GitHub App, GitLab | CircleCI user ID | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitHub App | See GitHub documentation for webhook events and payloads. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. | |||
| GitLab | See GitLab documentation for webhooks and webhook events. |
For example:
version: 2.1
jobs:
build:
docker:
- image: cimg/node:20.3.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 variables 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.