Choosing a value for <BUILD NAME>

Instructions for choosing a value for <BUILD NAME> when recording builds depending on your CI system and setup.

Your CI process probably already relies on some identifier to distinguish different builds. Such an identifier might be called a build number, build ID, etc. Most CI systems automatically make these values available via built-in environment variables. This makes it easy to pass this value into record build:

CI system Suggested <BUILD NAME> value Documentation
Azure DevOps Pipelines Build.BuildId Link
Bitbucket Pipelines BITBUCKET_BUILD_NUMBER Link
GitHub Actions GITHUB_RUN_ID Link
GitLab CI CI_JOB_ID Link
Jenkins BUILD_TAG Link

Other examples:

  • If your build produces an artifact or file that is later retrieved for testing, then the sha1sum of the file itself would be a good build name as it is unique.

  • If you are building a Docker image, its content hash can be used as the unique identifier of a build: docker inspect -f "{{.Id}}".

If you only have one source code repository, it might tempting to use a Git commit hash (or the output of git-describe) as the build name, but we discourage this.

It's not uncommon for teams to produce multiple builds from the same commit that are still considered different builds.