3.2.2.5 Build Number Image Tags

Build number image tags use a sequential identifier assigned by a CI/CD system to tag each image it produces, providing a simple, automatically incrementing way to distinguish builds without relying on either semantic versioning decisions or commit hashes.

Tagging by an Incrementing Build Number

Most CI systems expose a build number as an environment variable automatically, available to be used directly as part of an image tag without any additional bookkeeping.

docker build -t registry.example.com/myapp:build-$CI_BUILD_NUMBER .
docker push registry.example.com/myapp:build-$CI_BUILD_NUMBER

Every pipeline run produces a uniquely numbered image, with the CI system itself responsible for ensuring numbers never repeat.

Why Build Numbers Are Convenient

Because the CI system assigns build numbers automatically and monotonically, this tagging scheme requires no manual decision-making and guarantees uniqueness without any risk of collision between concurrent or rapid builds.

docker pull registry.example.com/myapp:build-4821

Build Numbers Provide Sequencing but Not Meaning

A build number reveals the relative order in which images were produced, but says nothing about the nature of the change between one build and the next, unlike semantic versioning, which is why build numbers are often paired with other tagging schemes for releases meant to be understood by people outside the immediate build pipeline.

docker tag myapp:build-4821 myapp:2.3.1

Build Numbers for Intermediate and Pre-Release Builds

Build-number tagging is particularly common for intermediate builds — pull request previews, nightly builds, pre-release candidates — where uniquely identifying every build matters more than communicating semantic meaning about each one.

docker push registry.example.com/myapp:pr-142-build-57

Why Build Number Tagging Matters

Build number tags are a low-effort, automatic way to ensure every single build produced by a CI/CD pipeline has a distinct, traceable identity, which is particularly useful during active development when many builds are produced in quick succession and a full semantic versioning decision for each one would be unnecessary overhead.