Artifact Registry Explained: Docker Images, Packages, and Access Control in GCP

Simple explanation

Before a container image can run on Cloud Run or GKE, it needs to be stored somewhere that GCP can pull from. Artifact Registry is that storage layer: a managed private registry where your pipeline pushes images and your runtime services pull them at deploy time.

The same pattern applies to language packages. If your team maintains a private npm library, internal Java packages, or shared Python tooling, Artifact Registry can host those too, with the same IAM controls and audit trail as your container images.

How Artifact Registry works

You start by creating a repository: a named storage location scoped to a single format (Docker, npm, Maven, and so on) in a specific region. Each repository has its own IAM policy, vulnerability scanning settings, and cleanup rules.

Once a repository exists, your build tools authenticate using Application Default Credentials or a service account, then push artefacts using the native client for that format (docker push for images, npm publish for packages). Every push is recorded in Cloud Audit Logs, giving you a full history of who pushed what and when.

At deploy time, services reference artefacts using the full registry URI. For a Docker image, that looks like this:

us-central1-docker.pkg.dev/my-project/my-repo/my-app:v1.2.0

The URI encodes the region, project ID, repository name, image name, and tag. IAM determines whether the caller is authorised to pull. If scanning is enabled, Artifact Analysis runs immediately after push and continues checking as new CVE data is published. A clean result at push time can change later as new vulnerabilities are disclosed.

Cleanup policies run on a schedule and remove untagged or stale images, keeping storage costs predictable. Remote repositories let you cache upstream registries like Docker Hub inside your own project, which eliminates rate-limiting problems and reduces external dependency.

When to use Artifact Registry

Artifact Registry is the right choice in most GCP workloads that involve containers or private packages:

• Docker images for Cloud Run. Every Cloud Run deployment requires a container image. Hosting that image in Artifact Registry in the same region as your service is the standard pattern.

• Application images for GKE. Pod specs reference images by URI. Hosting those in Artifact Registry gives you repository-level IAM and scanning alongside your cluster workloads. See securing GKE clusters for how scanning and Binary Authorization work together in practice.

• Private language packages. Internal npm, Maven, or PyPI packages that should not be published publicly belong in a private Artifact Registry repository. Developers configure their package manager to point at the registry URL and authenticate with their GCP credentials.

• Upstream package caching. A remote repository proxies Docker Hub or other external registries and caches images locally. This prevents Docker Hub rate-limit errors in Cloud Build pipelines and reduces cross-internet pull latency.

• Separating environments. Maintaining separate repositories for dev, staging, and production lets you apply different IAM policies to each. Production repositories can be restricted to deployment service accounts only, while dev repositories remain accessible to engineers. This maps directly to a sound dev, staging, and production strategy.

Artifact Registry vs Container Registry

Container Registry (gcr.io) was GCP’s original Docker registry. Google announced its deprecation and Artifact Registry is the designated replacement. As of 2025, Google has transitioned the underlying infrastructure so that gcr.io requests are served through Artifact Registry. For any new project, use Artifact Registry only.

If you are migrating existing gcr.io images, Google provides a migration tool that redirects gcr.io pulls to a corresponding Artifact Registry repository. The Artifact Registry best practices guide covers migration patterns in detail.

Creating a repository

Each repository holds one format and lives in one region. Create separate repositories per environment or per team. This keeps IAM boundaries clean and makes it straightforward to apply different cleanup and scanning policies to each.

# Enable the API
gcloud services enable artifactregistry.googleapis.com

# Create a Docker repository
gcloud artifacts repositories create my-docker-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="Production Docker images"

# Create an npm repository
gcloud artifacts repositories create my-npm-repo \
  --repository-format=npm \
  --location=us-central1

# List all repositories
gcloud artifacts repositories list --location=us-central1

Pushing and pulling Docker images

Before you can push or pull, Docker needs credentials for Artifact Registry. The gcloud auth configure-docker command writes a credential helper into your Docker config so that Docker can obtain short-lived tokens from GCP automatically.

When you push manually from a local machine, the image URI must include the full Artifact Registry path: region, project ID, repository name, image name, and tag. When Cloud Build builds and pushes images, it uses the same URI format but authenticates automatically with its service account, with no manual credential setup required.

# Configure Docker to authenticate with Artifact Registry
gcloud auth configure-docker us-central1-docker.pkg.dev

# Build, tag, and push
docker build -t us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo/my-app:v1 .
docker push us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo/my-app:v1

# Pull an image
docker pull us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo/my-app:v1

# List images in a repository
gcloud artifacts docker images list \
  us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo

# List tags for a specific image
gcloud artifacts docker tags list \
  us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo/my-app

The URI you push is the same URI you reference in Cloud Run deploy commands, Kubernetes pod specs, and Cloud Deploy release pipelines.

Managing access with IAM

Artifact Registry uses standard GCP IAM roles. The three you will use most often are:

• roles/artifactregistry.reader: pull images and packages
• roles/artifactregistry.writer: push images and packages
• roles/artifactregistry.repoAdmin: manage repository settings, delete tags, and configure policies

Bind these at the repository level wherever possible. This follows the principle of least privilege: your production deployment service account should get reader on the production repository only, not on every repository in the project. Cloud Build uses a dedicated service account (PROJECT_NUMBER@cloudbuild.gserviceaccount.com) that needs writer access to push images it builds.

# Grant a service account pull access (for Cloud Run or GKE)
gcloud artifacts repositories add-iam-policy-binding my-docker-repo \
  --location=us-central1 \
  --member=serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/artifactregistry.reader

# Grant a CI/CD service account push access
gcloud artifacts repositories add-iam-policy-binding my-docker-repo \
  --location=us-central1 \
  --member=serviceAccount:ci-cd-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/artifactregistry.writer

# Grant Cloud Build service account push access
gcloud artifacts repositories add-iam-policy-binding my-docker-repo \
  --location=us-central1 \
  --member=serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
  --role=roles/artifactregistry.writer

To restrict registry access to specific VPCs or prevent images from being pulled outside your organisation, see VPC Service Controls applied to the Artifact Registry API.

Vulnerability scanning

Artifact Analysis scans Docker images for known CVEs when they are pushed and continues scanning as new vulnerability data is published. Each finding is a vulnerability occurrence with a CVE identifier, severity (Critical, High, Medium, Low), the affected package version, and whether a patched version exists.

You can query these findings via the Container Analysis API and use the results to block deployments in your secure CI/CD pipeline. Combined with Binary Authorization, you can enforce that only scanned and approved images ever reach production.

# Enable the Container Analysis API
gcloud services enable containeranalysis.googleapis.com

# Enable scanning on a repository
gcloud artifacts repositories update my-docker-repo \
  --location=us-central1 \
  --enable-vulnerability-scanning

# List vulnerability findings for images in a repository
gcloud artifacts docker images list \
  us-central1-docker.pkg.dev/PROJECT_ID/my-docker-repo \
  --show-occurrences \
  --occurrence-filter="kind=VULNERABILITY"

Cleanup policies

Cleanup policies run on a schedule. The most common approach deletes untagged images older than a threshold. Untagged images are those superseded by a newer push but never explicitly removed. You can also combine conditions, for example keeping the most recent five tagged versions while deleting everything older.

# Delete untagged images older than 30 days
gcloud artifacts repositories set-cleanup-policies my-docker-repo \
  --location=us-central1 \
  --policy='[{
    "name": "delete-untagged",
    "action": {"type": "Delete"},
    "condition": {
      "tagState": "UNTAGGED",
      "olderThan": "2592000s"
    }
  }]'

Remote repositories

A remote repository acts as a caching proxy for an external registry such as Docker Hub, npm, or PyPI. On the first pull, Artifact Registry fetches the image or package from upstream and caches it. Subsequent pulls are served from the cache in your own project.

This solves two common problems in CI/CD. First, Docker Hub enforces rate limits on unauthenticated pulls. This issue surfaces quickly when many build workers pull popular base images at once. Second, caching images in the same region as your build infrastructure reduces pull latency and removes external internet dependency from your pipeline.

# Create a remote repository that proxies Docker Hub
gcloud artifacts repositories create dockerhub-proxy \
  --repository-format=docker \
  --location=us-central1 \
  --mode=remote-repository \
  --remote-repo-config-desc="Docker Hub proxy" \
  --remote-docker-repo=DOCKER_HUB

# Pull through the proxy
docker pull us-central1-docker.pkg.dev/PROJECT_ID/dockerhub-proxy/nginx:latest