Project challenges / verified progress
Beacon: package it so anyone can run it

The engineering notebook

Publish by digest

What really happens when an image is pushed to a registry?

Loading Vault account...
Phase 3 — Publish, inspect, prove

Step 01 of 06

Understand the idea

A container registry stores images so computers can download them. A tag such as dev is a name that can point to a different image after another push. You will publish and retrieve an image, then learn how to identify its exact contents.

ONE PUSH TWO REFERENCESbeacon imagemanifest and layersTagregistry.gitlab.com/me/beacon:v1can moveDigestsha256 content hashfixedRepositoryaccess and packagesGitLab Container Registry
The registry stores content once and lets references point at it. Tags make humans productive. Digests make machines repeatable. Use the right one in the right sentence.
Step 01

Key technical ideas

A repository is a namespace inside a registry

registry.gitlab.com/thesyscoder/beacon names the registry host, owner namespace, and package repository. Inside it, tags point to manifests, and manifests point to layer blobs. Pushing another image with the same tag changes the tag reference. The old blobs may still exist, but new pulls by tag no longer ask for them.

Login grants push rights, not moral authority

For a local push, create a GitLab personal access token with only read_registry and write_registry scopes. Store it in a local environment variable. Docker stores credentials in your credential helper. Never paste a token into a Dockerfile, compose file, or shell history. Pipe it to docker login --password-stdin so it is not visible in process arguments.

Pull by digest when repeatability matters

docker pull registry.gitlab.com/me/beacon@sha256:... asks for a specific manifest by content hash. If someone moves v1.0.0, the digest pull is unchanged. CI can build and push tags for discovery, but deployment records should include the digest. The tag is a label on the box. The digest is the box.

Immutable tags are policy, not physics

Some registries can refuse overwriting a tag. That is useful, but it is a server-side rule, not part of the tag itself. A different registry, repository, or permission mistake can still move names unless policy is enabled. Digest pinning remains the portable verification habit.

Logging in without exposing the token
export GITLAB_USERNAME="YOUR_GITLAB_USERNAME"
read -s GITLAB_TOKEN
printf '%s' "$GITLAB_TOKEN" | docker login registry.gitlab.com -u "$GITLAB_USERNAME" --password-stdin
unset GITLAB_TOKEN

docker tag beacon:meta registry.gitlab.com/YOUR_GITLAB_USERNAME/beacon:dev
docker push registry.gitlab.com/YOUR_GITLAB_USERNAME/beacon:dev

Create a token with read_registry and write_registry scopes on GitLab. Set the project registry visibility to public only if you want anonymous pulls; storage and transfer limits depend on your GitLab plan.

Tag and digest behaviour

ReferenceMutableBest use

main

Yes

Latest CI build for humans

v1.4.0

Maybe

Release discovery

Immutable tag

Registry blocks change

Release policy

@sha256:...

No

Deployments and rollbacks

Technical terms used at work

  • Registry — A server that stores OCI image manifests and blobs, such as registry.gitlab.com.

  • Repository — A named package collection inside a registry, such as owner/beacon.

  • Manifest — The JSON document that lists config and layer digests for an image.