Artifact Registry is a managed place to keep the files your software is built from and delivered in.

What is an artifact?

When developers write code, the code is not what actually runs in production. First it is compiled, packaged and bundled into files. These produced files are called artifacts. A container image, which is a sealed box holding an application and everything it needs to run, is an artifact. A Java library file, a Python package and a JavaScript module are also artifacts. Teams build many artifacts every day, and they must store them somewhere so that servers, test systems and other developers can fetch them.

The problem of scattered artifacts

Without a central, managed store, artifacts end up on personal laptops, shared folders or public websites. Nobody knows which version is the latest, who can download it, whether it contains a known security flaw, or whether it came from a trustworthy source. If a public website that hosts a library goes down, every build that depends on it fails. If someone uploads a malicious package with a familiar name, it can slip into your product unnoticed.

What the service does

Artifact Registry is a fully managed service that stores container images and language packages in private repositories inside your Google Cloud project. It controls who can read and write them using Google Cloud identity, scans images for known weaknesses, can cache packages from public sources, and works smoothly with Google Cloud build, deployment and runtime services. It also replaces the older Container Registry, which is being shut down.

Twelve words you will meet in every Artifact Registry conversation.

These words will return with examples in later chapters. For now, hold the picture in mind: a build produces artifacts, repositories store them, and identities with the right permissions pull them to run.

From a developer’s keyboard to a running application, Artifact Registry is the middle stop.

Software moves through a pipeline. A developer commits code. A build system compiles it, runs tests and produces an image or package. That artifact is pushed to Artifact Registry. A deployment system then pulls the artifact and starts it on a cluster, a serverless platform or virtual machines. Because every stage passes through the registry, it is the natural place to apply checks, record history and control access.

flowchart LR
DEV["Developer commits code"] --> BLD["Build system: compile and test"]
BLD -->|"Push"| AR["Artifact Registry"]
AR --> SCAN["Vulnerability scan"]
SCAN --> DEP["Deployment system"]
AR -->|"Pull"| RUN["GKE, Cloud Run, Compute Engine"]
DEP --> RUN
        

One service, many kinds of artifacts, each in its own repository.

A repository holds one format. You create a separate repository for each format you use, and you set its location when you create it. The supported formats cover the most common ecosystems used to build software.

Three kinds of repository, for private storage, caching and combining.

flowchart TD
DEVS["Developers and Build Systems"] --> VR["Virtual Repository: one address"]
VR -->|"Priority 1"| SR["Standard Repository: private packages"]
VR -->|"Priority 2"| RR["Remote Repository: cache of public source"]
RR --> PUB["Public Package Source"]
        

Why remote repositories matter

Pulling packages straight from the public internet on every build is slow and risky. The public site can be down, can change a package without warning, or can be blocked in a locked down network. A remote repository gives you a nearby copy, faster builds, a record of what was used, and a place to apply scanning and access rules. For container images, caching public images protects you from download rate limits on public registries.

Why virtual repositories matter

Developers should not need to know which of several repositories holds a package. A virtual repository gives them one address. Priorities decide which source wins when the same name appears in more than one place, and getting these priorities right is a security matter, as the next callout explains.

Where your artifacts live, and how their addresses are built.

Every repository is created in a location, which can be a single region or a multi-region such as a large geographic area. Choosing a location close to where artifacts are built and used makes pulls faster and keeps traffic inside Google’s network. A repository’s location cannot be changed after creation, so choose with care.

You may likeArtifact Repository Integration in Jenkins→

The address of an image

An image address has four parts: a host name that includes the location and the Artifact Registry domain, then the project, then the repository, then the image name with a tag or digest. Because the repository is part of the address, it also forms a natural boundary for permissions. Different repositories can have different access rules, even inside one project.

flowchart TD
P["Google Cloud Project"] --> R1["Repository: Docker images, region A"]
P --> R2["Repository: Python packages, region A"]
P --> R3["Repository: Maven packages, multi-region"]
R1 --> I1["Image: web service"]
R1 --> I2["Image: worker service"]
I1 --> T1["Tag: version 1.4"]
I1 --> T2["Tag: version 1.5"]
        

What happens behind the scenes when a build uploads an image and a cluster downloads it.

sequenceDiagram
participant B as Build System
participant R as Artifact Registry
participant I as IAM
participant K as Cluster or Runtime
B->>R: Push image layers
R->>I: Check writer permission
I-->>R: Allowed
R-->>B: Stored, digest returned
K->>R: Pull image by tag or digest
R->>I: Check reader permission
I-->>R: Allowed
R-->>K: Send image layers
        

Tag or digest?

A tag can be moved to point at a different image later, which is convenient but risky. A digest is a fingerprint of exact contents and never changes. For production deployments, pulling by digest guarantees you run exactly what was tested.

Decide exactly who can push, who can pull and who can manage.

Artifact Registry uses Google Cloud identity and access management. Roles can be granted on a whole project or, more precisely, on a single repository. The built-in roles separate duties clearly, so that people and systems get only what they need.

Principle of least privilege

Give each identity the lowest role that does the job. A runtime that only pulls images needs the reader role on the specific repository, not on the whole project. A build pipeline needs the writer role on its own repository, not on others. Avoid giving the administrator role to automation. Separate repositories for production and development let you give developers wide access to one and tight access to the other.

An artifact store is the checkpoint where trust can be proven or lost.

Attacks on software increasingly target the supply chain, meaning the libraries, images and build tools that a product depends on. A single poisoned dependency can compromise thousands of systems. Artifact Registry gives several tools to reduce this risk, and works together with other Google Cloud services to form a chain of trust.

flowchart LR
SRC["Source code"] --> BLD["Trusted build"]
BLD --> IMG["Image pushed to repository"]
IMG --> SC["Vulnerability scan"]
SC --> AT["Attestation: approved"]
AT --> BA["Binary Authorization checks"]
BA -->|"Approved"| PROD["Production runs image"]
BA -->|"Rejected"| STOP["Deployment blocked"]
        

Without cleaning, every build adds to your bill and your confusion.

Build systems can produce an image on every code change. In a busy team that is dozens a day, and old ones are almost never used again. Storage is billed by volume, and a cluttered repository makes it hard to find what is current. Cleanup policies automatically remove artifacts you no longer need, while keeping the ones you want.

Kinds of rules

Test before you delete

Deleting the wrong artifacts can break deployments. Cleanup policies offer a dry run mode, which only logs what would be deleted without removing anything. Always run a policy in dry run first, check the logs, and only then turn on real deletion. Keep rules in a clear order, since keep rules take priority over delete rules when they conflict.

Artifact Registry is most valuable as the shared hub of your delivery tools.

flowchart TD
GIT["Source repository"] --> CB["Cloud Build"]
CB --> AR["Artifact Registry"]
AR --> CD["Cloud Deploy"]
CD --> GKE["GKE cluster"]
CD --> CR["Cloud Run service"]
AR --> BA["Binary Authorization"]
BA --> GKE
        

If you ever used the older service, here is the story and how to move.

Before Artifact Registry, Google offered Container Registry for images only. Container Registry has been deprecated and shut down, and Artifact Registry is the recommended replacement for storing container images. It adds support for non-container formats, finer access control and more location choices. Container Registry controlled access through Cloud Storage roles on hidden buckets, while Artifact Registry uses its own roles that separate reading, writing and administration more clearly.

Keeping old addresses working

Many systems have the old gcr.io addresses written into deployment files. Artifact Registry can host repositories that answer requests for the gcr.io domain, in multi-region locations that match the old host names, so existing addresses keep working after migration. Google also provides a migration tool that creates matching repositories, copies images and helps map permissions. New projects without previous Container Registry usage already have images for the gcr.io domain hosted on Artifact Registry.

flowchart TD
A["Check Container Registry usage"] --> B["Create Artifact Registry repositories"]
B --> C["Map and grant IAM roles"]
C --> D["Copy images"]
D --> E["Update deployment files or use gcr.io hosting"]
E --> F["Test pulls and builds"]
F --> G["Retire old storage"]
        

When a deployment cannot pull an image, you need answers within minutes.

Artifact Registry records administrative actions and, if you enable them, data access events such as pulls and pushes, in audit logs. It can also produce platform logs for repository activity. Combined with Cloud Monitoring, this lets you see who accessed what, find failed requests and track usage and storage growth.

Make sure your private machines can reach the registry without touching the public internet.

Runtimes in private networks often have no internet access, yet they must still pull images. Google Cloud provides private routes for this. Private Google Access lets virtual machines without external addresses reach Google services, including Artifact Registry, through Google’s network. Private Service Connect and VPC Service Controls can add further isolation, so that artifacts and their metadata cannot be copied out of a defined perimeter.

Storage and network traffic drive most of the bill, and both are controllable.

Artifact Registry is billed mainly on the amount of data stored and on network traffic that leaves a location, with a small free storage allowance. Pulls inside the same region are generally free of network charges, while pulls across regions or out to the internet follow standard network rates. Vulnerability scanning has its own charges, and billing begins once the scanning service is enabled for a project. Exact rates vary and change, so use the official pricing page and calculator.

Where a trusted artifact store keeps delivery smooth.

These are common patterns rather than named customer stories, because specific designs change over time.

A managed store gives control and convenience, and asks for care with permissions and cost.

Habits that make a registry an asset, and habits that make it a liability.

Patterns that work

Strong teams use one repository per format per team or environment, with clear names. They build once and promote the same image through test and production by digest, instead of rebuilding. They route public packages through remote repositories and place their private repository first in virtual repositories. They scan on push and on a schedule, and they enforce approvals with Binary Authorization for production. They give identities the lowest roles possible, set cleanup policies from the start, and keep repositories near their runtimes.

A checklist to keep your artifact store safe, tidy and affordable.

Mistakes beginners make most often

The first is using a moving tag in production. The second is granting broad roles for convenience. The third is forgetting cleanup policies. The fourth is putting the repository in a far away region. The fifth is neglecting permissions when migrating from Container Registry. The sixth is trusting a one-time scan forever. The seventh is letting builds fetch directly from public sources with no checkpoint.

There are several places to keep images and packages, and each has its own character.

flowchart TD
Q1{"Need to store images or packages for Google Cloud workloads?"} -->|Yes| AR["Artifact Registry"]
Q1 -->|No| Q2{"Only plain files like archives?"}
Q2 -->|Yes| GS["Cloud Storage or generic repository"]
Q2 -->|No| Q3{"Must run outside Google Cloud with full control?"}
Q3 -->|Yes| SH["Self-hosted artifact server"]
Q3 -->|No| AR
        

Many organizations mix these. They use Artifact Registry for Google Cloud workloads, and a separate tool where they must support other clouds or special requirements, often connected through remote repositories or mirroring.

It is a fully managed Google Cloud service for storing, securing and delivering container images and language packages used in building and running software.

No. It also supports Maven, npm, Python, Go, apt, yum and other formats, each in its own repository.

A standard repository stores your own private artifacts. A remote repository caches artifacts from an outside source such as a public package site. A virtual repository gives one address that combines several repositories behind it, in priority order.

Only identities that have a role allowing it, such as the Artifact Registry Reader role on that repository or project. Grant it to the service accounts of your clusters and services.

Tags are friendly but can be moved to point at different images. Digests are exact fingerprints that never change. Use digests or immutable tags for production deployments.

Create cleanup policies with keep and delete rules, test them with dry run, and then enable them. This controls cost and clutter automatically.

Yes, through Artifact Analysis, which can scan images in repositories and report known vulnerabilities. Scanning can be turned on or off per repository, and it carries its own charges.

No. The location is chosen when the repository is created. To move, create a new repository in the desired location and copy the artifacts.

It was deprecated and shut down, and Artifact Registry is the recommended replacement. Artifact Registry can host repositories that answer the old gcr.io domain, so existing addresses can keep working after migration.

Yes, using Private Google Access or private connectivity options, so traffic stays on Google’s network instead of the public internet.

Mainly by the amount of storage used and by network traffic that leaves a location, with a small free allowance. Scanning is billed separately. Check the official pricing page for current rates.

By offering private, access-controlled storage, vulnerability scanning, immutable tags, remote repositories as controlled caches, audit logs and integration with Binary Authorization, which can block unapproved images from running.

Artifact Registry is Google Cloud’s managed home for container images and software packages. Builds push artifacts into repositories, scanners and policies inspect them, and runtimes pull them with narrowly granted permissions. Standard, remote and virtual repositories let you keep private artifacts, cache public ones and give developers a single address. Success comes from sensible repository layout, least privilege access, deployment by digest, scanning and approvals, regular cleanup and attention to location and cost.