Docs
circleci.com
Start Building for Free

Project values and variables

3 months ago3 min read
Cloud
Server v3.x
Server v2.x
On This Page
  • Built-in environment variables
  • Pipeline values

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.

VariableTypeValue
CIBooleantrue (represents whether the current environment is a CI environment)
CIRCLECIBooleantrue (represents whether the current environment is a CircleCI environment)
CIRCLE_BRANCHStringThe name of the Git branch currently being built.
CIRCLE_BUILD_NUMIntegerThe number of the current job. Job numbers are unique for each job.
CIRCLE_BUILD_URLStringThe URL for the current job on CircleCI.
CIRCLE_JOBStringThe name of the current job.
CIRCLE_NODE_INDEXIntegerFor 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_TOTALIntegerFor 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_TOKENStringAn OpenID Connect token signed by CircleCI which includes details about the current job. Available in jobs that use a context.
CIRCLE_PR_NUMBERIntegerThe number of the associated GitHub or Bitbucket pull request. Only available on forked PRs.
CIRCLE_PR_REPONAMEStringThe name of the GitHub or Bitbucket repository where the pull request was created. Only available on forked PRs.
CIRCLE_PR_USERNAMEStringThe GitHub or Bitbucket username of the user who created the pull request. Only available on forked PRs.
CIRCLE_PREVIOUS_BUILD_NUMIntegerThe 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.
CIRCLE_PROJECT_REPONAMEStringThe name of the repository of the current project.
CIRCLE_PROJECT_USERNAMEStringThe GitHub or Bitbucket username of the current project.
CIRCLE_PULL_REQUESTStringThe URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen.
CIRCLE_PULL_REQUESTSListComma-separated list of URLs of the current build’s associated pull requests.
CIRCLE_REPOSITORY_URLStringThe URL of your GitHub or Bitbucket repository.
CIRCLE_SHA1StringThe SHA1 hash of the last commit of the current build.
CIRCLE_TAGStringThe name of the git tag, if the current build is tagged. For more information, see the Git Tag Job Execution.
CIRCLE_USERNAMEStringThe GitHub or Bitbucket username of the user who triggered the pipeline (only if the user has a CircleCI account).
CIRCLE_WORKFLOW_IDStringA 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_IDStringA unique identifier for the current job.
CIRCLE_WORKFLOW_WORKSPACE_IDStringAn identifier for the workspace of the current job. This identifier is the same for every job in a given workflow.
CIRCLE_WORKING_DIRECTORYStringThe value of the working_directory key of the current job.
CIRCLE_INTERNAL_TASK_DATAStringInternal. 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.

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.

VariableTypeValue
pipeline.idStringA globally unique id representing for the pipeline
pipeline.numberIntegerA project unique integer id for the pipeline
pipeline.project.git_urlStringThe URL where the current project is hosted. For example, https://github.com/circleci/circleci-docs
pipeline.project.typeStringThe lower-case name of the VCS provider, E.g. “github”, “bitbucket”.
pipeline.git.tagStringThe 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.branchStringThe name of the git branch that was pushed to trigger the pipeline.
pipeline.git.revisionStringThe long (40-character) git SHA that is being built.
pipeline.git.base_revisionStringThe 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.in_setupBooleanTrue if the pipeline is in the setup phase, i.e. running a setup workflow.
pipeline.trigger_sourceStringThe source that triggers the pipeline, current values are webhook, api, scheduled_pipeline
pipeline.schedule.nameStringThe name of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggerd by other sources
pipeline.schedule.idStringThe unique id of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggerd by other sources

For example:

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.

Need support?

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.