Artifact Registry

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

Status	Authors	Coach	DRIs	Owning Stage	Created
proposed	`jdrpereira` `10io`	`sxuereb`	`trizzi` `crystalpoole`	devops package	2025-12-15

Summary

The Artifact Registry is a new SKU for GitLab providing centralized artifact management. It competes directly with JFrog Artifactory and Sonatype Nexus.

Unlike GitLab’s current project-level package and container registries, the Artifact Registry gives enterprises centralized control, visibility, and management of all artifacts (containers, packages, ML models).

The registry targets large enterprises (1,000+ users) who rely on external tools and need tool consolidation, cost optimization, and centralized governance. It offers:

Organization-level artifact management with a unified control plane
Virtual repositories that aggregate multiple upstream sources (public registries, cloud providers, legacy tools)
AI-powered configuration assistance and cost optimization
Migration tooling to onboard from other providers and existing GitLab package and container registries
Content-addressable storage with organization-scoped deduplication
Multi-format support starting with Docker, Maven, and npm

We are building a new registry from the ground up, free from backward compatibility constraints, with modern event-driven architecture from the start.

This initiative began with an internal proposal and evolved into an extended specification (internal) with user journeys, capabilities, database schemas, and implementation roadmap. This blueprint covers high-level design and architectural decisions suitable for public disclosure; the internal document contains additional strategic details.

Glossary

Organization: The highest-level container entity in GitLab, serving as the primary isolation and sharding boundary. Contains workspaces, repositories, and all artifacts. Each has independent storage, cost attribution, and deduplication scope.
Workspace: A logical grouping of repositories within an organization, organizing artifacts by team, security domain, or product line. Enables organizational structure mapping and workspace-scoped access controls. (Post-MVP feature; name subject to UX validation.)
Repository: A typed container for artifacts of a specific format (Docker, Maven, npm). Either Local (stores the organization’s own artifacts) or Virtual (aggregates upstream sources).
Local Repository: Stores artifacts published by the organization. Content-addressable storage persists artifacts; lifecycle policies manage them.
Virtual Repository: A proxy/aggregation layer caching artifacts from upstream sources (public registries, cloud providers, legacy tools). Provides unified access to local and remote artifacts.
Content-Addressable Storage (CAS): Artifacts use their SHA256 hash as both identifier and storage key, enabling deduplication, immutable paths, and integrity verification.
Artifact: A versioned software package (Docker image, Maven package, npm module) stored in the registry, consisting of metadata and one or more blobs.
Blob: Raw artifact content (container layers, package files). Stored and deduplicated within each organization.
Upstream Source: An external registry providing cached content to virtual repositories (Maven Central, npmjs.com, Docker Hub, AWS ECR, JFrog Artifactory, other GitLab repositories).
Deduplication: Automatic elimination of duplicate storage within an organization. Identical content (same SHA256 hash) stores only once.
OCI (Open Container Initiative): Industry standards for container formats and runtimes, extending beyond Docker’s original format.
MVP (Minimum Viable Product): Phase 1, covering ~30% of enterprise use cases (internal) with core storage, virtual repositories, and basic lifecycle management.
GA (General Availability): Production-ready status for all installation types (GitLab.com, Self-Managed, Dedicated).
SKU (Stock Keeping Unit): A distinct product offering. The Artifact Registry is a new premium SKU, separate from existing free-tier registries.
RBAC (Role-Based Access Control): Permissions assigned based on roles at organization, workspace, or repository level.

Motivation

GitLab’s current artifact management is fragmented and project-centric:

Project-level coupling: All artifacts bind to individual projects, creating a 1:N management burden where N can reach thousands of projects
No centralized visibility: Customers cannot see or manage artifacts across projects. Questions like “What artifacts do we have?” or “What’s our total storage cost?” are hard to answer
Separate implementations: Package registry (Rails) and container registry (Go) are separate applications with different architectures, preventing unified experiences
Repetitive configuration: Security policies, lifecycle rules, and access controls must be configured per-project with limited inheritance
Event data silos: Usage and security events scatter across services with no centralized harvesting. Security features like container scanning are reactive rather than proactive
Storage inefficiencies: Package registry lacks deduplication; container registry’s instance-wide deduplication creates operational complexity with expensive cross-partition operations
Development velocity gap: Container registry has limited access to Rails monolith tooling (migrations, feature flags, automated releases), slowing feature delivery
Limited enterprise features: No virtual repositories, limited upstream proxying, no migration path from JFrog/Nexus

Target Market:

Enterprises using competing tools who want to:

Consolidate tools into GitLab
Centralize management of their artifact landscape
Optimize costs with visibility and AI-powered recommendations
Migrate from legacy tools

Why Now:

Team expertise: The Package stage has 6+ years operating registries, understanding what works, what doesn’t, and what customers need
Technology maturity: Modern storage, event streaming, and AI/ML capabilities now exist that weren’t available when current registries were designed
Clean break advantage: Starting fresh provides velocity and architectural freedom for today’s requirements
Market opportunity: We can leapfrog competitors with an AI-native, top-level scoped solution

Strategic Alignment:

AI Integration: Event-rich foundation enables AI-powered configuration, cost optimization, and predictive capabilities (see AI-Enhanced Artifact Management)
Enterprise Positioning: Competes directly with JFrog and Nexus
Platform Consolidation: Eliminates external artifact management tools

Goals

Provide organization-level artifact management eliminating project-level fragmentation
Enable migration from JFrog Artifactory and Sonatype Nexus with tooling, validation, and safety controls
Deliver AI-powered optimization: configuration assistance, cost recommendations, predictive insights
Support virtual repositories aggregating upstream sources with caching
Reduce platform engineering effort through automation, templates, and AI assistance
Achieve cost savings through deduplication, lifecycle policies, and optimization
Align with Cells architecture using Organizations as the isolation and sharding boundary
Support multi-format artifacts: containers (Docker, OCI), packages (Maven, npm), and future formats

Non-Goals

Enhancing existing registries: This is a new SKU, not an evolution of current registries. Existing registries continue in parallel with no sunset plans. Free tier keeps current tools; Artifact Registry is a premium feature. Building new avoids disrupting tier 0 tools and eliminates backward compatibility constraints
Supporting nested group artifact management: Organizations are the isolation boundary, not top-level groups or projects
Providing instance-wide deduplication: Deduplication scopes to organizations for clear cost attribution
Supporting all artifact formats in MVP: Starting with Docker, Maven, npm; additional formats in v1.0+

Proposal

Design and implementation details

Architecture Overview

The Artifact Registry is implemented within a satellite service, leveraging GitLab’s Runway while maintaining clear boundaries for the new SKU. Key architectural decisions:

Scalability Requirements

The registry targets GitLab.com scale and large enterprise organizations. For detailed requirements, see ADR-003: System Requirements.

Phased Implementation

Implementation follows three phases, prioritized for customer adoption while building differentiation capabilities.

MVP (Phase 1)

Goal: Table stakes for customer adoption, covering ~30% of enterprise use cases with organization-level management.

Artifact Storage & Management:

Multi-format support (Docker, Maven, npm)
Content-addressable storage with organization-scoped deduplication
Metadata management
Basic artifact operations (upload, download, delete, tag)
Version management
GitLab CI metadata capture (platform captures pipeline, commit, and job context in artifact metadata)

Repository Management:

Repository types (local/virtual)
Typed repositories per format
Organization repositories (no workspaces)
Repository configuration

Virtual Repositories:

Public upstream proxying (Maven Central, npmjs.com, Docker Hub)
Private upstream proxying with credentials management
Multiple upstreams support where public and private upstreams can be mixed in a priority-based list
Shareable upstream configurations
Connection testing and health monitoring
Basic cache management with TTL

Access Control:

Organization RBAC
Authentication methods (personal access tokens, deploy tokens, CI/CD job tokens)
Visibility controls (public, internal, private)

Lifecycle Management:

Automated retention policies (basic)
Expiration management
Soft deletion with restoration capability
Version cleanup
Quarantine management

Analytics & Observability:

Organization dashboard with unified visibility
Download tracking
Storage usage and trends
Basic audit logging

Integration:

RESTful API
GraphQL API
Native client support (Maven, npm, Docker)
CI/CD integration/metadata

Success Criteria for MVP:

Customers can publish and retrieve Docker, Maven, and npm artifacts through organization repositories
Virtual repositories successfully proxy and cache artifacts from public upstream sources
Organization administrators can configure lifecycle policies that apply across all repositories
API performance meets or exceeds existing package/container registry benchmarks
GitLab CI/CD pipelines can seamlessly publish artifacts with embedded metadata
Early adopter customers validate the platform with production workloads

v1.0 and Beyond

v1.0 Goal: Expand format support and advanced features to reach ~60% of enterprise use cases.

Key v1.0 capabilities:

Additional artifact formats (PyPI, NuGet, RubyGems, Go modules)
Workspace support for organizational structure mapping
Enhanced virtual repository features (cloud provider integration, multi-upstream aggregation)
Advanced lifecycle policies with pattern matching and usage-based rules
Enhanced analytics and cost attribution

Success Criteria for v1.0:

Support for 7+ artifact formats with consistent management experience
Workspace-based structure enables large enterprises to map their team hierarchy
Customers successfully migrate from JFrog/Nexus using automated tooling
AI-powered recommendations reduce configuration time by measurable percentage

For comprehensive capability prioritization including v1.0 (Phase 2) and Future (Phase 3+) features, see the Capability Prioritization Matrix in the extended blueprint (internal).

Migration Strategy

Migration prioritizes service stability before introducing migration tools.

MVP Approach: Organic Migration

The MVP excludes migration tools. The registry will stabilize first, incentivizing organic adoption for new workflows:

Service matures and establishes reliability
Early adopters validate the platform with new projects
Avoids premature migration tooling complexity
Time to gather feedback and refine migration requirements

Users publish artifacts manually using native clients (npm, Maven, Docker). Virtual repositories facilitate gradual adoption by proxying upstream sources during migration.

Post-MVP: Migration Tools

After stabilization, migration capabilities accelerate adoption:

From External Providers:

Bulk import from specific competitors
Metadata extraction and preservation
Dry-run validation before actual migration
Progress tracking and error reporting
Rollback capabilities
Checksum verification and metadata completeness validation
Dependency resolution validation and pre-flight compatibility checks
Transitive dependencies support

From GitLab Package and Container Registries:

Migration tooling to move artifacts from existing GitLab project-level registries to the unified registry
Seamless transition path for GitLab customers

For migration timeline and prioritization, see the Capability Prioritization Matrix (internal).

Team Dependencies

The Artifact Registry requires collaboration with several GitLab teams to ensure successful implementation:

TBD

Alternative Solutions

TBD

Decisions

Key architectural decisions are documented as Architecture Decision Records (ADRs).

Note: Some ADRs include an Open Questions section capturing details not yet decided during the initial proposal. These do not block review and will be addressed in subsequent updates or new ADRs.

ADR-001: Organizations as Anchor Point - Why the registry anchors to Organizations
ADR-002: Storage Deduplication Scope - Deduplication scoped to Organizations rather than instance-wide
ADR-003: System Requirements - Infrastructure requirements and performance constraints

View page source - Edit this page - please contribute.