Tag Retention

As a project administrator, you can save storage capacity by defining rules to govern the number and retention period of artifacts stored in a repository. This allows you to keep only the necessary artifacts and discard those that are no longer required or have been superseded by a newer version. Managing your repository in this way can help ensure that only the most needed artifacts are kept, freeing up valuable storage space.

WARNING

The artifacts that are not covered by the retention rule will be deleted.

However, the operation is conducted at the artifact level. Artifacts that have more than one tag will be retained even if not all their tags are covered by the retention policy.

You can set tag retention rules for each repository in your project. With the following rules, you can identify which tags you would like to keep. It is important to note that you don’t actually define rules to explicitly remove tags; instead, any tags that are not eligible for retention are automatically discarded.

Multiple retention rules are executed with an OR logic applied between each rule. Each retention rule consists of three filters that are applied sequentially.

Retention Rule Definitions

Repository: Allows you to select the repositories for further processing. You can identify repositories that either match a name or name fragment, or exclude that name or name fragment from matching. Wild cards definition such as *repo, repo*, or ** are permitted.

Quantity to retain: adds the option to take the artifact push/pull count or number of days into consideration for your retention.
Specifying a maximum number of tags, or by specifying a maximum period for which to retain tags.

Tags to retain: Identify the tag on which to apply the rule. You can identify repositories that either match a name or name fragment, or exclude that name or name fragment from matching. Wild cards definition such as *repo, repo*, or ** are permitted. The checkbox is used to select whether untagged artifacts should be captured as part of the set of artifacts eligible for tag retention.

For information about how the definition and usage of Patterns such as ** see https://github.com/bmatcuk/doublestar#patterns.

Create a New Tag Retention Policy

• Inside a project, go to the Policy tab (1);
• Switch to TAG RETENTION (2);
• Click ADD RULE (3);

A dialogue window will appear:

Select Repos

To specify repositories where the policy should look for the tags to be retained:

• type certain repositories in separating them by commas or
• use a double- or single-starred pattern;
• select between matching and excluding from the dropdown to include or exclude specified repositories;

Select Tag Age or Number

To specify how artifacts should be selected for retention, use one of the following options from the second dropdown:

• to refer to the number of artifacts stored in a repo:
  • select retain the most recently pushed # artifacts and type in the number of artifacts to be retained in the COUNT field;
  • select retain the most recently pulled # artifacts and type in the number of artifacts to be retained in the COUNT field;
• to refer to the artifacts “age”:
  • select retain the artifacts pushed within the last # days and fill in the DAYS field;
  • select retain the artifacts pulled within the last # days and fill in the DAYS field;
• select retain always will keep the artifacts and tags forever.

Select Tags by Name

To specify the tags to be retained:

• type in certain tags separated by commas or
• use a double- or single-starred pattern;
• select between matching and excluding to include or exclude selected tags;
• check untagged artifacts if you want to include artifacts that have no tag.

Manage Tag Retention Rules

You can edit, disable/enable, and delete a tag retention rule using the Action button next to each rule. Disabled rules will be marked with a red exclamation mark.

Run Retention Rules

Retention rules do nothing until they are run proactively. Indeed, it means that no tags or artifacts are deleted before you run a retention rule. You can do it either manually or create a schedule for it.

Run the Retention Manually

If you want the retention to take an effect immediately, you can use the RUN NOW (1) button. But, before doing this, we highly recommend using DRY RUN (2) which only simulates the retention policy execution and provides a log (4) describing once again which artifacts and tags are to be deleted or retained. Use ABORT (3) to stop an execution. Example of the log data:

2021-08-12T14:27:34Z [INFO] [/pkg/retention/job.go:83]: Run retention process.
 Repository: library/test 
 Rule Algorithm: or 
 Dry Run: true
2021-08-12T14:27:34Z [INFO] [/pkg/retention/job.go:98]: Load 2 candidates from repository library/test
2021-08-12T14:27:34Z [INFO] [/pkg/retention/job.go:201]: 
|                                 Digest                                  |   Tag    | Kind  | Labels |     PushedTime      |     PulledTime      |     CreatedTime     | Retention |
|-------------------------------------------------------------------------|----------|-------|--------|---------------------|---------------------|---------------------|-----------|
| sha256:1b26826f602946860c279fce658f31050cff2c596583af237d971f4629b57792 | 4.0,test | image |        | 2021/08/12 14:26:29 | 2021/08/11 14:32:52 | 2021/08/11 08:30:49 | RETAIN    |
| sha256:1649f969e17dff21275d1e227581fd492c77c9d856f989c2a1188a5798f6dfd2 | 2.0,1.0  | image |        | 2021/08/04 12:47:31 | 2021/08/11 14:32:53 | 2021/07/29 12:02:18 | DEL       |

Schedule the Execution of the Retention Rule

To make the retention execution happen automatically and on a regular basis, you can create a schedule for the policy to run.

• Go to the Schedule;
• Click EDIT;
• Select a schedule from the dropdown;

• If you select CRON, you need to create specify the frequency using the online CRON formatter (copy and paste the value from it);
  • Alternatively, consult our short knowledge article by clicking on the i icon and create the schedule by yourself.