Container Registry, OCI Images, Cleanup, Authentication, Vulnerability Scanning, and Retention: Concepts, Architecture, and Mental Model

1. The practical problem: “image:latest” is not a release identity

Chapter 22 treated packages as governed distribution objects. Container images are also release artifacts, but OCI adds another layer of indirection: a human-friendly tag points to a manifest, while a content-addressed digest identifies exact manifest bytes. If a deployment records only service:latest, the same text can resolve to different content tomorrow.

This chapter therefore treats the registry as production state. The useful question is not “did we push an image?” but “which project repository owns it, which manifest digest was produced, what source and pipeline created it, who may mutate its tags, what scan evidence belongs to that digest, and what retention rule keeps rollback possible?”

2. Registry object model: project → repository → manifest → tag/digest

Layers may be shared across manifests, so repository/tag deletion and physical storage reclamation are not the same operation.

3. Mental model: source and pipeline create a registry object; deployment consumes a digest

flowchart TD
  G[Git commit / ref] --> P[Pipeline + build job]
  P -->|CI_REGISTRY_USER + short-lived password| R[Project Container Registry]
  R --> T[Tag: commit-abc123]
  T --> D[Manifest digest sha256:...]
  D --> S[Container scan report]
  D --> E[Deployment / runtime]
  C[Cleanup + protection policy] --> T
  A[Self-Managed storage + GC] --> R

4. OCI identity: tag equality is weaker than digest equality

An OCI reference may be written as registry.example.invalid/group/project/api:v1 or as registry.example.invalid/group/project/api@sha256:<digest>. The first asks the registry what v1 points to at request time. The second names the manifest content directly.

registry.example.invalid/platform/payments/api:v1.4.0
registry.example.invalid/platform/payments/api@sha256:0123456789abcdef...

A platform-specific image can have one digest while a multi-architecture index has another. Record which digest your deployment mechanism resolves and uses; do not compare unrelated manifest and platform-manifest digests as if they were the same object.

5. Authentication is short-lived; authorization is registry-scope plus project permission

Current registry token methods include personal, project, group, and deploy tokens. For token-based access, pull requires read_registry; push requires both read_registry and write_registry. In CI, GitLab exposes CI_REGISTRY_USER and CI_REGISTRY_PASSWORD; the password is job-only, has the same value as CI_JOB_TOKEN, and expires with the job.

Use --password-stdin; do not place a registry password on a command line, in source, or in a trace artifact.

6. Read-only inspection comes before publish or delete

Prove the project registry is enabled and inspect current repositories before changing anything:

git rev-parse HEAD
glab container-registry repository list --output json
# For a known repository ID:
glab container-registry repository view <repository-id> --include-tags --output json
glab container-registry tag list <repository-id> --details --output json

The current glab container-registry commands operate against GitLab’s registry metadata API. Detailed tag listing adds digest, size, and creation data. Record project, repository ID/path, tag, digest, commit SHA, and pipeline ID together.

7. Cleanup policy removes tags; storage reclamation is a separate layer

GitLab project cleanup policies select tags by name/age and keep rules. Current behavior always keeps latest, excludes configured keep patterns and recent tags, and also excludes protected/immutable tags. Deleting a tag can leave manifest/layer data referenced elsewhere or awaiting garbage collection.

On GitLab.com/Dedicated, the service operates storage reclamation. On Self-Managed, administrators own registry storage and garbage-collection architecture. With the registry metadata database, GitLab supports online garbage collection; legacy/offline modes have different operational procedures. A project Maintainer should not run administrator garbage-collection commands merely because a cleanup policy removed tags.

8. Protection and immutability are different controls

Protected container repositories restrict who may push to matching repository paths and are Free across current offerings. Protected container tags restrict who may push/delete matching tags and are currently documented for GitLab.com/Self-Managed. Immutable container tags prevent matching existing tags from being updated or deleted, but are Ultimate-only on GitLab.com/Self-Managed.

Digest-based deployment remains useful even if a tag is protected or immutable: permission policy controls mutation; digest identity proves which manifest was selected.

9. A scan report is evidence about an image, not proof the image is trusted

Current GitLab container scanning is Free/Premium/Ultimate and uses a GitLab-managed CI template around the Trivy analyzer. The job can emit gl-container-scanning-report.json and a CycloneDX SBOM. Richer vulnerability-management surfaces vary by tier.

A “green scan” does not prove source provenance, absence of malware, correct base-image policy, correct digest selection, or future vulnerability status. Preserve the scanned image reference/digest, analyzer version/evidence, commit, and pipeline so findings cannot be accidentally attached to a different tag incarnation.

10. Production invariant: the release record must survive tag movement

A production handoff should be reconstructible from immutable evidence: source commit → pipeline → image repository → manifest digest → scan/report → deployment. Tags can remain for humans, but deployment/rollback decisions should be verifiable against the digest actually used.

Knowledge check

Summary

The operating model is now explicit: GitLab owns project-level registry authorization, OCI defines repositories/manifests/tags/digests, CI supplies short-lived registry identity, cleanup controls tag retention, and scanning produces security evidence. The digest is the durable content coordinate tying those layers together.

Official references

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

• GitLab Docs — Container Registry
• GitLab Docs — Authenticate with the Container Registry
• GitLab Docs — Reduce Container Registry storage
• GitLab Docs — Protected container repositories
• GitLab Docs — Protected container tags
• GitLab Docs — Immutable container tags
• GitLab Docs — Container Registry API
• GitLab Docs — Container scanning
• GitLab Docs — Container Registry metadata database
• GitLab Docs — Predefined CI/CD variables
• GitLab CLI — container-registry repository list
• GitLab CLI — container-registry tag list
• GitLab CLI — container-registry tag view
• GitLab CLI — container-registry tag delete