Configure Retention

This guide shows you how to set how long a repository keeps its history, have Swamp remove what is older without a manual command, and check that it does.

Prerequisites

Swamp installed and on your PATH
An initialised repo (swamp repo init)

1. Set a retention period

Add a garbageCollection block to .swamp.yaml. retention covers workflow runs, their snapshots, method outputs and audit logs; add a key for any kind that should differ:

garbageCollection:
  retention: 30d
  outputs: 7d
  audit: 90d

Durations use m for minutes and mo for months. See garbageCollection for every key.

2. Check what is past its cutoff

swamp doctor datastores --retention

When every kind is within its retention, you will see output like:

✓ No stored item is older than its retention

Retention: automatic off
  workflowRuns 30d cutoff 2026-09-16T17:03:33.409Z ✓ none older than cutoff
  evaluatedSnapshots 30d cutoff 2026-09-16T17:03:33.409Z ✓ none older than cutoff
  outputs 7d cutoff 2026-10-09T17:03:33.409Z ✓ none older than cutoff
  data no retention
  audit 90d cutoff 2026-07-18T17:03:33.409Z ✓ none older than cutoff
  bookkeeping no retention

Items past their cutoff are listed under their kind, and the command exits non-zero:

✗ 2 item(s) are older than their retention. Retention is not automatic: set garbageCollection.automatic: true, or run 'swamp run gc' and 'swamp data gc' (audit logs are pruned only automatically).

Retention: automatic off
  ...
  outputs 7d cutoff 2026-10-09T17:00:58.155Z ✗ 2 older than cutoff
    • command/shell/execute/e746c3b3-2baf-45b1-bba7-c189976246a9-2026-10-01T16-59-25-273Z.yaml 2026-10-01T16:59:25.273Z
    • command/shell/execute/e746c3b3-2baf-45b1-bba7-c189976246a9-2026-10-01T16-59-26-526Z.yaml 2026-10-01T16:59:26.526Z

To remove them once, run swamp run gc.

3. Turn on automatic retention

Add automatic: true:

garbageCollection:
  retention: 30d
  automatic: true
  outputs: 7d
  audit: 90d

swamp serve now runs a pass 5 minutes after it starts and hourly after that. Without a server, the next command that writes to the repository runs one when it finishes, at most once an hour.

On a busy swamp serve, a pass competes with runs for the datastore. Watch run latency after the first passes; see swamp-club#3518 and swamp-club#3535.

4. Confirm the passes run

Run swamp doctor datastores --retention again. Each kind shows its last pass:

Retention: automatic on
  workflowRuns 30d cutoff 2026-09-16T15:03:34.713Z ✓ none older than cutoff
    last pass 2026-10-16T17:00:59.969Z, cutoff 2026-09-16T17:00:59.969Z, complete
  ...

With automatic on, the check allows two hours past each cutoff before it reports an item as overdue. On a server, the health endpoint reports the same last pass per kind under retention.

If you changed audit, restart swamp serve so its audit stores pick it up.

5. Opt in to data retention

Data is not covered by retention. To remove data older than a cutoff, add a data key:

garbageCollection:
  retention: 30d
  automatic: true
  data: 90d

This removes every version of a data name whose latest version is older than 90 days, including data with lifetime: infinite. A behavior that has not run in 90 days loses its data. Set it only when the data can be produced again. See Why data is opt-in.

swamp data gc applies data too, whether automatic is on or not.