Artifact Registry Concepts

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:

<artifact-path>:<version>

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.

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.

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.

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

• AVAILABLE
• DELETED

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.