Shape the future of software delivery and make your voice heard by taking the 2023 State of DevOps survey.

Create standard repositories

This page describes how to create Artifact Registry standard repositories.

Standard repositories are repositories for your private artifacts. You upload artifacts to and download artifacts directly from these repositories.

There are two other repository modes that are available for some artifact formats:

  • Remote store artifacts from external sources such as Docker Hub, Maven Central, or PyPI.
  • Virtual act as a single access point to download, install, or deploy artifacts that are in upstream standard or remote repositories.

Each repository can contain artifacts for a single supported format.

Before you begin

  1. Enable Artifact Registry, including enabling the Artifact Registry API and installing Google Cloud CLI.
  2. (Optional) Configure defaults for gcloud commands.
  3. If you require customer-managed-encryption keys (CMEK) to encrypt repository content, create and enable a key in Cloud KMS for the repository.

Required roles

To get the permissions that you need to create repositories, ask your administrator to grant you the Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin) IAM role on the Google Cloud project. For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a standard repository

When you create a repository, you must configure the following settings that cannot be changed after the repository is created:

  • Artifact format.
  • Repository mode, if multiple modes are available for the selected format.
  • Repository location.
  • Encryption with Google-managed keys or customer-managed encryption keys. Artifact Registry uses Google-managed encryption keys by default.

Artifact Registry enforces organization policy constraints that require CMEK to encrypt resources or limit which Cloud KMS keys can be used for CMEK protection.

Create a repository using Google Cloud console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. Click Create Repository.

  3. Specify the repository name. For each repository location in a project, repository names must be unique.

  4. Select the repository format.

  5. If multiple repository modes are available, select Standard.

  6. Maven only: Configure the version policy.

    1. Choose a version policy:

      • None - No version policy. Store both release and snapshot packages.
      • Release - Store only release packages.
      • Snapshot - Store only snapshot packages.

    2. If you want a snapshot repository to accept non-unique snapshots that overwrite existing versions in the repository, select Allow snapshot overwrites.

  7. Under Location Type, choose the location for the repository:

    1. Choose the location type: Region or Multi-Region. The list of locations changes to reflect your selection.

    2. In the Region or Multi-region list, select a location.

    For information about location types and supported locations, see Repository locations

  8. Add a description for the repository. Descriptions help to identify the purpose of the repository and the kind of artifacts it contains.

    Do not include sensitive data, since repository descriptions are not encrypted.

  9. If you want to use labels to organize your repositories, click Add Label and enter the key-value pair for the label. You can add, edit, or remove labels after you create the repository.

  10. In the Encryption section, choose the encryption mechanism for the repository.

    • Google-managed key - Encrypt repository content with a Google-managed encryption key.

    • Customer-managed key - Encrypt repository content with a key that you control through Cloud Key Management Service. For key setup instructions, see Setting up CMEK for repositories.

      1. For Docker repositories, the Immutable Tags setting (Preview) indicates how tags are associated with versions of images. A user with the Artifact Registry administrator role can change the setting after the repository is created.

        • By default this setting is disabled. Tags are mutable, meaning that The image version that tag points to can change. Deleting images, removing tags, and changing the version of an image that a tag points to are permitted.
        • If this setting is enabled, tags are immutable. A tag must always point to the same image digest. The following actions are not permitted:
        • Delete a tagged image. Deleting untagged images is still permitted.
        • Remove a tag from an image.
        • Push an image with a tag that is already used by another version of the image in the repository.

      2. Click Create.

Artifact Registry creates the repository and adds it to the list of repositories.

After you have created the repository:

Create a repository using the Google Cloud CLI

Run the command to create a new repository.

Apt 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=apt \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

Docker 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --tag-immutability=TAG-SETTING
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • TAG-SETTING indicates how tags are associated with versions of images. A user with the Artifact Registry administrator role can change the setting after the repository is created.

    • The default setting is false. The image version that tag points to can change. Deleting images, removing tags, and changing the version of an image that a tag points to are permitted.
    • When set to true, a tag must always point to the same image digest. The following actions are not permitted:
    • Delete a tagged image. Deleting untagged images is still permitted.
    • Remove a tag from an image.
    • Push an image with a tag that is already used by another version of the image in the repository.

  • --async returns immediately, without waiting for the operation in progress to complete.

KubeFlow Pipelines 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=kfp \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

Maven

By default, Maven repositories store both snapshot and release versions of packages. You can specify a version policy to create a snapshot or release repository.

To create a repository that stores snapshots and releases, run the command:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=maven \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

To store snapshot and release versions in different repositories, specify the version policy in the command:

gcloud artifacts repositories create REPOSITORY \
  --repository-format=maven \
  [--location=LOCATION] \
  [--description="DESCRIPTION"] \
  [--kms-key=KMS-KEY] \
  [--version-policy=VERSION-POLICY] \
  [--allow-snapshot-overwrites] \
  [--async] \

The following flags are specific to Maven repositories:

--version-policy=VERSION-POLICY
Specifies the types of packages to store in the repository. You can set VERSION-POLICY to:
  • None - No version policy. Store both release and snapshot packages. If you do not include the --version-policy flag in your command, this is the default setting.
  • Release - Store only release packages.
  • Snapshot - Store only snapshot packages.
--allow-snapshot-overwrites
For snapshot repositories only. If you specify this flag, you can publish non-unique snapshots that overwrite existing versions in the repository.

npm 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=npm \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

Python 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=python \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

Yum 

gcloud artifacts repositories create REPOSITORY \
    --repository-format=yum \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --kms-key=KMS-KEY \
    --async
  • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

  • LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command:

    gcloud artifacts locations list

  • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

  • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

    projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

    Where

    • KMS-PROJECT is the project where your key is stored.
    • KMS-LOCATION is the location of the key.
    • KEY-RING is the name of the key ring.
    • KEY is the name of the key.

  • --async returns immediately, without waiting for the operation in progress to complete.

Artifact Registry creates your repository. Run the following command to view a description of the repository:

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

After you have created the repository:

Create a repository using Terraform

Use the google_artifact_registry_repository resource to create repositories. terraform-provider-google version 4.61.0 or newer is required.

If you are new to using Terraform for Google Cloud, see the Get Started - Google Cloud page on the HashiCorp website.

The following example defines the provider and a repository with the Terraform resource name my-repo.

Apt 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "apt"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

Docker 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "docker"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

KubeFlow Pipelines 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "kfp"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

Maven

If you do not specify a version policy, Artifact Registry creates a Maven repository that stores both snapshot and release versions of packages by default.

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "maven"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

To store snapshot and release versions in different repositories, specify a version policy for the repository using a maven_config block. This block supports the following settings:

  • version_policy sets the version policy with one of the following values:
    • VERSION_POLICY_UNSPECIFIED: Store snapshot and release packages. This is the default setting.
    • RELEASE: Store release packages only.
    • SNAPSHOT: Store snapshot packages only.
  • allow_snapshot_overwrites configures a repository with a SNAPSHOT version policy to accept non-unique snapshots that overwrite existing versions in the repository.

The following example defines a Maven repository with a release version policy.

provider "google" {
project = "my-project"
}

resource "google_artifact_registry_repository" "my-repo" {
provider = google-beta

location = "us-central1"
repository_id = "my-repo"
description = "Maven repository"
format = "MAVEN"
maven_config {
  version_policy = "RELEASE"
}
}

npm 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "npm"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

Python 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "python"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

Artifact Registry creates your repository. Run the following command to view a description of the repository:

gcloud artifacts repositories describe REPOSITORY \
  --location=LOCATION

Yum 

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = DESCRIPTION"
  format = "yum"
  kms_key_name = "KEY"
}

Where

  • PROJECT-ID is the Google Cloud project ID.
  • LOCATION is the repository location.
  • REPOSITORY is the repository name.
  • DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.

After you have created the repository:

Edit repository descriptions

You can change the repository description from Google Cloud console or the gcloud CLI.

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. In the repository list, select the repository and click Edit Repository.

  3. Edit the repository description and then click Save.

gcloud

To update the repository description, run the command:

gcloud artifacts repositories update REPOSITORY \
    --project=PROJECT] \
    --location=LOCATION \
    --description="DESCRIPTION"

Replace the following values:

  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • PROJECT is the Google Cloud project ID. If this flag is omitted, the current or default project is used.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
  • DESCRIPTION is a description for the repository.

What's next