Step 01 of 06
Learn the concept
An image without metadata is a jar with the label washed off. It may run perfectly, but six weeks later nobody knows which commit produced it, when it was built, or where the source lives. OCI annotations turn that archaeology into one docker image inspect.
The ideas this is made of
Labels are metadata, not filesystem files
A Docker LABEL instruction writes key-value data into the image configuration. It does not create /labels.txt and it does not change how Beacon runs. The OCI keys are conventional names other tools understand: source repository, revision, creation time, licences, title, and description. They make inspection cheap and automation boring.
Build args are inputs, not secrets
ARG VCS_REF lets docker build --build-arg VCS_REF=$(git rev-parse HEAD) stamp the commit. Build args can appear in image history and metadata, so never pass tokens through them. They are excellent for public facts: version, source URL, created timestamp, and revision.
Reproducibility removes accidental time travel
Two builds from the same commit should be as similar as the toolchain allows. SOURCE_DATE_EPOCH gives tools a stable timestamp instead of wall-clock time. Go also needs flags such as -trimpath and controlled version variables. Perfect reproducibility is hard; knowing which inputs break it is already a professional step up.
Latest is a nickname with no memory
beacon:latest can point to one image at noon and another at 12:05. Nothing in the tag name records the change. A digest such as sha256:... is computed from content and changes when the content changes. Deployments that need repeatability pin digests and use labels to explain them.
docker image inspect beacon:meta --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'The label is retrieved from image configuration, not from inside the container. You do not need to start Beacon to ask where the image came from.
Names and identities
| Reference | Can change? | Use it for |
|---|---|---|
| Yes | Local convenience only |
| Technically yes | Human release name |
Immutable tag | Policy says no | Registry workflow |
Digest | No | Deployment identity |
What these are called on the job
OCI annotation — A standard image metadata key such as
org.opencontainers.image.source.Digest — A content hash identifying image bytes, commonly
sha256:....Build arg — A Dockerfile input supplied at build time with
--build-arg.