CircleCI环境变量CIRCLE_SHA1的含义及设置方法咨询

Hey there! Let’s break down what CIRCLE_SHA1 does in CircleCI and how you can work with it.

What is CIRCLE_SHA1? #

CIRCLE_SHA1 is an automatically populated environment variable in CircleCI that holds the SHA-1 hash of the Git commit currently being built or tested.

Every Git commit has a unique SHA-1 hash, so this variable acts as a unique identifier linking your CircleCI build directly to the exact code revision it’s running against. You’ll often see it used for things like:

• Tagging Docker images with the commit hash for traceability
• Generating versioned artifacts tied to a specific code snapshot
• Logging or debugging to quickly map a build back to corresponding code changes

For example, you might use it in a build step like this:

docker build -t my-app-image:$CIRCLE_SHA1 .

Can You Set or Override CIRCLE_SHA1? #

By default, CircleCI injects this variable automatically—you don’t need to do anything to get it. But if you have a specific use case (like testing a build workflow against a different commit, or simulating a scenario), you can override it in a few ways:

• Project-level environment variables:
  Head to your CircleCI project settings, navigate to the "Environment Variables" section, and add a new variable named CIRCLE_SHA1 with your desired SHA value. This will override the default auto-populated value for all builds of the project.

• In your .circleci/config.yml:
  You can set it globally for a job, or temporarily within a single step:

  jobs:
    test-custom-sha:
      docker:
        - image: cimg/node:20
      # Set for the entire job
      environment:
        CIRCLE_SHA1: "a1b2c3d4e5f6g7h8i9j0"
      steps:
        - checkout
        - run: echo "Using custom SHA: $CIRCLE_SHA1"
        # Or override just for this step
        - run:
            command: |
              export CIRCLE_SHA1="z9y8x7w6v5u4t3s2r1q0"
              echo "Temporary SHA: $CIRCLE_SHA1"
  

• Via CircleCI API:
  If you trigger builds programmatically using the CircleCI API, you can include environment_variables in your request body to override CIRCLE_SHA1. This is mostly useful for automated testing or integration scenarios.

A Quick Note #

Unless you’re debugging, testing a specific workflow, or have a very niche use case, it’s best to leave CIRCLE_SHA1 as the auto-populated value. Overriding it can break the link between your build and the actual code commit, making it harder to trace issues back to specific changes later on.

内容的提问来源于stack exchange，提问作者newbie