Document tag edge-cases

[bdelavega-maralytix]

Specifically I'm wondering:
Will adding tags replace existing tags on an image?
Will adding an existing tag fail?

[shrink]

@bdelavega-maralytix Hi Bill, thank you for your interest in the action.

The intention of this action was to provide a way to add a new tag to an image in a registry in a way that does not modify the image or create a new image: it should add a new tag only.

Q: Will adding tags replace existing tags on an image?
A: No, existing tags will remain as-is

Q: Will adding an existing tag fail?
A: That depends on the behaviour of the registry. Some registries support immutable tags which would block any attempt to re-use a tag, however, most registries (including Docker's and GitHub's) allow for a tag to be re-used. Therefore, an attempt to use a tag for a second time, will "move" the tag.

What's your use case: are you hoping to prevent a tag from being re-assigned? I could add an option to guard against that, however, I suspect that's something you'd typically want to happen at the registry level (due to the potential for race conditions when interacting with the registry API, which is what this action does).

[shrink]

Actually, it might be helpful for me to describe how a Docker registry works. An image is represented by a manifest: a manifest is stored in a repository at one or more locations. The manifest can be accessed using the digest hash (e.g: sha256:7ea108539c53d2e601b17c23d9f3b0aacd627c3873eb1ef52187dd71a41ba061) and by one or more tags (e.g: latest v1.0.0).

This action uses the Docker registry API to push the target image's manifest to one or more tags. Therefore, unless you specify tags that already exist in your image's repository there will only be the creation of new tags. The logic of the action is:

1. Download a copy of the target image manifest
2. Push a copy of the image manifest to each of the specified tags

[bdelavega-maralytix]

Thanks a ton for answering so quickly!

My use case is this: our build process puts images into a private GitHub registry with some tags. Later on, if some tests pass, the image is deployed to a staging environment. Later it may or may not go to production. I want to tag the images when they're deployed (e.g. with stage), so that I can identify old, unused images to delete. We plan to keep a few older images in case we need to rollback.

Your answers fit the need well.

I still need to find a way to remove tags, but that's less sensitive because it will be a separate process from the build/test/deploy scripts. Probably a daily cron job.

[shrink]

@bdelavega-maralytix You might find snok/container-retention-policy helpful. I haven't used it personally, however, after a brief look around the documentation, it looks ideal for cleaning up stale images. The untagged-only option would probably work well alongside your use of the stage tag.