Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Image tags overview

An image tag refers to a label or identifier assigned to a specific version or variant of a container image. Container images are typically composed of multiple layers that represent different parts of the image. Image tags are used to differentiate between different versions of an image or to provide additional information about the image.

Image tags have the following benefits:

  • Versioning and Releases: Image tags allow you to denote different versions or releases of an application or software. For example, you might have an image tagged as v1.0 to represent the initial release and v1.1 for an updated version. This helps in maintaining a clear record of image versions.
  • Rollbacks and Testing: If you encounter issues with a new image version, you can easily revert to a previous version by specifying its tag. This is helpful during debugging and testing phases.
  • Development Environments: Image tags are beneficial when working with different environments. You might use a dev tag for a development version, qa for quality assurance testing, and prod for production, each with their respective features and configurations.
  • Continuous Integration/Continuous Deployment (CI/CD): CI/CD pipelines often utilize image tags to automate the deployment process. New code changes can trigger the creation of a new image with a specific tag, enabling seamless updates.
  • Feature Branches: When multiple developers are working on different features or bug fixes, they can create distinct image tags for their changes. This helps in isolating and testing individual features.
  • Customization: You can use image tags to customize images with different configurations, dependencies, or optimizations, while keeping track of each variant.
  • Security and Patching: When security vulnerabilities are discovered, you can create patched versions of images with updated tags, ensuring that your systems are using the latest secure versions.
  • Dockerfile Changes: If you modify the Dockerfile or build process, you can use image tags to differentiate between images built from the previous and updated Dockerfiles.

Overall, image tags provide a structured way to manage and organize container images, enabling efficient development, deployment, and maintenance workflows.

8.1. Viewing image tag information by using the UI
Copy link

Use the following procedure to view image tag information using the v2 UI.

Prerequisites

  • You have pushed an image tag to a repository.

Procedure

  1. On the v2 UI, click Repositories.
  2. Click the name of a repository.

  3. Click the name of a tag. You are taken to the Details page of that tag. The page reveals the following information:

    • Name
    • Repository
    • Digest
    • Vulnerabilities
    • Creation
    • Modified
    • Size
    • Labels
    • How to fetch the image tag
  4. Click Security Report to view the tag’s vulnerabilities. You can expand an advisory column to open up CVE data.
  5. Click Packages to view the tag’s packages.
  6. Click the name of the repository to return to the Tags page.

Model card information can be viewed on the v2 UI. Model cards are essentially markdown (.md) files with additional metadata that provide information about a machine learning application. To view model card information, a manifest must have an annotation that is defined in your config.yaml file (for example, application/x-mlmodel) and include a model card stored as a layer in the manifest. When these conditions are met, a Model Card tab appears on the Details page of a tag.

Prerequisites

  • You have pushed an artifact of that annotation type, and it includes a model card (.md) file.

Procedure

  1. Update your config.yaml file to include the following information:

    Example model card YAML

    FEATURE_UI_MODELCARD: true
    1 
    
UI_MODELCARD_ARTIFACT_TYPE: application/x-mlmodel
    2 
    
UI_MODELCARD_ANNOTATION:
    3 
    
  org.opencontainers.image.description: "Model card metadata"
UI_MODELCARD_LAYER_ANNOTATION:
    4 
    
  org.opencontainers.image.title: README.md
    Copy to Clipboard Toggle word wrap

    1
    Enables the Model Card image tab in the UI.
    2
    Defines the model card artifact type. In this example, the artifact type is application/x-mlmodel.
    3
    Optional. If an image does not have an artifactType defined, this field is checked at the manifest level. If a matching annotation is found, the system then searches for a layer with an annotation matching UI_MODELCARD_LAYER_ANNOTATION.
    4
    Optional. If an image has an artifactType defined and multiple layers, this field is used to locate the specific layer containing the model card.
  2. Push an artifact of that annotation type, and one that includes a model card (.md) file, to your repository.
  3. On the v2 UI, click Repositories.
  4. Click the name of a repository.
  5. Click the name of a tag. You are taken to the Details page of that tag.

  6. Click ModelCard to view information about the image. For example:

    Modelcard information
    View larger image
    Modelcard information

Use the following procedure to view image tag information by using the API

Prerequisites

Procedure

  1. To obtain tag information, you must use the GET /api/v1/repository/{repository} API endpoint and pass in the includeTags parameter. For example: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>?includeTags=true
    Copy to Clipboard Toggle word wrap

    Example output

    {"namespace": "quayadmin", "name": "busybox", "kind": "image", "description": null, "is_public": false, "is_organization": false, "is_starred": false, "status_token": "d8f5e074-690a-46d7-83c8-8d4e3d3d0715", "trust_enabled": false, "tag_expiration_s": 1209600, "is_free_account": true, "state": "NORMAL", "tags": {"example": {"name": "example", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "test": {"name": "test", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}}, "can_write": true, "can_admin": true}
    Copy to Clipboard Toggle word wrap

  2. Alternatively, you can use the GET /api/v1/repository/{repository}/tag/ endpoint. For example: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737029, "end_ts": 1718737153, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:57:09 -0000", "expiration": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737018, "end_ts": 1718737029, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:56:58 -0000", "expiration": "Tue, 18 Jun 2024 18:57:09 -0000"}, {"name": "sample_tag", "reversion": false, "start_ts": 1718736147, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:42:27 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1717680780, "end_ts": 1718737018, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000", "expiration": "Tue, 18 Jun 2024 18:56:58 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

You can add a new tag to an image in Red Hat Quay.

Procedure

  1. On the Red Hat Quay v2 UI dashboard, click Repositories in the navigation pane.
  2. Click the name of a repository that has image tags.
  3. Click the menu kebab, then click Add new tag.

  4. Enter a name for the tag, then, click Create tag.

    The new tag is now listed on the Repository Tags page.

You can add a new tag, or restore an old one, to an image by using the API.

Prerequisites

Procedure

  1. You can change which image a tag points to or create a new tag by using the PUT /api/v1/repository/{repository}/tag/{tag} command: 

    $ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "manifest_digest": "<manifest_digest>"
  }' \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
    Copy to Clipboard Toggle word wrap

    Example output

    "Updated"
    Copy to Clipboard Toggle word wrap

  2. You can restore a repository tag to its previous image by using the POST /api/v1/repository/{repository}/tag/{tag}/restore command. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "manifest_digest": <manifest_digest>
  }' \
  quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore
    Copy to Clipboard Toggle word wrap

    Example output

    {}
    Copy to Clipboard Toggle word wrap

  3. To see a list of tags after creating a new tag you can use the GET /api/v1/repository/{repository}/tag/ command. For example: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
   https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

8.5. Adding and managing labels by using the UI
Copy link

Administrators can add and manage labels for tags by using the following procedure.

Procedure

  1. On the v2 UI dashboard, click Repositories in the navigation pane.
  2. Click the name of a repository that has image tags.
  3. Click the menu kebab for an image and select Edit labels.
  4. In the Edit labels window, click Add new label.

  5. Enter a label for the image tag using the key=value format, for example, com.example.release-date=2023-11-14.

    Note

    The following error is returned when failing to use the key=value format: Invalid label format, must be key value separated by =.

  6. Click the whitespace of the box to add the label.
  7. Optional. Add a second label.
  8. Click Save labels to save the label to the image tag. The following notification is returned: Created labels successfully.
  9. Optional. Click the same image tag’s menu kebab Edit labels X on the label to remove it; alternatively, you can edit the text. Click Save labels. The label is now removed or edited.

8.6. Adding and managing labels by using the API
Copy link

Red Hat Quay administrators can add and manage labels for tags with the API by using the following procedure.

Prerequisites

Procedure

  1. Use the GET /api/v1/repository/{repository}/manifest/{manifestref} command to retrieve the details of a specific manifest in a repository: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>
    Copy to Clipboard Toggle word wrap

  2. Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/labels command to retrieve a list of labels for a specific manifest: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels
    Copy to Clipboard Toggle word wrap

    Example output

    {"labels": [{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}, {"id": "2d34ec64-4051-43ad-ae06-d5f81003576a", "key": "org.opencontainers.image.version", "value": "1.36.1-glibc", "source_type": "manifest", "media_type": "text/plain"}]}
    Copy to Clipboard Toggle word wrap

  3. Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid} command to obtain information about a specific manifest: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<label_id>
    Copy to Clipboard Toggle word wrap

    Example output

    {"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}
    Copy to Clipboard Toggle word wrap

  4. You can add an additional label to a manifest in a given repository with the POST /api/v1/repository/{repository}/manifest/{manifestref}/labels command. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "key": "<key>",
    "value": "<value>",
    "media_type": "<media_type>"
  }' \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels
    Copy to Clipboard Toggle word wrap

    Example output

    {"label": {"id": "346593fd-18c8-49db-854f-4cb1fb76ff9c", "key": "example-key", "value": "example-value", "source_type": "api", "media_type": "text/plain"}}
    Copy to Clipboard Toggle word wrap

  5. You can delete a label using the DELETE /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid} command: 

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<labelid>
    Copy to Clipboard Toggle word wrap

    This command does not return output in the CLI. You can use one of the commands above to ensure that it was successfully removed.

8.7. Setting tag expirations
Copy link

Image tags can be set to expire from a Red Hat Quay repository at a chosen date and time using the tag expiration feature. This feature includes the following characteristics:

  • When an image tag expires, it is deleted from the repository. If it is the last tag for a specific image, the image is also set to be deleted.
  • Expiration is set on a per-tag basis. It is not set for a repository as a whole.
  • After a tag is expired or deleted, it is not immediately removed from the registry. This is contingent upon the allotted time designed in the time machine feature, which defines when the tag is permanently deleted, or garbage collected. By default, this value is set at 14 days, however the administrator can adjust this time to one of multiple options. Up until the point that garbage collection occurs, tags changes can be reverted.

The Red Hat Quay superuser has no special privilege related to deleting expired images from user repositories. There is no central mechanism for the superuser to gather information and act on user repositories. It is up to the owners of each repository to manage expiration and the deletion of their images.

Tag expiration can be set up in one of three ways:

  • By setting the quay.expires-after= label in the Dockerfile when the image is created. This sets a time to expire from when the image is built. This label only works for image manifests.
  • By setting the quay.expires-after= annotation label in the Dockerfile when the image is created. --annotation can be passed in for both image manifests and image indexes.

  • By selecting an expiration date on the Red Hat Quay UI. For example:

    Change tag expiration under the Options icon or from the EXPIRES column

Setting tag expirations can help automate the cleanup of older or unused tags, helping to reduce storage space.

8.7.1. Setting tag expiration from a repository
Copy link

Procedure

  1. On the Red Hat Quay v2 UI dashboard, click Repositories in the navigation pane.
  2. Click the name of a repository that has image tags.
  3. Click the menu kebab for an image and select Change expiration.
  4. Optional. Alternatively, you can bulk add expiration dates by clicking the box of multiple tags, and then select Actions Set expiration.
  5. In the Change Tags Expiration window, set an expiration date, specifying the day of the week, month, day of the month, and year. For example, Wednesday, November 15, 2023. Alternatively, you can click the calendar button and manually select the date.
  6. Set the time, for example, 2:30 PM.
  7. Click Change Expiration to confirm the date and time. The following notification is returned: Successfully set expiration for tag test to Nov 15, 2023, 2:26 PM.

  8. On the Red Hat Quay v2 UI Tags page, you can see when the tag is set to expire. For example:

    Red Hat Quay v2 UI tag expiration

8.7.2. Setting tag expiration from a Dockerfile
Copy link

You can add a label, for example, quay.expires-after=20h to an image tag by using the docker label command to cause the tag to automatically expire after the time that is indicated. The following values for hours, days, or weeks are accepted:

  • 1h
  • 2d
  • 3w

Expiration begins from the time that the image is pushed to the registry.

Procedure

  • Enter the following docker label command to add a label to the desired image tag. The label should be in the format quay.expires-after=20h to indicate that the tag should expire after 20 hours. Replace 20h with the desired expiration time. For example: 

    $ docker label quay.expires-after=20h quay-server.example.com/quayadmin/<image>:<tag>
    Copy to Clipboard Toggle word wrap

8.7.3. Setting tag expiration using annotations
Copy link

You can add an annotation, for example, quay.expires-after=20h, to an image tag using the --annotation flag when pushing an image to the registry. This annotation causes the tag to automatically expire after the specified time. The annotation can be applies to both image manifests and image indexes. The following values for hours, days, or weeks are accepted:

  • 1h
  • 2d
  • 3w

Expiration begins from the time that the image is pushed to the registry.

Note

Using the --annotation flag is simplest using the oras CLI tool.

Prerequisites

  • You have downloaded the oras CLI. For more information, see Installation.

Procedure

  1. Enter the following oras push --annotation command to add an annotation to the desired image tag. The annotation should be in the format quay.expires-after=<value> to indicate that the tag should expire the set time. For example: 

    $ oras push --annotation quay.expires-after=<value> \
  <quay-server.example.com>/<organization>/<repository>:<tag> \
  <file_path>:<media_type>
    Copy to Clipboard Toggle word wrap

    Example output

    ✓ Uploaded  hello.txt                                                                                                       12/12  B 100.00%  321ms
  └─ sha256:74b9e308133afb3bceae961097cb2aa481483869d695ce1414cd2bc7f046027c
✓ Uploaded  application/vnd.oci.empty.v1+json                                                                                 2/2  B 100.00%  328ms
  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                                    620/620  B 100.00%     0s
  └─ sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3
Pushed [registry] quay-server.example.com/fortestuser/busybox:test2
ArtifactType: application/vnd.unknown.artifact.v1
    Copy to Clipboard Toggle word wrap

  2. Confirm that the expiration date has been applied by checking the Red Hat Quay UI, or by entering the following command: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/?specificTag=<tag>" \
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test2", "reversion": false, "start_ts": 1743706344, "end_ts": 1743778344, "manifest_digest": "sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3", "is_manifest_list": false, "size": 12, "last_modified": "Thu, 03 Apr 2025 18:52:24 -0000", "expiration": "Fri, 04 Apr 2025 14:52:24 -0000"}, {"name": "test2", "reversion": false, "start_ts": 1742493776, "end_ts": 1743706344, "manifest_digest": "sha256:d80aa3d7f5f5388cfae543b990d3cd3d47ff51c48ef29ff66102427bf7bc0a88", "is_manifest_list": false, "size": 2266046, "last_modified": "Thu, 20 Mar 2025 18:02:56 -0000", "expiration": "Thu, 03 Apr 2025 18:52:24 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

8.7.4. Removing tag expiration using annotations
Copy link

With the oras CLI tool, you can unset previously established expiration times.

Prerequisites

  • You have downloaded the oras CLI. For more information, see Installation.
  • You have pushed an image with the quay.expires-after=<value> annotation.

Procedure

  1. Enter the following oras push --annotation command to remove an annotation to the desired image tag. The annotation should be in the format quay.expires-after=never. For example: 

    $ oras push --annotation quay.expires-after=never \
  <quay-server.example.com>/<organization>/<repository>:<tag> \
  <file_path>:<media_type>
    Copy to Clipboard Toggle word wrap

    Example output

    ✓ Uploaded  hello.txt                                                                                                       12/12  B 100.00%  321ms
  └─ sha256:74b9e308133afb3bceae961097cb2aa481483869d695ce1414cd2bc7f046027c
✓ Uploaded  application/vnd.oci.empty.v1+json                                                                                 2/2  B 100.00%  328ms
  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                                    620/620  B 100.00%     0s
  └─ sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3
Pushed [registry] quay-server.example.com/fortestuser/busybox:test2
ArtifactType: application/vnd.unknown.artifact.v1
    Copy to Clipboard Toggle word wrap

  2. The latest manifest will no longer have an expiration time. Confirm that the expiration date has been removed by checking the Red Hat Quay UI, or by entering the following command: 

    {"tags": [{"name": "test2", "reversion": false, "start_ts": 1743708135, "manifest_digest": "sha256:19e3a3501b4125cce9cb6bb26ac9207c325259bef94dc66490b999f93c4c83a9", "is_manifest_list": false, "size": 12, "last_modified": "Thu, 03 Apr 2025 19:22:15 -0000"}, {"name": "test2", "reversion": false, "start_ts": 1743706344, "end_ts": 1743708135}]}
    Copy to Clipboard Toggle word wrap

    Note that no expiration time is listed.

8.7.5. Setting tag expirations by using the API
Copy link

Image tags can be set to expire by using the API.

Prerequisites

Procedure

  • You can set when an image a tag expires by using the PUT /api/v1/repository/{repository}/tag/{tag} command and passing in the expiration field: 

    $ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "expiration": "<seconds since epoch>"
  }' \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
    Copy to Clipboard Toggle word wrap

    Example output

    "Updated"
    Copy to Clipboard Toggle word wrap

8.8. Fetching an image by tag or digest
Copy link

Red Hat Quay offers multiple ways of pulling images using Docker and Podman clients.

Procedure

  1. Navigate to the Tags page of a repository.
  2. Under Manifest, click the Fetch Tag icon.

  3. When the popup box appears, users are presented with the following options:

    • Podman Pull (by tag)
    • Docker Pull (by tag)
    • Podman Pull (by digest)

    • Docker Pull (by digest)

      Selecting any one of the four options returns a command for the respective client that allows users to pull the image.

  4. Click Copy Command to copy the command, which can be used on the command-line interface (CLI). For example: 

    $ podman pull quay-server.example.com/quayadmin/busybox:test2
    Copy to Clipboard Toggle word wrap

Red Hat Quay offers a comprehensive history of images and their respective image tags.

Procedure

  1. On the Red Hat Quay v2 UI dashboard, click Repositories in the navigation pane.
  2. Click the name of a repository that has image tags.

  3. Click Tag History. On this page, you can perform the following actions:

    • Search by tag name
    • Select a date range
    • View tag changes
    • View tag modification dates and the time at which they were changed

Red Hat Quay offers a comprehensive history of images and their respective image tags.

Prerequisites

Procedure

  1. Enter the following command to view tag history by using the GET /api/v1/repository/{repository}/tag/ command and passing in one of the following queries:

    • onlyActiveTags=<true/false>: Filters to only include active tags.
    • page=<number>: Specifies the page number of results to retrieve.
    • limit=<number>: Limits the number of results per page.

    • specificTag=<tag_name>: Filters the tags to include only the tag with the specified name. 

      $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/tag/?onlyActiveTags=true&page=1&limit=10"
      Copy to Clipboard Toggle word wrap

      Example output

      {"tags": [{"name": "test-two", "reversion": false, "start_ts": 1717680780, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}
      Copy to Clipboard Toggle word wrap

  2. By using the specificTag=<tag_name> query, you can filter results for a specific tag. For example: 

    $ curl -X GET   -H "Authorization: Bearer <bearer_token>"   -H "Accept: application/json"   "<quay-server.example.com>/api/v1/repository/quayadmin/busybox/tag/?onlyActiveTags=true&page=1&limit=20&specificTag=test-two"
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

8.11. Deleting an image tag
Copy link

Deleting an image tag removes that specific version of the image from the registry.

To delete an image tag, use the following procedure.

Procedure

  1. On the Repositories page of the v2 UI, click the name of the image you want to delete, for example, quay/admin/busybox.
  2. Click the More Actions drop-down menu.

  3. Click Delete.

    Note

    If desired, you could click Make Public or Make Private.

  4. Type confirm in the box, and then click Delete.

  5. After deletion, you are returned to the Repositories page.

    Note

    Deleting an image tag can be reverted based on the amount of time allotted assigned to the time machine feature. For more information, see "Reverting tag changes".

8.12. Deleting an image by using the API
Copy link

You can delete an old image tag by using the API.

Prerequisites

Procedure

  1. You can delete an image tag by using the DELETE /api/v1/repository/{repository}/tag/{tag} command: 

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
    Copy to Clipboard Toggle word wrap

    This command does not return output in the CLI. Continue on to the next step to return a list of tags.

  2. To see a list of tags after deleting a tag, you can use the GET /api/v1/repository/{repository}/tag/ command. For example: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
   https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

8.13. Reverting tag changes by using the UI
Copy link

Red Hat Quay offers a comprehensive time machine feature that allows older images tags to remain in the repository for set periods of time so that they can revert changes made to tags. This feature allows users to revert tag changes, like tag deletions.

Procedure

  1. On the Repositories page of the v2 UI, click the name of the image you want to revert.
  2. Click the Tag History tab.
  3. Find the point in the timeline at which image tags were changed or removed. Next, click the option under Revert to restore a tag to its image.

8.14. Reverting tag changes by using the API
Copy link

Red Hat Quay offers a comprehensive time machine feature that allows older images tags to remain in the repository for set periods of time so that they can revert changes made to tags. This feature allows users to revert tag changes, like tag deletions.

Prerequisites

Procedure

  1. You can restore a repository tag to its previous image by using the POST /api/v1/repository/{repository}/tag/{tag}/restore command. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "manifest_digest": <manifest_digest>
  }' \
  quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore
    Copy to Clipboard Toggle word wrap

    Example output

    {}
    Copy to Clipboard Toggle word wrap

  2. To see a list of tags after restoring an old tag you can use the GET /api/v1/repository/{repository}/tag/ command. For example: 

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
   https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
    Copy to Clipboard Toggle word wrap

    Example output

    {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
    Copy to Clipboard Toggle word wrap

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat