Project values and variables
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 all CircleCI projects. 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.
Note: 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.
| ||String||The name of the Git branch currently being built.|
| ||Integer||The number of the current job. Job numbers are unique for each job.|
| ||String||The URL for the current job on CircleCI.|
| ||String||The name of the current job.|
| ||Integer||For jobs that run with parallelism enabled, this is the index of the current parallel run. The value ranges from 0 to ( |
| ||Integer||For jobs that run with parallelism enabled, this is the number of parallel runs. This is equivalent to the value of |
| ||String||An OpenID Connect token signed by CircleCI which includes details about the current job. Available in jobs that use a context.|
| ||Integer||The number of the associated GitHub or Bitbucket pull request. Only available on forked PRs.|
| ||String||The name of the GitHub or Bitbucket repository where the pull request was created. Only available on forked PRs.|
| ||String||The GitHub or Bitbucket username of the user who created the pull request. Only available on forked PRs.|
| ||Integer||The number of previous builds on the current branch. Note: This variable is not set on runner executors.|
| ||String||The name of the repository of the current project.|
| ||String||The GitHub or Bitbucket username of the current project.|
| ||String||The URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen.|
| ||List||Comma-separated list of URLs of the current build’s associated pull requests.|
| ||String||The URL of your GitHub or Bitbucket repository.|
| ||String||The SHA1 hash of the last commit of the current build.|
| ||String||The name of the git tag, if the current build is tagged. For more information, see the Git Tag Job Execution.|
| ||String||The GitHub or Bitbucket username of the user who triggered the pipeline (only if the user has a CircleCI account).|
| ||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.|
| ||String||A unique identifier for the current job.|
| ||String||An identifier for the workspace of the current job. This identifier is the same for every job in a given workflow.|
| ||String||The value of the |
| ||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.|
| ||String||Deprecated. The GitHub or Bitbucket URL to compare commits of a build. Available in config v2 and below. For v2.1 we will introduce “pipeline values” as an alternative.|
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.
| ||String||A globally unique id representing for the pipeline|
| ||Integer||A project unique integer id for the pipeline|
| ||String||The URL where the current project is hosted. For example, |
| ||String||The lower-case name of the VCS provider, E.g. “github”, “bitbucket”.|
| ||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.|
| ||String||The name of the git branch that was pushed to trigger the pipeline.|
| ||String||The long (40-character) git SHA that is being built.|
| ||String||The long (40-character) git SHA of the build prior to the one being built. Note: While in most cases |
| ||Boolean||True if the pipeline is in the setup phase, i.e. running a setup workflow.|
| ||String||The source that triggers the pipeline, current values are |
| ||String||The name of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggerd by other sources|
| ||String||The unique id of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggerd by other sources|
version: 2.1 jobs: build: docker: - image: cimg/node:latest auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference 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
Note: 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.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.