13.2.1.1 Dev Promotion Tags

Dev promotion tags mark an image as having reached, or being intended for, the development stage of a promotion flow, providing a clear, human-readable indicator alongside the image's precise, immutable commit-based tag.

Applying a Dev-Specific Tag

A development-stage tag is applied immediately after a successful build, alongside the more precise SHA-based tag.

docker build -t registry.example.com/myapp:${{ github.sha }} .
docker tag registry.example.com/myapp:${{ github.sha }} registry.example.com/myapp:dev
docker push registry.example.com/myapp:${{ github.sha }}
docker push registry.example.com/myapp:dev

This dev tag provides a convenient, human-readable reference to the most recent build intended for the development environment, while the SHA-based tag retains a precise, immutable link to the exact source commit.

Why a Floating Tag Like dev Should Move Deliberately

Since dev is a mutable, floating tag — it can be reassigned to point at a different image over time — it should only move as part of an explicit, intentional promotion step, not by accident or through an unrelated build.

docker tag registry.example.com/myapp:${{ github.sha }} registry.example.com/myapp:dev

This deliberate re-tagging step is what actually moves the dev tag forward, rather than it changing implicitly as a side effect of something else.

Using This Tag to Trigger a Development Environment Deployment

A development environment's deployment process can specifically watch for updates to this tag, automatically deploying whatever image it currently points to.

docker pull registry.example.com/myapp:dev
docker compose -f docker-compose.dev.yml up -d

Why Dev Promotion Tags Matter

A clearly named, deliberately managed tag for the development stage provides a convenient, consistent reference point for that environment's deployment process, while the underlying SHA-based tag preserves the precise traceability needed to know exactly what source code that image actually represents.