Container Registry, Package Registry, Generic Packages, Dependency Proxy, and Artifact Promotion: Configuration, Design Choices, and Tradeoffs

1. Design problem: distribution policy is part of delivery architecture

Once multiple teams consume artifacts, registry choices affect blast radius, rollback speed, auditability, storage cost, and developer experience. The right question is not “which registry feature is richest?” It is “which identity, authentication, lifecycle, and evidence model keeps the verified bytes reproducible across teams?”

Before comparing designs, preserve the producer identity: CI_PIPELINE_SOURCE, exact CI_COMMIT_SHA, pipeline/job IDs, and the published package checksum or image digest. Design decisions are valid only if they keep that evidence chain intact.

2. Job token versus deploy token

For CI, start with the job token. For a non-CI consumer, a narrowly scoped deploy token may be appropriate. Never choose a credential merely because it “makes 403 go away.”

3. Tag versus digest/version

4. Rebuild per environment versus promote the same bytes

Rebuilding in test, staging, and production produces three artifact identities even if the source SHA is the same. Toolchain timing, dependency resolution, base image drift, timestamps, or nondeterministic compilation can change the bytes. Promotion should preserve the object identity and only change eligibility or a human-facing pointer.

flowchart LR
  A[Build once from source SHA] --> B[Digest/checksum]
  B --> C[Test consumes exact identity]
  C --> D[Approval / policy]
  D --> E[Staging points to same identity]
  E --> F[Approval / policy]
  F --> G[Production points to same identity]
  G --> H[Independent health check]

5. GitLab registry versus external repository manager

6. Protection and immutability are different controls

Protected packages and protected container tags restrict who can push/delete matching identities. Current protected container tags are Free and can define up to five rules per project; protected tags are excluded from cleanup policies. Container tag immutability goes further: once a matching tag exists, it cannot be updated or deleted. Current GitLab documents container tag immutability as Ultimate, so the mandatory course path never depends on it.

Generic Packages have their own duplicate behavior: duplicate files are allowed by default and can be restricted at group settings. Therefore, your immutable contract should still include exact version + checksum even when governance rules exist.

7. Retention: storage control must preserve rollback evidence

Container cleanup policies select tags by name/age while always preserving latest and excluding protected/immutable tags. Deleting tags does not necessarily reclaim underlying layers immediately; registry garbage collection/online GC behavior is a separate storage layer. Package cleanup likewise has package/asset rules. Start with narrow policies and inspect what will remain before relying on cleanup for cost control.

8. Worked scenario: choose a design

A team builds a CLI once, tests it in CI, deploys it to staging and production, and also publishes a container wrapper. Production must be reproducible; a legacy external host needs read-only download access.

9. Tier/offering assumptions

• Generic Packages, Package Registry, Container Registry, Dependency Proxy, protected packages, and protected container tags are available across Free/Premium/Ultimate in current docs.
• Container tag immutability is currently documented as Ultimate.
• Self-Managed registry capabilities can depend on using the newer container registry/metadata database.
• Cross-project job-token access remains authorization-sensitive even when the feature itself is Free.

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. The design lesson treats GitLab feature availability as a runtime assumption to record, because Self-Managed registry backend/version configuration can affect which protection and cleanup capabilities are actually usable.

• 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.