Repository and image names

Artifact Registry uses a naming convention to identify repositories and images when you use the API, gcloud, and docker commands to interact with repositories.

Docker repositories

The full name for a docker repository is in the following format:

LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY

where:

  • LOCATION is the regional or multi-regional location of the repository.

  • PROJECT is your Google Cloud console project ID. If your project ID contains a colon (:) and you are working with a Docker repository, see Domain-scoped projects.

  • REPOSITORY is the name of the repository.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository format: docker
  • Repository name: my-repo
  • Project ID: my-project

The repository is specified as:

us-docker.pkg.dev/my-project/my-repo

Container image names

The full name for a container image is one of the following formats: 

LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

or

LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

or

LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

where:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE is the name of the image in the repository.
  • TAG is the tag for the image version that you want to pull.

  • IMAGE-DIGEST is the sha256 hash value of the image contents. In Google Cloud console, click on the specific image to see its metadata. The digest is listed as the Image digest.

    If you don't specify a tag or a digest, Artifact Registry looks for the image with the default tag latest. See Container image versions for information about versions.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: test
  • Tag: staging

This version of the image tagged with staging is specified as:

us-docker.pkg.dev/my-project/my-repo/test:staging

Container image versions

A registry can contain many container images, and these images can have different versions. To identify a specific version of an image, you can specify the image tag or digest. Tags are unique to one image within a registry. Digests are automatically generated, are unique to a version of an image, and have the form @[IMAGE_DIGEST], where [IMAGE_DIGEST] is the sha256 hash value of the image contents.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: test
  • Tag: staging
  • Digest: sha256:4d11e24ba8a615cc85a535daa17b47d3c0219f7eeb2b8208896704ad7f88ae2d

To identify the image with its tag, use:

us-docker.pkg.dev/my-project/my-repo/test:staging

To identify it with the digest, use:

us-docker.pkg.dev/my-project/my-repo/test@sha256:4d11e24ba8a615cc85a535daa17b47d3c0219f7eeb2b8208896704ad7f88ae2d

If your project ID contains a colon (:), see Domain-scoped projects below.

In the console, on the Images screen, the Tags column lists the image's tags. Click on the version of the image to see metadata, including the Image digest.

See Tagging Images for more information about tagging.

Domain-scoped projects

If your project is scoped to your domain, the project ID includes the name of the domain followed by a colon (:). Because of how Docker treats colons, you must replace the colon character with a forward slash when you specify an image digest in Artifact Registry. Identify images in these types of projects using the following format:

LOCATION-docker.pkg.dev/DOMAIN/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

For example, the project with ID example.com:my-project could have the following image:

us-docker.pkg.dev/example.com/my-project/my-repo/image-name