Artifact Registry Concepts

Review concepts and terms related to Artifact Registry.

An artifact is a software package, library, zip file, or any other type of file used for deploying applications. Examples are Python or Maven libraries. Artifacts are grouped into repositories, which are collections of related artifacts. For example, you could group several versions of a Maven artifact in a Maven repository, or upload your Python libraries to a Python repository.

Repository and Artifact Names in Artifact Registry

When you create a repository in which to group similar artifacts, you give it repository name <repo-name>. The name must start with a letter or underscore, followed by letters, numbers, hyphens, or underscores. Length can be 1–255 characters. Avoid entering confidential information.

Example: web-app-repo

If you leave the name blank, the system automatically generates a name that you can change later. An automatically generated name has the following pattern: artifactrepository<timestamp>

Example: artifactrepository20210423180901

When you upload an artifact to a repository, you specify a path and version for it. Based on your input, an artifact name is assigned to the artifact in the following format:


Example: project01/my-web-app/artifact-abc:1.0.0

  • The artifact path <artifact-path> is a user-defined path that describes the location of the artifact in the repository. Slashes don't create a directory structure, but you can use slashes to organize the repository.

    Example: project01/my-web-app/artifact-abc

  • The version <version> is the artifact version. Because of incremental updates to artifacts, you can assign versions to artifacts. This way, you can associate builds with the artifact versions and roll back to previous versions.

    Examples: 1.1.0 or 1.2-beta-2

An artifact name is truncated to a maximum length of 255.

Immutable Artifacts in Artifact Registry

When you create a repository, you can designate it as immutable, which means that the artifacts uploaded to it become immutable. These artifacts are used as-is and can't be replaced. Immutable repositories ensure the integrity of the artifacts. Following are some common use cases for immutable artifacts:

  • Rolling back a deployment: For a rollback, you use the exact files of the previous working version of a deployment. Immutable artifacts ensure that no one has changed the last working version after the artifacts were uploaded to the repository.
  • Contributing code: In a deployment project, to ensure that a developer's code change doesn't affect others, the best practice is to make all artifacts immutable. For example, if you have an image of a rabbit in website-image.png, no one can overwrite it with an image of a fox. Replacing an image doesn't break the code, but it changes the outcome. Instead of replacing an immutable artifact, you upload a new artifact.

Deleting an artifact and then using the same artifact name to upload a new artifact is the same as overwriting that artifact's content.

An immutable artifact can be deleted but can't be replaced. If you delete an immutable artifact, you can’t assign its name to another artifact. Therefore, you can’t upload a new artifact and assign it the deleted artifact's path and version. However, you can give it the same path with a new version.

If a repository isn't immutable, then the artifacts in it can be overwritten. For example, you can use mutable snapshots of immutable repositories for testing.

Artifact States in Artifact Registry

You can filter the artifacts in a repository for their state. Possible states are:


For example, before you name an artifact, you can filter for artifacts with a DELETED state. This way, you can ensure that when you upload a new artifact, you don't use a deleted artifact's name.

When you upload an artifact to a repository, Artifact Registry calculates the SHA256 digest for the artifact and adds it to the artifact's properties. The SHA256 digest is a 256-bit Secure Hash Algorithm.

Identifying Artifacts with Secure Hash in Artifact Registry

When you roll back or use an artifact in your code, compare its SHA256 digest to the artifact's SHA256 digest in the repository. If the artifacts have different SHA256 digests, then their content is different.