Chapter 23Lesson 03~295 minutes

Container Registry, OCI Images, Cleanup, Authentication, Vulnerability Scanning, and Retention: Configuration, Design Choices, and Tradeoffs

Choose tag and digest policy, CI versus deploy-token identity, integrated versus external registry, and cleanup/retention rules from reproducibility, rollback, security, reliability, performance, and cost requirements.

ArchitectureDigest pinningCredentialsRetentionExternal registryTradeoffs

Learning objectives

Choose digest/tag policy from reproducibility and human usability requirements.
Select CI credentials or deploy tokens from actor lifetime and privilege needs.
Design retention around deployed/rollback references rather than tag recency alone.
Evaluate integrated GitLab Registry versus an external OCI registry.
Use protection/immutability controls only within their current tier/offering boundaries.

Availability baseline (verified 2026-08-22 against current GitLab 19.3 documentation). The integrated Container Registry is Free/Premium/Ultimate on GitLab.com, Self-Managed, and Dedicated; Self-Managed administrators must enable and operate it. Registry authentication supports job-scoped CI credentials and token credentials with registry scopes. Cleanup policies are Free across all three offerings. Container scanning is Free/Premium/Ultimate, but some vulnerability-management presentation/governance capabilities vary by tier. Protected container repositories are Free across all three offerings. Protected container tags are Free on GitLab.com and Self-Managed with the current registry backend prerequisites. Immutable container tags are Ultimate-only on GitLab.com/Self-Managed. The mandatory labs therefore require neither Ultimate nor Self-Managed administration, privileged runners, cloud spend, nor a persistent registry credential.

1. Start from invariants, not favorite tools

Registry architecture should preserve a few invariants: every production image has an exact digest; the producer and consumer identities are least-privilege; the source/pipeline relationship is recoverable; cleanup cannot destroy required rollback state; and security reports refer to the same image identity that is deployed.

Those invariants help choose between tags/digests, CI/deploy tokens, integrated/external registries, and aggressive/conservative retention.

2. Mutable tags versus digest pinning

Choice	Strength	Cost / caveat
Deploy by mutable tag	Human-readable and simple.	Same tag can resolve to new content; weak incident/rollback evidence.
Release tag + digest record	Readable release plus independently verifiable content.	Automation must persist and compare digest.
Deploy directly by digest	Strong content identity.	Humans need metadata to map digest back to release/source.
Immutable tag policy	Prevents matched tag mutation.	Current GitLab capability is Ultimate-only and does not replace digest provenance.

Recommended production pattern: keep useful semantic/commit tags, but make deployment evidence digest-based.

3. CI job identity versus deploy token

Use job-scoped registry credentials when publication happens inside the producing pipeline. They disappear with the job and align with pipeline provenance. Use a deploy token when an external long-lived system must pull images and cannot use a job token or federated identity. Give pull-only consumers only read_registry.

Question	CI registry credentials	Deploy token
Lifetime	One job.	Persistent until expiry/revocation.
Best actor	Pipeline producer/consumer.	External machine/service.
Push capability	Available to current project job identity.	Only if token has `write_registry` + `read_registry`.
Revocation burden	Ends automatically with job.	Operational inventory and rotation required.
Secret distribution	Runner job environment.	Must be delivered to external system securely.

4. Integrated GitLab Registry versus external OCI registry

The integrated registry wins when project authorization, CI variables, GitLab metadata/UI/API, cleanup policy, and source-to-image traceability are valuable. An external registry may win for global replication, established enterprise artifact governance, cloud-native runtime integration, specialized signing/policy, or multi-SCM consumers.

Dimension	GitLab integrated	External registry
Authorization	GitLab project/group roles and registry scopes.	Provider-specific IAM/policy.
CI integration	Native `CI_REGISTRY*` variables.	External auth bootstrap required.
Provenance navigation	Close to project/pipeline.	Must build cross-system evidence links.
Operations	GitLab.com/Dedicated managed; Self-Managed customer-operated.	Registry/provider-specific.
Portability	GitLab-centered.	Potentially easier for heterogeneous SCM/CD fleets.

5. Aggressive cleanup versus rollback/reproducibility

Cleanup is safe only after classifying image value. Short-lived branch images can expire quickly; release digests need a retention window aligned to deployment rollback, incident investigation, compliance, and disaster recovery. “Keep the newest N tags” alone is not a rollback policy if production can still run an older digest.

Write retention in terms of deployment references and evidence, then express a conservative cleanup regex/age policy around that.

6. Repository protection, protected tags, and immutability answer different governance questions

Control	Question answered	Current boundary
Protected repository	Who may push to this repository path?	Free; current docs cover GitLab.com, Self-Managed, Dedicated.
Protected container tag	Who may push/delete matching tags?	Free; current docs cover GitLab.com and Self-Managed with registry backend prerequisites.
Immutable tag	Can anyone update/delete a matching existing tag?	Ultimate; GitLab.com/Self-Managed; GA since GitLab 18.10.
Digest pinning	What exact OCI manifest is this?	OCI/client behavior; no paid GitLab feature required.

7. Scan timing: build-time feedback versus continuous registry posture

Pipeline container scanning gives release feedback at a specific source/pipeline moment. Registry-oriented continuous scanning can detect newly disclosed vulnerabilities later, but availability/governance differs. Even with continuous scanning, deployment identity must remain digest-based so a new finding can be mapped to the running image.

Do not use “no findings at build time” as an indefinite approval.

8. Multi-platform images require one more identity decision

An OCI image index can reference separate linux/amd64 and linux/arm64 manifests. If your runtime pins the index digest, preserve that. If a platform resolver selects a child manifest, record the platform and selected digest as deployment evidence when operationally important. A scan can also target a specific platform; current GitLab container scanning supports a platform selection variable.

9. Worked scenario: payment API with 30-day rollback objective

Requirements: every merge builds a test image; production releases weekly; rollback must work for 30 days; external Kubernetes pulls images; no paid GitLab control may be mandatory.

Decision	Choice	Reason
Image naming	`api:$CI_COMMIT_SHA` plus `vX.Y.Z`.	Source and human release mapping.
Production deployment	Digest captured from release tag.	Tag movement cannot change selected content.
Publisher identity	CI registry credentials.	Short-lived, pipeline-bound.
Runtime credential	Read-only deploy token or external workload identity.	No registry write capability.
Retention	Keep production-referenced releases ≥30 days + incident hold.	Matches rollback objective.
Cleanup	Expire unreferenced branch tags after conservative age; keep releases.	Reduces storage without breaking rollback.
Scanning	Pipeline scan + preserved report/digest mapping.	Free-compatible release evidence.

10. Cost/performance reasoning belongs after correctness

Registry storage, egress, build cache, multi-platform layers, repeated scanning, and retention all cost resources. Optimize by deduplicating layers, keeping only useful tags, using cleanup policies, and avoiding redundant rebuilds—but never by deleting the evidence/digests required for deployed releases. Volatile GitLab.com storage quotas/pricing are intentionally not hardcoded; check current subscription/admin data at implementation time.

Knowledge check

When is a deploy token better than CI registry credentials?

Why is “keep latest 10 tags” not enough for rollback?

Which control is Free-compatible even when immutable tags are not?

Why might an external registry be reasonable despite weaker GitLab integration?

What should multi-architecture evidence record?

Summary

Production registry design balances human-friendly tags with digest truth, ephemeral producers with durable consumers, rollback retention with storage cost, and integrated convenience with external-registry requirements. These are policy choices around explicit invariants, not syntax preferences.

Official references

Primary sources used for the current GitLab 19.3 behavior taught in this lesson:

Next lesson

Diagnostics, Failure Modes, Security, and Performance

Use preserved registry, pipeline, digest, auth, scan, and storage evidence to repair real failure modes without hiding their cause.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.