Repositories

Creating an Image Repository

On the main Quay landing page:

  • Click the Create New Repository button.

create repo

  • Select the organization from the drop-down list, name the repository kafka, and set the visibility to Public.

repo config

  • Click Create Public Repository.

Pushing and Tagging an Image to the Repository

  • Pull an image from the public registry by running the podman pull command followed by the image name.

podman pull quay.io/strimzi/kafka:latest-kafka-4.0.0

  • Tag the image with a name and version number using the podman tag command.

podman tag quay.io/strimzi/kafka:latest-kafka-4.0.0 ${QUAY_HOSTNAME}/olleb/kafka:4.0.0

  • Sign in to your Quay repository using your account credentials, if you are not already signed in.

podman login ${QUAY_HOSTNAME}

  • Push the image to the Quay repository using the podman push command.

podman push ${QUAY_HOSTNAME}/olleb/kafka:4.0.0

  • Verify that the image has been successfully pushed to your Quay repository by confirming that the image is listed.

image pushed

Inspecting Image Layers

  • Navigate to the olleb/kafka repository.

  • Click the Tags icon.

  • Under the MANIFEST section of the 4.0.0 tag, click the SHA256 value to open the image layers dashboard.

image pushed2
img layers

Pulling an Image from the Repository

  • From the Quay dashboard, locate and select the olleb/kafka repository.

  • Click the Tags tab.

  • Select any of the repository’s tags and click the Fetch Tag icon.

fetchtagpre

  • From the Image Format drop-down menu, select Podman Pull (by tag) and click the Copy Command button.

fetchtag

  • Switch to a terminal, paste the command you copied from the Quay UI, and execute it. Ensure that Podman is installed on your system. Since the repository was created as Public, no login is required to pull the image.

Rolling Back an Image

Quay provides a convenient way to review the history of tags associated with an image repository and to roll back to a previous version when needed.

  • Create a new image repository as previously explained. In this case, create a public repository named olleb/rollback on Quay.

  • Build an image, tag it, and push it.

echo "FROM scratch" > Containerfile.rbk
podman build . -t rollback:1.0 -f Containerfile.rbk

podman tag localhost/rollback:1.0 ${QUAY_HOSTNAME}/olleb/rollback:latest
podman push ${QUAY_HOSTNAME}/olleb/rollback:latest

  • Verify that the image has been pushed to the Quay repository. Also, check the manifest digest and the layers.

rblatest1
rblayers1

  • Add a new layer to the Containerfile, rebuild the image, and overwrite the previous one by tagging and pushing it with the same remote tag.

echo "LABEL org.opencontainers.image.authors=[email protected]" >> Containerfile.rbk
podman build . -t rollback:2.0 -f Containerfile.rbk

podman tag localhost/rollback:2.0 ${QUAY_HOSTNAME}/olleb/rollback:latest
podman push ${QUAY_HOSTNAME}/olleb/rollback:latest

  • Verify that the new image has been pushed to the Quay repository, and check its manifest digest and layers in the Quay UI. You should observe that the manifest digest and layers differ from the previous image.

rblatest2
rblayers2

  • To roll back the image to the previous version, navigate to the Quay UI and click the Tag History option for the repository.

tagh

  • From there, select the tag of the previous image you want to restore, and click Revert to …​.

revert

  • Click the Restore Tag button. This will restore the tag to reference the previous image.

restoretag

  • To verify that the rollback was successful, go to the Tag History section in the Quay UI and confirm that the restored tag has the same manifest digest and layers as the previous image.

restored

Image Expiration

To configure an image tag to expire in Quay at a specific time or date, follow these steps:

  • Create a new image repository as previously explained. In this example, create a public repository named olleb/expiration.

  • Build a 1.0 image, tag it, and push it to the olleb/expiration repository.

echo "FROM scratch" > Containerfile.exp
podman build . -t exp:1.0 -f Containerfile.exp

podman tag localhost/exp:1.0 ${QUAY_HOSTNAME}/olleb/expiration:1.0
podman push ${QUAY_HOSTNAME}/olleb/expiration:1.0

  • The label quay.expires-after is used to specify the expiration time for a tag. The value can be defined in several formats, including a specific date and time, a relative time offset from image creation, or a relative time offset from tag creation. In this example, we use a relative time offset of 5m, which means the image will expire 5 minutes after being tagged as 2.0 and latest.

echo "LABEL org.opencontainers.image.authors=[email protected]" >> Containerfile.exp
echo "LABEL quay.expires-after=5m" >> Containerfile.exp
podman build . -t exp:2.0 -f Containerfile.exp

podman tag localhost/exp:2.0 ${QUAY_HOSTNAME}/olleb/expiration:2.0
podman push ${QUAY_HOSTNAME}/olleb/expiration:2.0

podman tag localhost/exp:2.0 ${QUAY_HOSTNAME}/olleb/expiration:latest
podman push ${QUAY_HOSTNAME}/olleb/expiration:latest

  • At this point, the olleb/expiration repository contains two images and three tags:

    • The 1.0 image has the 1.0 tag.

    • The 2.0 image has the 2.0 and latest tags. The 2.0 and latest tags are marked as expiring soon.

exp1

After 5 minutes, both tags will be automatically removed from the repository.

exp2
taghistoryautodeleted

  • To manually configure an expiration time, select the 1.0 tag. From the Actions drop-down list, select Change Expiration, and set the desired Expiration Date.

exp3
expirationdatetag
Alternatively, you can set the expiration by clicking the Options icon and selecting Change Expiration.

When a tag is about to expire, a warning message is displayed:

abouttoexpire
By default, the minimum expiration time is one hour, and the maximum is 104 weeks (approximately two years). If you need shorter or longer expiration limits, modify the LABELED_EXPIRATION_MINIMUM setting in the Config Bundle Secret of your registry instance. This property accepts values such as 60s (seconds), 5m (minutes), 24h (hours), 7d (days), or 2w (weeks). For more details, see 2.5.1 Configuring allowed OCI artifact types.

When a tag expires, it is deleted automatically.

However, even after a tag is deleted, the corresponding image can still be restored. When a tag is deleted and no other tags reference the same image, the image is not immediately removed — it is marked for garbage collection, which by default occurs after 14 days (2w). Quay’s garbage collection worker runs periodically and removes expired images once the configured Time Machine retention period has passed.

Because the image was stored under the olleb organization, you can check that value by navigating to /organization/olleb?tab=settings.

orgexptime

If the image was stored under a user account instead of an organization, the setting can be found under User Settings.

The Time Machine retention period can be modified by changing the TAG_EXPIRATION_OPTIONS array property, which must include the default expiration value DEFAULT_TAG_EXPIRATION in its list. An example of how to modify this value is provided in section 2.5.1 Configuring allowed OCI artifact types.

For example, with the following custom configuration:

expcfg

you will see:

customtm