Transitioning from Container Registry

Artifact Registry is the evolution of Container Registry. As a fully-managed service with support for both container images and non-container artifacts, Artifact Registry will eventually replace Container Registry.

If you currently use Container Registry, use the information on this page to learn about transitioning to Artifact Registry.


When Artifact Registry is generally available, it will provide the same container management features as Container Registry. During the beta period, you can start transitioning your automation to use Artifact Registry for your containers.

Backwards compatibility and co-existence

You can use both Artifact Registry and Container Registry in the same project. When you view a list of repositories with gcloud or Cloud Console, Artifact Registry also lists Container Registry repositories in the same project.

Both services will co-exist for a minimum of 6 months after Artifact Registry becomes generally available. This period provides time for you to transition your containers and your automation to Artifact Registry. Eventually Artifact Registry will replace Container Registry.

After Artifact Registry becomes generally available, you will have an option to create backwards-compatible repositories. These repositories can help you perform a more gradual update to your automation for builds and deployments with support for:

  • gcloud container images commands
  • Referencing the repository with a * or * hostname.

To provide compatibility, these repositories will have some feature limitations. In particular, each backwards-compatible repository must be located in the same multi-region as a corresponding Container Registry hostname in your project.

Setting up repositories

In Artifact Registry you must create repositories before you can push images to them. So a key part of moving to Artifact Registry is setting up Artifact Registry repositories and integrating them into your CI/CD automation.

To provide greater flexibility, there are some changes in how Artifact Registry represents repositories.

Container Registry

Each multi-regional location is associated with a single storage bucket. Organizing your images into repositories under a hostname is optional. Consider the following example that shows the image webapp in three locations:

Repositories are only an organizing mechanism and do not restrict access. Any user with access to the storage bucket for in this project can access all versions of the webapp container image.

Artifact Registry

Each repository is a separate resource in your project. Since each repository is a unique resource, you can:

  • Give each repository a name, description, and labels
  • Create multiple repositories in the same location
  • Configure repository-specific permissions

In addition, the location of a repository can be a region or a multi-region.

These changes give you more control over your repositories. For example, if you have teams in São Paulo and Sydney, you can create a repository for each team in a region that is geographically closer than the nearest multi-regional location.

You can then grant each team with permissions to their team repository only.

See the setup guide for instructions to transition to Artifact Registry.

New and changed features

This section summarizes improvements and changes to container management in Artifact Registry.

Supported formats

Artifact Registry supports multiple artifact formats, including container images, Java packages and Node.js modules.

If you have a question about support for another artifact format, use one of the support options to ask about it.

Changes to repositories

  • Repository creation: Container Registry automatically creates a repository in a multi-region if you have not pushed an image there before. In Artifact Registry, you must create the target repository before pushing images to it.
  • Regional repositories: You can create repositories in the same multi-regions as Container Registry (Asia, Europe, United States), or create them in a specific region. As an example, the closest multi-region for Australia is Asia. With regional support, you can create a repository in the Sydney data center.
  • Multiple discrete repositories: You can create multiple repositories in the same location within a single project. See Organizing your repositories for more information.
  • Hostname: To push to and pull from Artifact Registry Docker repositories, you must use a * hostname. For details on the name format, see Repository and artifact names.

    After Artifact Registry becomes generally available, Artifact Registry will provide an option to create backwards-compatible repositories that you can reference with both * and * hostnames.

  • Repository-level access control: You can apply repository-specific permissions to control access by team, development stage, or other context.

Product-specific roles and permissions

Container Registry does not have its own roles and permissions. Instead, you control access using IAM roles for Cloud Storage. Artifact Registry has its own roles for access control.

You can set these permissions at the project level or on each Artifact Registry repository so that you have more control over access to different repositories that are used in different contexts.

Service accounts for common Google Cloud integrations are configured to work with Artifact Registry repositories in the same project by default.


Artifact Registry supports the same authentication methods as Container Registry.

If you use the Docker credential helper, version 2.0.0 or newer is required. Docker client versions prior to v18.03 are no longer supported.

Using Google Cloud Console

You can view a list of your Artifact Registry and Container Registry repositories in the Artifact Registry section of Cloud Console.

If you click a Container Registry repository, you are directed to the list of images in the Container Registry section of the Cloud Console.

Using gcloud and API commands

After Artifact Registry becomes generally available, Artifact Registry will provide an option to create backwards-compatible repositories that support gcloud container images commands. For a comparison of Container Registry and Artifact Registry gcloud commands, see the gcloud command comparison.

Artifact Registry also includes an API for managing repositories and artifacts in all formats.

Pub/Sub notifications

Artifact Registry publishes changes to the same gcr topic as Container Registry. If you create repositories in the same project as your existing Container Registry service, your existing Pub/Sub configuration works automatically.

If you set up Artifact Registry in a different project than Container Registry, you can set up the Pub/Sub in that project.

To learn more, see Configuring Pub/Sub notifications.

Feature availability

Java and Node.js package management is in alpha and is only available to users who are in the alpha group. To apply for the alpha, complete the signup form.

The following Container Registry features are not currently available in the Artifact Registry beta release. This page will be updated for changes in feature availability.

Refer to this page and the release notes for any feature updates during the beta period.

  • Container Analysis and vulnerability scanning
  • Integration with Binary Authorization
  • Integration with App Engine and Container-Optimized OS
  • Google-provided containers are still hosted on Examples of hosted containers include:


For Container Registry, you are billed for Cloud Storage usage, including storage and network egress. Artifact Registry has its own pricing and you are charged for storage and network egress. For details see Pricing.