Before looking at features, let us understand what an “artifact” is and why it needs a registry.

What is an artifact?

An artifact is any file or bundle produced or used while building and running software. Examples include a container image that holds an application and everything it needs to run, a Java library packaged as a jar file, a JavaScript package, a Python package, or a Helm chart that describes how to install an application on Kubernetes. Artifacts are the finished parts that get passed from one stage of software delivery to the next.

The one-sentence definition

Artifact Registry is Google Cloud’s fully managed service for storing, managing and securing container images and language packages. It gives your teams a single place to keep these artifacts, control who can use them, scan them for known weaknesses and deliver them quickly to the systems that run your applications.

The problem it solves

Without a central registry, teams store images and packages in scattered places: personal laptops, shared drives, public websites or separate tools for each language. This makes it hard to know what is in production, who can change it, or whether a package has been tampered with. A central, access-controlled, scanned registry brings order and safety.

Understanding where it came from explains why it supports so many formats and so many security features.

Google’s first image storage service, Container Registry, was built around container images stored in Cloud Storage buckets. It worked well but was limited: it handled only container images, its permission model was tied to storage buckets, and it lacked features such as per-repository access, regional placement and support for other package types. Meanwhile, software teams used many package formats in the same project and wanted one consistent system rather than a different tool for each.

Artifact Registry was designed to fix this. It introduced repositories as first-class resources, each with a format, a location and its own permissions. It added more formats, regional and multi-regional storage, remote and virtual repositories, cleanup policies, and tighter links to security scanning and deployment tools. Over time, Container Registry was phased out in favor of it.

A handful of terms appear in every conversation about Artifact Registry. Learn them once and everything else becomes easier.

flowchart TD
  P[Google Cloud Project] --> R1[Repository: Docker, us-central1]
  P --> R2[Repository: Maven, europe-west1]
  P --> R3[Repository: Python, us-central1]
  R1 --> I1[Image: web-app]
  I1 --> V1[Version by Digest]
  V1 --> T1[Tags: v1.4.2, latest]
  R2 --> PK[Package: payments-client]
  PK --> V2[Versions 1.0, 1.1, 1.2]
        

One of Artifact Registry’s biggest strengths is that it speaks the languages of many tools.

Support for formats can grow over time, and some formats have their own limits and rules. Check the current list in the official documentation before you plan around a specific format.

Why one registry for many formats helps

Not all repositories work the same way. The mode you choose shapes how artifacts get in and how they are served.

Standard repositories

This is where you publish what you build. A build pipeline creates a container image or library, pushes it to a standard repository, and downstream systems pull it from there. You control who can write to it and who can read from it.

Remote repositories

A remote repository acts as a smart middleman between your builds and a public registry. Instead of every build reaching out to the internet, builds ask your remote repository, which fetches the item once and keeps a copy. This speeds up builds, reduces dependence on outside availability, can help avoid rate limits imposed by public registries and lets you apply your own scanning and access controls to third-party packages. Upstream sources can include well-known public registries and package indexes, and in some cases custom upstream addresses with credentials stored securely.

Virtual repositories

Developers do not want to configure ten different addresses. A virtual repository gives them one address. Behind it, you list the underlying repositories, for instance your own internal packages and a remote repository for the public index, and give each a priority. When someone asks for a package, the virtual repository checks them in order. This also helps defend against dependency confusion attacks, where an attacker publishes a public package with the same name as one of your private packages, because you can set your private repository to a higher priority.

flowchart TD
  D[Developer or Build Tool] --> V[Virtual Repository: One Address]
  V -->|Priority 1| S[Standard Repository: Internal Packages]
  V -->|Priority 2| R[Remote Repository: Cache of Public Index]
  R --> U[Upstream Public Registry]
        

Where a repository lives, and how you address it, affects speed, cost, compliance and day-to-day usage.

Regional and multi-regional repositories

When you create a repository, you choose a location. A regional repository stores data in one region, such as one near your servers. A multi-regional repository stores data across a larger area, such as the United States, Europe or Asia, which can improve availability and serve widely distributed users. For most workloads, a regional repository in the same region as your build and deployment systems gives the best speed and the lowest transfer cost.

The shape of an address

Each format has a host name based on the format and location, followed by the project, the repository and the package. For container images, the address looks like a location-based host name, then the project identifier, then the repository name, then the image name with a tag or digest. Knowing this pattern makes it easy to read configuration files and logs.

Choosing locations wisely

A look at the journey of an artifact makes the rest of the service easier to understand.

Pushing a container image

A container image is made of layers, which are stacked chunks of files, plus a manifest that lists the layers and a small configuration. When you push an image, your tool checks which layers the registry already has, uploads only the missing ones, and then uploads the manifest. Because layers are shared, many images that share a common base only store that base once, saving space and time.

Pulling an artifact

When a cluster or service pulls an image, it authenticates, requests the manifest by tag or digest, then downloads the needed layers. For remote repositories, if the item is not yet cached, the service first fetches it from the upstream source, stores it and then serves it. For virtual repositories, the service checks the underlying repositories in priority order.

sequenceDiagram
  participant B as Build Pipeline
  participant AR as Artifact Registry
  participant AA as Artifact Analysis
  participant K as GKE or Cloud Run
  B->>AR: Push image layers and manifest
  AR->>AA: Request vulnerability scan
  AA-->>AR: Store findings and metadata
  K->>AR: Pull image by tag or digest
  AR-->>K: Return manifest and layers
        

Because artifacts become running software, controlling who can read and write them is a core security task.

IAM at the repository level

Access is managed through Identity and Access Management. You can grant roles at the project level, which affects every repository in the project, or at the repository level, which affects only that repository. Repository-level permissions are the preferred approach, because they follow the principle of least privilege.

How tools authenticate

Public access

Repositories can be made readable by anyone, for example to share an open-source package. This is powerful but risky. Be deliberate: review exactly what a repository contains, and never make a repository public if it might hold private code, configuration or secrets baked into images.

Storing artifacts is only half the job. Knowing whether they are safe is the other half.

You may likeArtifact Repository Integration in Jenkins→

What scanning does

Artifact Analysis examines the contents of your artifacts, such as the operating system packages and language libraries inside a container image, and compares them to databases of publicly known security weaknesses. It then records the findings, with severity levels, against the specific image version. Scanning can run automatically when an image is pushed and can continue as new weaknesses are discovered, because an image that was clean yesterday may be flagged tomorrow.

Using findings well

A secure registry is one link in a chain. The goal is to know that what runs in production is exactly what you built and approved.

Why supply chain security matters

Attackers increasingly target the steps between writing code and running it: compromised build systems, poisoned dependencies and swapped images. A secure software supply chain aims to make each step verifiable, so that you can prove where an artifact came from and that nobody changed it along the way.

The building blocks

flowchart LR
  A[Source Code] --> B[Trusted Build with Provenance]
  B --> C[Push Image to Artifact Registry]
  C --> D[Scan and Test]
  D --> E[Create Attestation]
  E --> F{Deployment Policy Check}
  F -->|Required proof present| G[Deploy to GKE or Cloud Run]
  F -->|Missing proof| H[Deployment Blocked]
        

How you label artifacts decides how safely and predictably you can deploy and roll back.

Tags can move, digests cannot

A tag such as “latest” is just a label that can be reassigned to a different image at any time. If a deployment refers to “latest”, two servers started a day apart might run different code without anyone noticing. A digest is a fingerprint of exact content and never changes. For anything important, deploy by digest, or by a version tag that your process never reuses.

Immutable tags

Docker repositories can be configured so that a tag, once assigned, cannot be moved to a different image. This prevents accidental or malicious overwriting and gives each release label a permanent meaning.

Promotion across environments

A common pattern keeps separate repositories for different stages, such as development, staging and production. An image is built once, tested, and then promoted by copying the same image, with the same digest, into the next repository, rather than rebuilding it. This ensures the thing you tested is the thing you ship, and lets you restrict who can write to the production repository to your trusted pipeline only.

Left alone, registries grow forever. Every build adds new versions, and storage is billed.

The problem of endless growth

A busy team may push hundreds of images a day. Most are old test builds that nobody will ever use again. Without cleanup, storage costs climb, searching becomes noisy and scanning covers many stale items.

Cleanup policies

Cleanup policies let you define rules that automatically delete or keep versions in a repository. Rules can be based on tag status, tag prefixes, version age or the number of recent versions to keep. You can combine “delete” rules with “keep” rules, where keep rules take priority so you never lose the artifacts you need. A dry run mode shows what would be deleted before you turn the policy on.

Artifact Registry sits in the middle of the delivery pipeline. Here is how it connects to its neighbors.

flowchart LR
  DEV[Developer Commits Code] --> CB[Cloud Build]
  CB --> AR[Artifact Registry]
  AR --> SCAN[Artifact Analysis Scan]
  AR --> CD[Cloud Deploy]
  CD --> GKE[GKE Cluster]
  CD --> CR[Cloud Run]
  AR --> PS[Pub/Sub Notification]
  PS --> AUTO[Automation and Alerts]
        

Artifacts often contain valuable code, so the network and encryption layers matter.

Many organizations started with Container Registry. Moving to Artifact Registry is a common, well-trodden task.

What changes

Container Registry stored images in buckets with bucket-level permissions and project-wide addressing. Artifact Registry uses repositories with their own permissions and different host names. Google provides ways to keep older gcr.io style addresses working by hosting them in Artifact Registry, and tools to copy existing images, so most migrations are gradual rather than abrupt.

When a deployment fails to fetch an image at midnight, you want answers quickly.

What to monitor

Artifact Registry costs are modest compared with compute, but they can still surprise you.

Ways to keep costs down

Several tools can store artifacts. Knowing the differences helps you choose.

flowchart TD
  Q1{Are you running software on Google Cloud?} -->|Yes| Q2{Need containers or language packages?}
  Q1 -->|No| A1[Consider the registry of your main cloud]
  Q2 -->|Yes| A2[Artifact Registry]
  Q2 -->|No| Q3{Only plain files?}
  Q3 -->|Yes| A3[Cloud Storage or Generic format repository]
  Q3 -->|No| A2
        

Patterns capture what experienced teams repeatedly find works; anti-patterns capture what goes wrong.

Helpful patterns

Anti-patterns to avoid

An honest view of strengths, limits and where teams actually use the service.

Real-world examples

A checklist to carry into every project, followed by answers to common beginner questions.

No. Artifact Registry is the newer, broader service that replaces Container Registry. It supports many formats, repository-level permissions and more features, and it can serve older gcr.io style addresses to ease migration.

Container and OCI images, Helm charts, and packages for Maven, npm, Python, Go, Apt and Yum, plus Kubeflow pipeline templates and generic files. Check current documentation for the full and latest list.

A standard repository stores artifacts you publish. A remote repository caches items from an outside source. A virtual repository gives one address that checks several repositories in priority order.

Because it can point to different images over time, so deployments are unpredictable and rollbacks are unclear. Use digests or immutable version tags.

Grant the cluster’s workload or node identity read access on the specific repository, and make sure it has a network path to the service, such as Private Google Access. Avoid embedding long-lived keys.

Yes, through Artifact Analysis, which can scan supported artifacts automatically or on demand and record findings. Scanning has its own settings and cost, so review them for your setup.

No. You create a new repository in the desired location and copy the artifacts, then update the consumers.

Use cleanup policies with rules to delete old or untagged versions and keep rules for releases and recent versions. Test with a dry run first.

Use a virtual repository that ranks internal repositories above remote ones, so internal packages are always chosen when names match, and control which public packages are allowed.

Yes. Use workload identity federation or short-lived tokens so the external system gets temporary Google Cloud access without storing long-lived keys.

Build in a trusted pipeline that records provenance, scan and attest the image, deploy by digest, and use a deployment policy such as Binary Authorization to block images that lack required proof.

Storage, network transfer especially across regions or out of Google Cloud, scanning, and the compute time affected by slow pulls. Cleanup policies and regional placement help control them.

Artifact Registry is Google Cloud’s managed home for the building blocks of software: container images, Helm charts and language and operating system packages. Repositories organize artifacts by format and location, while standard, remote and virtual modes cover everything from your own releases to cached public dependencies behind one safe address. Repository-level IAM, private networking, encryption and audit logs control access; Artifact Analysis, provenance and attestations add visibility and proof; tagging discipline, immutable versions and promotion keep deployments predictable; and cleanup policies and regional placement keep costs in check. Connected to Cloud Build, GKE, Cloud Run and Cloud Deploy, it becomes the trusted middle of a delivery pipeline. Treat it as a supply chain control point, not just storage, and review current documentation for formats, limits and pricing.