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.
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.
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:devCreate 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
| Reference | Mutable | Best use |
|---|---|---|
| Yes | Latest CI build for humans |
| Maybe | Release discovery |
Immutable tag | Registry blocks change | Release policy |
| 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.
