Consider both internal processes for creating your artifacts and the usage by consumers of your artifacts when you create your repositories.
Each repository is associated with a specific artifact format. For example, a Docker repository stores Docker images. You can create multiple repositories for each format in the same Google Cloud project.
There are multiple repository modes. Each mode serves a different purpose, so you cannot change the repository mode after you have created a repository.
Standard repositories are regular Artifact Registry repositories for your private artifacts. You upload and download artifacts directly with these repositories and use Artifact Analysis to scan for vulnerabilities and other metadata.
To create standard repositories, follow the steps in Create standard repositories.
Remote repositories are read-only repositories that act as proxies to store artifacts from the following upstream sources:
The first time you request an artifact version, the repository downloads it from the upstream source and caches a copy of it. The remote repository serves the cached copy when the same version is requested again.
Remote repositories reduce latency and improve availability for builds and deployments on Google Cloud. You can also use Artifact Analysis to scan cached packages for vulnerabilities and other metadata.
To learn more about remote repositories, read Remote repository overview. To create remote repositories, follow the steps in Create remote repositories.
A read-only repository that acts as a single access point to download, install, or deploy artifacts of the same format from one or more upstream repositories. An upstream repository can be a standard, remote, or virtual repository.
Virtual repositories simplify client configuration for consumers of your artifacts. You can also mitigate dependency confusion attacks by configuring your upstream policy to prioritize repositories with your private artifacts over remote repositories that cache public artifacts.
To learn more about virtual repositories, read Virtual repository overview. To create virtual repositories, follow the steps in Create virtual repositories.
The following diagram shows one of many possible ways you can use repositories in different modes together. The diagram shows a workflow across two Google Cloud projects. In a development project, developers build a Java application. In a separate runtime project, another build creates a container image with the application for deployment to Google Kubernetes Engine.
In the development project, a Java development team uses Cloud Build to build a Java application.
In the runtime project, Cloud Build containerizes the Java application.
The build uses the Maven virtual repository to download the application. The virtual repository serves the package from the standard repository in the development project. The build can also download public Java dependencies from the same virtual repository.
In the runtime project, Cloud Build uploads the built container image to a standard Docker repository.
GKE pulls images from the Docker virtual repository.
In this example, all repositories, builds, and GKE clusters are in the same region. Using the same location for Google Cloud services has benefits which are described in Repository location.
This section describes why you might want to create a repository in the same region as other Google Cloud services.
You can reduce latency and network egress costs by creating repositories in the same region where you run GKE, Cloud Run, Cloud Build, and other Google Cloud services that interact with the repository. There is no charge for egress from Artifact Registry to other Google Cloud services in the same region.
Although there is no charge for egress from a multi-region to a Google Cloud service in a corresponding region, this pricing only applies to a limited set of regions.
us multi-region, egress to a region in the United States such as
us-central is not charged, to any region in Canada or South America is
charged.asia multi-region, egress to regions in Asia such as
asia-northeast1 are not charged, but egress to regions in Australia are
charged.Consider the location of consumers outside of Google Cloud. For example, if you developers team in Australia need to download artifacts from Artifact Registry to their local workstations, a repository in an Australian region will reduce latency and incur lower egress charges than a repository located on another continent.
If you need to comply with regulations or policies that require you to store data in specific regions, you can include a resource locations constraint in your Google Cloud organization policy that only allows repository creation in compliant regions. Artifact Registry only enforces the constraint after you include it in your organization policy. If you have existing repositories in non-compliant locations, you must move your artifacts to a repository in a compliant location yourself and then delete the non-compliant repository.
An Artifact Registry cleanup policy defines criteria for automatically deleting artifact versions that you no longer need or keeping artifacts that you want to store indefinitely.
Cleanup policies are useful if you store many versions of your artifacts, but only need to keep specific versions that you release to production. You can define delete policies with criteria for deleting artifacts and keep policies with criteria for retaining artifacts.
If an artifact version matches criteria in both a delete policy and a keep policy, Artifact Registry applies the keep policy.
Delete policies delete artifacts matching the following required criteria:
Tag state: indicates if the policy should check for tagged artifacts or untagged artifacts. Artifacts are tagged when pushing or pulling an image to or from a repository. For more on Docker tags, see Container concepts.
Formats that don't support tags are treated as untagged. Tagged artifacts
in repositories with immutable tags enabled cannot be deleted.
For more information on tag state as it applies to cleanup policies, see the TagState reference.
You can use any of the following settings to configure your delete policy:
test, and staging would match
images with tags testenv and staging-1.5. tagState must be set to
TAGGED to use tag prefixes.
v1, v2 would match versions v1.5,
v2.0alpha, and v10.2.Enter or , between the prefixes.
For example red, blue would create two prefixes, red and blue and
would match artifact names red-team, redis,
and bluebird.30d is 30 days. You can specify durations of seconds,
minutes, hours, or days by appending s, m, h, or d respectively.30d is 30 days.Keep policies keep artifacts matching the same conditions as delete policies, or a set number of most recent versions.
For example, given a repository containing the following artifacts:
IMAGE: us-west1-docker.pkg.dev/my-project/release-xyz-v1
DIGEST: sha256:1b0a26bd07a3d17473d8d8468bea84015e27f87124b2831234581bce13f61370
TAGS:
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:10
IMAGE: us-west1-docker.pkg.dev/my-project/release-xyz-v2
DIGEST: sha256:6e494387c901caf429c1bf77bd92fb82b33a68c0e19f123456a3ac8d27a7049d
TAGS: latest
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:09
IMAGE: us-west1-docker.pkg.dev/my-project/release-v2
DIGEST: sha256:6e494387c901caf429c1bf77bd92fb82b33a68c0e19f123456a3ac8d27a7049d
TAGS: latest
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:09
If your Keep most recent versions policy is set to keep 3 versions of
packages matching the Package prefixes: {release-xyz}, only
release-xyz-v1, and release-xyz-v2 are kept.
Deletions triggered by delete policies count against your Artifact Registry per project delete request quota.
To create and apply cleanup policies to your repository, see Configure cleanup policies.
Artifact Registry supports hosting of images on the gcr.io domain. If you are
transitioning from Container Registry to Artifact Registry, you can set up
gcr.io repositories Artifact Registry to minimize changes to your existing
automation and workflows. These repositories provide:
gcr.io domain.For more information, see Transition to repositories with gcr.io domain support
There are two general approaches for setting up your repositories in multi-project organizations.
Create all repositories in a single project and then grant access to principals from other projects at the repository level. This approach can be more effective when a single person or team handles repository administration and repository access across your organization.
It can also simplify setup of virtual repositories since you only need to enable and manage a single instance of Artifact Registry.
Create repositories in projects that store and download artifacts. This approach might be required when you have data governance policies or trust boundaries that require more project-level separation and control of resources.
Repositories are only accessible with appropriate permissions unless you configure the repository for public access. You can grant permissions at the project or repository level.
Some Google Cloud services use default service accounts with default permissions to repositories in the same Google Cloud project. However, these default might not be suitable for your software development process or might not comply with security or policy requirements in your organization. Your repository administrator must explicitly grant these services access to repositories if:
For other principals that require access to repositories, your repository administrator must grant access. Following the security principle of least privilege, grant the minimum required permissions. For example:
You can restrict artifact downloads with download rules. Download rules let you allow or deny artifact downloads from your repositories and packages. You can also set conditions so the rule applies to specific tags or versions.
For details on how downloads rules work, see the Restrict artifact downloads section of the Control access and protect artifacts overview.
Artifact Registry also supports organization policy constraints that can require CMEK to protect resources.
Labels provide a way to organize resources specific to a Google Cloud service. In Artifact Registry, you can add labels to repositories so that you can group them together or filter repository lists by label. For example, you can use labels to group repositories by development stage or by team for automation or billing purposes. For more information about creating and using repository labels, see Labelling repositories.
You can also apply tags to repositories. While labels are primarily for organizing and filtering service-specific resources, tags are for programmatic control of policies across a Google Cloud organization. For more information, see Tagging repositories.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-09 UTC.