The Tag Retention field controls how many overwrites of the same tag are saved in Artifactory. Tag overwriting occurs when you upload a new revision of a tag name that already exists in your repository: for instance, “latest”.
The Tag Retention limit applies to any tag name you overwrite, not just “latest”.
By default, this field is set to one (1), implying that if you upload a tag, Artifactory will not save the previous version of the tag that is being overwritten.
When setting this field to a value of 2 (or above), Artifactory will automatically make a copy of the existing tag in Artifactory before it is overwritten and rename it according to its SHA2 hash value. This field accepts any number that represents a limit of how many previous revisions of the same tag should be stored. This field also works according to FIFO (first in, first out) logic, meaning that once you overwrite your tag beyond the limit, the oldest tag revision will be removed.
If your artifactory instance has Trash Can enabled you will be able to retrieve your oldest overwritten tag according to its SHA2 hash value if needed.
Example of Tag Retention Usage
The following diagram shows what happens when you overwrite the same "Latest" tag over and over again three times:
1st push: Latest (Original)
2nd push: Latest (revision 2)
3rd push: Latest (revision 3)
In the diagrams, the green boxes = stored tags, and the gray boxes = deleted tags.
During this process, once we upload the Latest tag for the 2nd time, the original copy of Latest already stored in Artifactory is renamed according to its hash and continues to be stored in the system, making way for the updated revision of Latest that will use the “Latest” tag name. Then, when the 3rd revision of Tag1 is pushed, the 2nd revision of the second version is renamed as a SHA value.
Finally, when uploading the Latest tag for the 4th time, the number of overwritten tags exceeded the Tag Retention limit of 3, meaning that the oldest iteration of Latest tag (SHA 1), the original first push, will be removed.