Project values and variables

Cloud

Server v4+

Built-in environment variables

The following built-in environment variables are available for CircleCI projects. Some environment variables are available for GitHub OAuth and Bitbucket Cloud projects that have been deprecated for GitLab, GitHub App and Bitbucket Data Center 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 and can be used within the context of a job. Environment variables 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	Server
`CI`	GitHub, Bitbucket, GitLab	Boolean	`true` (represents whether the current environment is a CI environment)
`CIRCLECI`	GitHub, Bitbucket, GitLab	Boolean	`true` (represents whether the current environment is a CircleCI environment)
`CIRCLE_BRANCH`	GitHub, Bitbucket, GitLab	String	The name of the Git branch currently being built.
`CIRCLE_BUILD_NUM`	GitHub, Bitbucket, GitLab	Integer	The number of the current job. Job numbers are unique for each job.
`CIRCLE_BUILD_URL`	GitHub, Bitbucket, GitLab	String	The URL for the current job on CircleCI.
`CIRCLE_JOB`	GitHub, Bitbucket, GitLab	String	The name of the current job.
`CIRCLE_NODE_INDEX`	GitHub, 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 (`CIRCLE_NODE_TOTAL` - 1)
`CIRCLE_NODE_TOTAL`	GitHub, Bitbucket, GitLab	Integer	For jobs that run with parallelism enabled, this is the number of parallel runs. This is equivalent to the value of `parallelism` in your config file.
`CIRCLE_OIDC_TOKEN`	GitHub, Bitbucket, GitLab	String	An OpenID Connect token signed by CircleCI which includes details about the current job.	from v4.4
`CIRCLE_OIDC_TOKEN_V2`	GitHub, Bitbucket, GitLab	String	An OpenID Connect token signed by CircleCI which includes details about the current job.	from v4.4
`CIRCLE_ORGANIZATION_ID`	GitHub, Bitbucket, GitLab	String	A unique identifier for the CircleCI organization.
`CIRCLE_PIPELINE_ID`	GitHub, Bitbucket, GitLab	String	A unique identifier for the current pipeline.
`CIRCLE_PR_NUMBER`	GitHub OAuth, Bitbucket Cloud	Integer	The number of the associated GitHub or Bitbucket pull request. Only available on forked PRs.
`CIRCLE_PR_REPONAME`	GitHub OAuth, Bitbucket Cloud	String	The name of the GitHub or Bitbucket repository where the pull request was created. Only available on forked PRs.
`CIRCLE_PR_USERNAME`	GitHub OAuth, Bitbucket Cloud	String	The GitHub or Bitbucket username of the user who created the pull request. Only available on forked PRs.
`CIRCLE_PREVIOUS_BUILD_NUM`	GitHub, 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 will be deprecated and is not recommended for use.
`CIRCLE_PROJECT_ID`	GitHub, Bitbucket, GitLab	String	A unique identifier for the current project.
`CIRCLE_PROJECT_REPONAME`	GitHub, GitLab, Bitbucket	String	The name of the repository of the current project.
`CIRCLE_PROJECT_USERNAME`	GitHub, GitLab, Bitbucket	String	The GitHub or Bitbucket username of the current project.
`CIRCLE_PULL_REQUEST`	GitHub, Bitbucket Cloud	String	The URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen.
`CIRCLE_PULL_REQUESTS`	GitHub OAuth, Bitbucket Cloud	List	Comma-separated list of URLs of the current build’s associated pull requests.
`CIRCLE_REPOSITORY_URL`	GitHub OAuth, Bitbucket Cloud	String	The URL of your GitHub or Bitbucket repository.
`CIRCLE_SHA1`	GitHub, GitLab, Bitbucket	String	The SHA1 hash of the last commit of the current build.
`CIRCLE_TAG`	GitHub, 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.
`CIRCLE_USERNAME`	GitHub, Bitbucket, GitLab	String	The GitHub or Bitbucket username of the user who triggered the pipeline (only if the user has a CircleCI account).
`CIRCLE_WORKFLOW_ID`	GitHub, 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.
`CIRCLE_WORKFLOW_JOB_ID`	GitHub, Bitbucket, GitLab	String	A unique identifier for the current job.
`CIRCLE_WORKFLOW_WORKSPACE_ID`	GitHub, Bitbucket, GitLab	String	An identifier for the workspace of the current job. This identifier is the same for every job in a given workflow.
`CIRCLE_WORKING_DIRECTORY`	GitHub, Bitbucket, GitLab	String	The value of the `working_directory` key of the current job.
`CIRCLE_INTERNAL_TASK_DATA`	GitHub, 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	Source	Type	Value	Server
`pipeline.id`	GitHub, Bitbucket, GitLab	String	A globally unique id representing for the pipeline.
`pipeline.number`	GitHub, Bitbucket, GitLab	Integer	A project unique integer id for the pipeline.
`pipeline.project.git_url`	GitHub, Bitbucket, GitLab	String	The URL where the current project is hosted. For example, `https://github.com/circleci/circleci-docs`.
`pipeline.project.type`	GitHub, Bitbucket, GitLab	String	The lower-case name of the VCS provider, for example, `github`, `bitbucket`.
`pipeline.git.tag`	GitHub, 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, Bitbucket, GitLab	String	The name of the git branch that was pushed to trigger the pipeline.
`pipeline.git.branch.is_default`	GitHub, Bitbucket, GitLab	Boolean	Whether the branch the pipeline was triggered on is the default branch.	(>= v4.7)
`pipeline.git.revision`	GitHub, Bitbucket, GitLab	String	The long (40-character) git SHA that is being built.
`pipeline.git.base_revision`	GitHub OAuth, Bitbucket Cloud	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, Bitbucket, GitLab	String	The source that triggers the pipeline, current values are `webhook`, `api`, `scheduled_pipeline`.
`pipeline.schedule.name`	GitHub OAuth, Bitbucket Cloud	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 Cloud	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.gitlab.type`	GitLab		See GitLab documentation for webhooks and webhook events.
`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.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.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.
`pipeline.trigger_parameters.webhook.body`	Custom webhook	String	The body of the payload that was sent with a custom webhook.
`pipeline.event.name`	GitHub App	String	The name of the event that triggered the pipeline. Possible values: `custom_webhook`, `api`, `push`, `pull_request`.
`pipeline.event.action`	GitHub App	String	The action associated with the event. This value is always the same as `pipeline.event.name`, except for GitHub events that have an `action` property, for example pull_request. Possible values: `custom_webhook`, `api`, `push`, `opened`, `synchronize`, `reopened`, `closed`, `ready_for_review`, `labeled`. Read more about trigger event options.
`pipeline.event.context.github.pr_url`	GitHub App	String	The URL of the associated GitHub pull request, if one exists. If there are multiple associated pull requests, one URL is randomly chosen. This value matches env variable CIRCLE_PULL_REQUEST.
`pipeline.event.github.pull_request.base.ref`	GitHub App	String	The name of the base (or target) branch of the PR - that is the branch that will receive the changes. Only populated for pipelines triggered by pull request events (`pipeline.event.name = 'pull_request'`).
`pipeline.event.github.pull_request.head.ref`	GitHub App	String	The name of the head branch of the PR - that is the branch containing the changes to be merged. Only populated for pipelines triggered by pull request events (`pipeline.event.name = "pull_request"`).
`pipeline.event.github.pull_request.draft`	GitHub App	Boolean	A boolean value indicating whether the pull request is a draft. Only populated for pipelines triggered by pull request events (`pipeline.event.name = "pull_request"`).
`pipeline.event.github.pull_request.title`	GitHub App	String	The title of the pull request. Only populated for pipelines triggered by pull request events (`pipeline.event.name = "pull_request"`).
`pipeline.event.github.pull_request.number`	GitHub App	Integer	The numeric identifier of the pull request. Only populated for pipelines triggered by pull request events (`pipeline.event.name = "pull_request"`).

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.

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site

Project values and variables

On This Page

Built-in environment variables

Pipeline values

Suggest an edit to this page

Still need help?