Artifact Management
Retention Rules
Cloudsmith Retention Rules automate artifact data management by deleting packages that exceed a repository's configured limits. The configured limits can be based on:
- The number of packages (count)
- The total size of packages (bytes)
- The age of the package (days)
For more granular retention rules, artifacts in a repository can be divided up into distinct groups based on:
- Package Name
- Package Format
- Package Type
- A search query
Each repository has one configurable retention rule. This rule runs automatically when a new package is uploaded to a repository or when the latest uploaded package is resynced. Packages that fall outside of the repository’s configured limits will be deleted.
Retention Rules can be configured through the Cloudsmith Web App, the Cloudsmith API, or the Cloudsmith Terraform provider.
How Retention Rules work
Cloudsmith uses a "funnel" approach to identify which packages should be evaluated and deleted.
The “Funnel”: Identifying the evaluation groups
Cloudsmith enables granular control by evaluating packages as distinct subgroups rather than only treating the repository as a single unit. These groups are defined by your specific grouping configurations and package filters.
- If no groupings or filters are configured, the entire repository is processed as a single group.
- If multiple groupings or filters are enabled, they are applied hierarchically (nested). This creates specific, distinct groups for evaluation.
Grouping examples
| Groupings enabled | Resulting evaluation group(s) |
|---|---|
| Format | One group for every unique format in the repository. |
| Format + Name | One group for every unique name within each unique format in the repository. |
| Format + Type | One group for every unique type within each unique format in the repository. |
| Format + Name + Type | One group for every unique type within each unique name within each unique format in the repository. |
| Grouping + Package Filters | Only packages matching your search query within each enabled grouping. |
Note
Packages that have not synced successfully are ignored and excluded from the evaluation groups.
The deletion logic
Once the evaluation groups are identified, Cloudsmith checks them against your configured limits. If any limit is exceeded, deletions are triggered based on specific sorting methods:
| Limit Type | Sorting Method | Action |
|---|---|---|
| Limit by Count | Upload Date | Deletes the oldest packages until the count limit is met. “Oldest” is determined by the date the package was uploaded into Cloudsmith. Manually resyncing a cached package does not change the uploaded timestamp. |
| Limit by Days | Upload Date | Deletes packages older than X days. “Oldest” is determined by the date the package was uploaded into Cloudsmith. Manually resyncing a cached package does not change the uploaded timestamp. |
| Limit by Size | Semantic Version | Deletes the oldest packages until the group size is within limits. "Oldest" is determined using the semantic version of a package. |
When are Retention Rules evaluated?
Retention rules are not a continuous background process; they are event-driven. Evaluations only occur in response to specific triggers.
Trigger events
A Retention Rule is evaluated when:
- A new package is uploaded and successfully synchronized.
- The most recently uploaded package is manually resynced.
Note
Resyncing an older package will not trigger an evaluation.
The scope of evaluation
If you have configured groupings or package filters, the evaluation will be isolated to the distinct group associated with the package that invokes the trigger event.
- Group by Format: Uploading a Docker image triggers an evaluation only for Docker packages. All other package formats are excluded from the evaluation.
- Nested Groups (Format + Name): Uploading a Docker image named
test-dockeronly triggers an evaluation for that specific name within the Docker format.
Why some packages may persist
Because rules are event-driven and group-specific, packages may persist beyond the configured limits of a rule if there is no activity in their configured group.
For example: You have a 90-day retention rule and Group by Format enabled. You upload Python packages every day, but haven't uploaded a Docker image in 120 days. Your existing Docker images will not be deleted until a new Docker image is added or the latest Docker image is resynced, which triggers a Docker format evaluation.
For manual resyncs, the package that triggers the evaluation is never deleted.
How the cutoff date is calculated
When Limit by Days has been enabled, Cloudsmith will delete packages based on their upload date. Cloudsmith determines age-based deletions by using a "cutoff date" relative to the triggering package, not the current calendar date.
For example: If your most recent package is 100 days old and your limit is 90 days, the cutoff is 190 days. Only packages 190 days or older are identified for deletion.
The package used to trigger the evaluation (the latest one) is never deleted, even if it exceeds your configured parameter. To properly delete this 100-day-old package, you must upload a newer package to shift the cutoff date forward.
How many packages will be deleted
The processing limit is 10,000 deletions per evaluation cycle. Any packages exceeding this limit stay in the repository until the next evaluation is triggered.
Enabling Retention Rules
Retention Rules for a repository are disabled by default. Go to the Repository Settings and, in the left menu, click on Retention Rules. Then, click the Enable button in the colored banner.
To disable a Retention Rule, follow the same steps and click the Disable button in the colored banner.
Alternatively, you can use the Cloudsmith Repo Retention Partial Update to update a repository’s retention rule or configure a repository’s retention rule using the Cloudsmith Terraform Provider.
Configuration parameters
| Name | API | Description |
|---|---|---|
| Enabled | retention_enabled | Activates Retention Rules for the repository. A value of true enables the rule, and false disables it. |
| Group packages by Name | retention_group_by_name | If enabled, evaluation applies to groups of packages by name rather than all packages. |
| Group packages by Format | retention_group_by_format | If enabled, evaluation applies to packages by package formats rather than across all package formats. |
| Group packages by Type | retention_group_by_package_type | If enabled, evaluation applies to packages by package type (for example, binary vs source) rather than across all package types. |
| Package Filters (Query String) | retention_package_query_string | A package search expression that filters packages in each evaluation group. Refer to the Cloudsmith search syntax documentation. |
| Limit by Days | retention_days_limit | Number of days to retain a package. Packages older than this are selected for deletion. Set to 0 to disable. “Oldest” is based on upload date; resyncing doesn’t change it. |
| Limit by Count | retention_count_limit | Maximum number of packages to retain. Set to 0 to disable. If 5 packages meet criteria and the limit is 4, one is deleted; if only 3 meet criteria, none are deleted. “Oldest” is based on upload date; resyncing doesn’t change it. |
| Limit by Size | retention_size_limit | Maximum total size (bytes) of packages to retain. Set to 0 to disable. "Oldest" is determined using semantic version when reducing size. |
From the Cloudsmith Web App, use the sliders to configure limits, and then click the green Update button to apply the changes.
To learn how to configure retention rule parameters via our Cloudsmith API, visit the API reference documentation. For Terraform, visit the Cloudsmith Terraform Provider documentation.
Docker and multi-architecture images
We recommend exercising caution when applying retention rules to Docker repositories containing multi-architecture images.
Key considerations
Cloudsmith evaluates and deletes Docker artifacts as individual entities. Because the retention rule engine does not currently evaluate the relationship between a manifest list and its associated images, automated deletion can lead to repository inconsistency, such as:
- Broken manifests: A manifest list may remain while one or more of its required images are deleted.
- Orphaned images: Platform-specific images may remain after their parent manifest list has been removed.
Download statistics are not recorded against Docker Manifests. If you use package filters based on download activity, specifically the last_downloaded or downloads package filter options, Cloudsmith may inadvertently delete manifests because they appear "unused." This often results in orphaned platform images remaining in the repository.
Note
If your workflow relies heavily on manifest lists, consider using package filters (query strings) to exclude critical tags from retention, or use the Cloudsmith API to manage cleanup to ensure all associated artifacts are completely removed.
