Ask an engineer what is running in production and you will usually get a tag. Ask which commit produced it and the answer takes longer, and is sometimes wrong.
That gap is what this cluster closes. A container image is an artifact; a Git commit is a point in history. They are related only by whatever identity somebody deliberately recorded at build time — and if nobody did, the relationship exists in a CI log that expired ninety days ago.
Start with the Docker + Git workflowWhat this cluster answers
Section titled “What this cluster answers”The chain
Section titled “The chain”A vertical sequence: a Git commit; the Dockerfile it contains; a CI build; a container image identified by digest; a registry; and a deployment referencing that digest.
Two identities appear in that chain and they answer different questions.
A Git SHA answers “what source produced this?” It is a commit. It says nothing about how the build ran, what base image was current that day, or whether the same command would produce the same bytes tomorrow.
An image digest answers “what content is this exactly?” It is a content hash over the image. It says nothing about where the source came from.
You need both, and you need something connecting them — an OCI label, an attestation, or both. Git SHA container images is the lesson that works through why one is not a substitute for the other, and it is short because the idea is narrow and important.
The organising idea
Section titled “The organising idea”Tags are pointers. Digests are content.
A tag can be moved. myapp:1.2.3 today and myapp:1.2.3 next week can be different images, because nothing in the container ecosystem prevents a tag from being reassigned. A digest cannot be moved: sha256:abc… is that image or it is nothing.
That single fact reorganises most container workflow decisions:
Tags are for humans and for discovery. latest, v1.2.3, main — useful for finding an image, unsuitable as a production reference on their own.
Digests are for deployment and promotion. What staging tested and what production runs should be the same digest, not the same tag pointing at two different builds.
Both belong in the workflow, and image tagging with Git covers building a tagging scheme that gives you human-readable discovery without letting mutability into the deployment path.
What is worth version controlling
Section titled “What is worth version controlling”The repository holds the instructions for producing an artifact, not the artifact.
| In Git | Not in Git |
|---|---|
Dockerfile | The built image |
.dockerignore | Registry credentials |
compose.yaml | .env with real values |
| Build scripts and CI workflows | Layer caches |
| Pinned base image digests | Anything the build downloads |
| Example env files with placeholders | Secrets, in any encoding |
Version controlling Dockerfiles and Docker Compose with Git cover the boundary in detail, including the case that produces most accidental secret commits: an .env file that started as an example and acquired real values.
Reproducibility, honestly
Section titled “Reproducibility, honestly”Container builds are more reproducible than they used to be and less reproducible than people claim.
What pinning a base image digest gets you: the same starting layers, every time. This is real and worth doing.
What it does not get you: byte-identical images. Package managers resolve versions at build time, timestamps get embedded, and layer ordering can vary. FROM node:22 and FROM node@sha256:… are meaningfully different in reliability; neither makes your build deterministic on its own.
What actually establishes what happened: provenance. Recording the source commit, the build parameters and the resulting digest, ideally as a signed attestation. That is the difference between believing an image came from a commit and being able to demonstrate it.
The questions this cluster settles
Section titled “The questions this cluster settles”Should the Dockerfile live with the application or in a separate repository? Almost always with the application, and Dockerfile version control explains the cases where that stops being true — and why a “docker repository” holding everyone’s Dockerfiles is a coordination bottleneck rather than an organisation.
Do we pin base images by tag or digest? Both, and in a specific way: a digest for reproducibility, with the tag recorded in a comment so a human can see what it was and automation can offer an upgrade.
What goes in the tag? Usually several things at once — a semantic version for humans, a commit SHA for traceability, and a latest-style pointer if you genuinely need one. Image tagging has the decision table.
Does production reference a tag or a digest? A digest. The tag is how a human found it; the digest is what gets deployed.
How does an image get promoted between environments? By moving the digest reference in a repository, through a pull request. Not by rebuilding. Docker release workflow covers the release-tag path, and Kubernetes environment promotion covers what happens after.
Who is allowed to push? CI, on merge. Not engineers from laptops — a locally built image has no reviewable provenance and typically no attestation.
How do we build for both amd64 and arm64 without doubling the release process? Multi-architecture builds, including the honest performance discussion about emulation.
Compose is not a deployment tool
Section titled “Compose is not a deployment tool”Worth stating on the hub because the confusion is common and costly.
compose.yaml describes a set of services for a single host. It is excellent for local development environments, integration tests in CI, and small single-machine deployments. It is not an orchestrator, has no scheduling, no rolling update semantics and no reconciliation.
Teams that outgrow it usually do so without noticing, and the symptom is a Compose file accumulating environment-specific overrides, deploy-time shell scripts and manual steps. Docker Compose with Git covers keeping the file useful for what it is good at, and recognising the point at which the answer is Kubernetes instead.
Where this cluster sits
Section titled “Where this cluster sits”Pillar 4 owns the workflow files — building and publishing images from Actions.
Pillar 5 owns the security depth — signing images, attestations, SBOMs.
This cluster owns the identity and versioning decisions those two are implementing: what gets tagged, what gets promoted, what a deployment should reference, and how a running container traces back to a line of code.