Container Registry, Package Registry, Generic Packages, Dependency Proxy, and Artifact Promotion: Concepts, Architecture, and Mental Model

1. The practical problem: a green build does not make an artifact safely distributable

Chapter 22 bound a release record to an exact tag, source SHA, and verified artifact digest. Chapter 23 asks where those bytes should live so downstream pipelines and environments can retrieve them repeatedly without rebuilding. A CI artifact is excellent pipeline evidence, but it may expire. A registry or package repository gives the object a durable coordinate, authentication boundary, metadata, and lifecycle policy.

The failure mode is subtle: teams often publish only latest, rebuild separately for staging and production, or trust a proxy cache as if it proves origin. Those patterns break the chain from tested bytes to deployed bytes.

2. Terms before commands

3. State model: distribution adds a durable identity layer

4. Mental model: build once, publish once, consume by immutable identity

A producer job starts from an exact source SHA and creates bytes. Before publication it computes a checksum. Authentication authorizes publication to one package path or image repository. The registry assigns durable metadata: package name/version/file checksum or image manifest digest. Downstream consumers retrieve that exact identity and verify it. Promotion changes which environment or policy points at the object; it should not invoke a second build.

flowchart LR
  A[Source SHA + producer pipeline] --> B[Build bytes once]
  B --> C[Authenticate to registry]
  C --> D[Publish version/tag]
  D --> E[Record checksum or manifest digest]
  E --> F[Consumer pulls immutable identity]
  F --> G[Promotion reference]
  G --> H[Retention / protected cleanup]
  H --> I[Deployment and health verified separately]

5. Generic Packages: explicit coordinates and stored checksums

A Generic Package file is addressed by project, package name, package version, and file name. GitLab accepts CI_JOB_TOKEN for CI automation and stores checksums for uploaded files. That makes Generic Packages a useful mandatory lab path because it needs no privileged container daemon.

PACKAGE_NAME="glci-ch23-demo"
PACKAGE_VERSION="0.0.0-${CI_PIPELINE_ID}"
FILE="dist/payload.txt"
sha256sum "$FILE" | tee evidence/payload.sha256

curl --fail --location \
  --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  --upload-file "$FILE" \
  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${PACKAGE_VERSION}/payload.txt"

6. Container images: tag for humans, digest for machines

A container tag such as 1.4.0 or main is a mutable reference unless stronger controls prevent updates. After push, capture the registry manifest digest and use repository@sha256:… for deployment/promotion evidence. Do not confuse a local Docker image ID with the registry manifest digest.

7. Authentication is part of provenance

Within the same project, CI provides CI_REGISTRY_USER/CI_REGISTRY_PASSWORD for container-registry push/pull and CI_JOB_TOKEN for package APIs. For external systems, deploy tokens can use narrow read_registry, write_registry, read_package_registry, or write_package_registry scopes. Cross-project job-token access adds two gates: the target project allowlist and the permissions of the user who started the job.

8. Dependency Proxy: availability optimization, not provenance

The Dependency Proxy is group-level and acts as a pull-through cache for Docker Hub images. In CI, GitLab supplies dependency-proxy variables and can authenticate automatically. If a Docker Hub tag moves, the proxy still does not transform that tag into trusted provenance. Reproducible consumption needs a verified upstream digest and appropriate source trust.

9. Read-only inspection first

printf 'source=%s ref=%s sha=%s pipeline=%s job=%s\n' \
  "$CI_PIPELINE_SOURCE" "$CI_COMMIT_REF_NAME" "$CI_COMMIT_SHA" \
  "$CI_PIPELINE_ID" "$CI_JOB_ID"

printf 'registry=%s image=%s project=%s\n' \
  "$CI_REGISTRY" "$CI_REGISTRY_IMAGE" "$CI_PROJECT_PATH"

# Inspect package/download coordinates; never dump the token itself.
printf 'package=%s version=%s\n' "$PACKAGE_NAME" "$PACKAGE_VERSION"

10. Common mistakes and safer patterns

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. Generic Packages, Package Registry, Container Registry, Dependency Proxy, protected packages, and protected container tags are documented for Free/Premium/Ultimate unless noted otherwise. Current immutable container-tag rules are Ultimate-only. Dependency Proxy is group-level and supports Docker Hub images. Current protected-container-tag rules are Free and protected tags are excluded from container cleanup policies. Container tag immutability is an Ultimate feature, so the chapter teaches digest pinning as the mandatory portable path.

• Package registry — official reference.
• Generic packages — official reference.
• Supported package functionality — official reference.
• Protected packages — official reference.
• Reduce package registry storage — official reference.
• Container registry — official reference.
• Container registry authentication — official reference.
• Protected container tags — official reference.
• Immutable container tags — official reference.
• Reduce container registry storage — official reference.
• Dependency Proxy — official reference.
• CI job token — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.