Add retain_checkpoints field to Repository

Add a retain_checkpoints field to the Repository model that limits
the number of checkpoint publications per repository. When set,
older checkpoint publications beyond the limit have their checkpoint
flag cleared automatically.

Cleanup is triggered both when retain_checkpoints is updated on an
existing repository and when a new checkpoint publication is created.

closes #7428
Assisted-by: GitHub Copilot

Author: Moustafa-Moustafa

CHANGES/7428.feature

@@ -0,0 +1 @@
+Added ``retain_checkpoints`` field to Repository to automatically clear the checkpoint flag on older publications exceeding the limit.

docs/user/guides/checkpoint.md

@@ -73,6 +73,22 @@ http https://pulp.example/pulp/content/checkpoint/myfile
 </html>
 ```
 
+## Limiting Checkpoints
+
+By default, all checkpoint publications are retained indefinitely. You can limit the number of
+checkpoints per repository by setting `retain_checkpoints` on the repository. When set, only the
+most recent N checkpoint publications are kept. Older checkpoint publications have their checkpoint
+flag cleared but are not deleted and the underlying publications and repository versions remain intact.
+
+```bash
+pulp file repository update --name myrepo --retain-checkpoints 10
+```
+
+Setting this to `null` (the default) disables checkpoint retention and keeps all checkpoints.
+
+Note that clearing the checkpoint flag on a publication also removes its repository version from
+checkpoint protection, making it eligible for cleanup by `retain_repo_versions` if configured.
+
 ### Accessing a Specific Checkpoint
 To access a specific checkpoint, suffix the checkpoint distribution's path with a timestamp in the format
 `yyyyMMddTHHmmssZ` (e.g. 20250130T205339Z), If a checkpoint was created at this time, it will be

pulpcore/app/migrations/0146_repository_retain_checkpoints.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.12 on 2026-03-09 22:18
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("core", "0145_domainize_import_export"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="repository",
+            name="retain_checkpoints",
+            field=models.PositiveIntegerField(default=None, null=True),
+        ),
+    ]

pulpcore/app/models/publication.py

@@ -233,6 +233,11 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 self.delete()
                 raise
 
+            # Unmark old checkpoints if retention is configured
+            if self.checkpoint:
+                repository = self.repository_version.repository
+                repository.cleanup_old_checkpoints()
+
             # invalidate cache
             if settings.CACHE_ENABLED:
                 base_paths = Distribution.objects.filter(

pulpcore/app/models/repository.py

@@ -52,6 +52,8 @@ class Repository(MasterModel):
         next_version (models.PositiveIntegerField): A record of the next version number to be
             created.
         retain_repo_versions (models.PositiveIntegerField): Number of repo versions to keep
+        retain_checkpoints (models.PositiveIntegerField): Number of checkpoint publications to
+            keep as checkpoints.
         user_hidden (models.BooleanField): Whether to expose this repo to users via the API
 
     Relations:
@@ -71,6 +73,7 @@ class Repository(MasterModel):
     description = models.TextField(null=True)
     next_version = models.PositiveIntegerField(default=0)
     retain_repo_versions = models.PositiveIntegerField(default=None, null=True)
+    retain_checkpoints = models.PositiveIntegerField(default=None, null=True)
     user_hidden = models.BooleanField(default=False)
     content = models.ManyToManyField(
         "Content", through="RepositoryContent", related_name="repositories"
@@ -419,6 +422,33 @@ def cleanup_old_versions(self):
                 )
                 version.delete()
 
+    @hook(AFTER_UPDATE, when="retain_checkpoints", has_changed=True)
+    def _cleanup_old_checkpoints_hook(self):
+        transaction.on_commit(self.cleanup_old_checkpoints)
+
+    def cleanup_old_checkpoints(self):
+        """Unmark old checkpoint publications based on retain_checkpoints."""
+        from .publication import Publication
+
+        if self.retain_checkpoints:
+            checkpoint_pubs = Publication.objects.filter(
+                repository_version__repository=self,
+                checkpoint=True,
+                complete=True,
+            ).order_by("-pulp_created")
+            expired_pks = list(
+                checkpoint_pubs[self.retain_checkpoints :].values_list("pk", flat=True)
+            )
+            if expired_pks:
+                Publication.objects.filter(pk__in=expired_pks).update(checkpoint=False)
+                _logger.info(
+                    "Cleared checkpoint flag on %d publication(s) for repository %s "
+                    "due to checkpoint retention limit of %d.",
+                    len(expired_pks),
+                    self.name,
+                    self.retain_checkpoints,
+                )
+
     def delete(self, **kwargs):
         """
         Delete the repository.

pulpcore/app/serializers/repository.py

@@ -44,6 +44,15 @@ class RepositorySerializer(ModelSerializer):
         required=False,
         min_value=1,
     )
+    retain_checkpoints = serializers.IntegerField(
+        help_text=_(
+            "Retain X checkpoint publications for the repository. "
+            "Default is null which retains all checkpoints."
+        ),
+        allow_null=True,
+        required=False,
+        min_value=1,
+    )
     remote = DetailRelatedField(
         help_text=_("An optional remote to use by default when syncing."),
         view_name_pattern=r"remotes(-.*/.*)-detail",
@@ -69,6 +78,7 @@ class Meta:
             "name",
             "description",
             "retain_repo_versions",
+            "retain_checkpoints",
             "remote",
         )
 

pulpcore/app/viewsets/repository.py

@@ -97,6 +97,7 @@ class Meta:
         fields = {
             "name": NAME_FILTER_OPTIONS,
             "retain_repo_versions": NULLABLE_NUMERIC_FILTER_OPTIONS,
+            "retain_checkpoints": NULLABLE_NUMERIC_FILTER_OPTIONS,
         }
 
 

pulpcore/tests/functional/api/using_plugin/test_checkpoint.py

@@ -24,21 +24,18 @@ def _content_factory(name):
 
 
 @pytest.fixture(scope="class")
-def setup(
-    file_repository_factory,
-    file_distribution_factory,
-    content_factory,
-    file_bindings,
-    monitor_task,
-):
-    def create_publication(repo, checkpoint):
-        nonlocal content_counter
+def create_publication(content_factory, file_bindings, monitor_task):
+    counter = [0]
+
+    def _create_publication(repo, checkpoint):
+        content_href = content_factory(f"{counter[0]}")
+        counter[0] += 1
+
         monitor_task(
             file_bindings.RepositoriesFileApi.modify(
-                repo.pulp_href, {"add_content_units": [content_factory(f"{content_counter}")]}
+                repo.pulp_href, {"add_content_units": [content_href]}
             ).task
         )
-        content_counter += 1
 
         response = monitor_task(
             file_bindings.PublicationsFileApi.create(
@@ -47,11 +44,19 @@ def create_publication(repo, checkpoint):
         )
         return file_bindings.PublicationsFileApi.read(response.created_resources[0])
 
+    return _create_publication
+
+
+@pytest.fixture(scope="class")
+def setup(
+    file_repository_factory,
+    file_distribution_factory,
+    create_publication,
+):
     repo = file_repository_factory()
     distribution = file_distribution_factory(repository=repo.pulp_href, checkpoint=True)
 
     pubs = []
-    content_counter = 0
     pubs.append(create_publication(repo, False))
     sleep(1)
     pubs.append(create_publication(repo, True))
@@ -227,3 +232,51 @@ def test_checkpoint_publication_with_repository_version_fails(
                 file_bindings.PublicationsFileApi,
                 {"repository_version": repo.latest_version_href, "checkpoint": True},
             )
+
+
+@pytest.mark.parallel
+def test_checkpoint_retention(
+    file_bindings,
+    file_repository_factory,
+    file_distribution_factory,
+    create_publication,
+    monitor_task,
+):
+    """Test retain_checkpoints for repositories.
+
+    When retain_checkpoints is set, only the N most recent checkpoint publications should
+    retain their checkpoint=True flag. Older ones get their checkpoint flag cleared.
+    """
+    repo = file_repository_factory()
+    file_distribution_factory(repository=repo.pulp_href, checkpoint=True)
+
+    # Create 4 checkpoint publications
+    checkpoint_pubs = []
+    for _ in range(4):
+        checkpoint_pubs.append(create_publication(repo, True))
+
+    # Verify all 4 publications are checkpoints
+    for pub in checkpoint_pubs:
+        assert file_bindings.PublicationsFileApi.read(pub.pulp_href).checkpoint is True
+
+    # Set retain_checkpoints=2 — should clear checkpoint flag on the 2 oldest
+    task = file_bindings.RepositoriesFileApi.partial_update(
+        repo.pulp_href, {"retain_checkpoints": 2}
+    ).task
+    monitor_task(task)
+
+    # Verify the 2 oldest had their flag cleared
+    for pub in checkpoint_pubs[:2]:
+        assert file_bindings.PublicationsFileApi.read(pub.pulp_href).checkpoint is False
+
+    # Verify the 2 most recent still have checkpoint=True
+    for pub in checkpoint_pubs[2:]:
+        assert file_bindings.PublicationsFileApi.read(pub.pulp_href).checkpoint is True
+
+    # Create another checkpoint — should trigger steady-state cleanup
+    new_pub = create_publication(repo, True)
+
+    # checkpoint_pubs[2] should now be cleared too
+    assert file_bindings.PublicationsFileApi.read(checkpoint_pubs[2].pulp_href).checkpoint is False
+    assert file_bindings.PublicationsFileApi.read(checkpoint_pubs[3].pulp_href).checkpoint is True
+    assert file_bindings.PublicationsFileApi.read(new_pub.pulp_href).checkpoint is True