Operate
Retention and garbage collection
How long builds and sites are kept, and how unused files are deleted.
CirCI deletes what is old and what nothing uses, in the background.
Retention
Section titled “Retention”Each project keeps its builds for a number of days (1 to 3650). Builds older than that, and hosted-site versions past their retention, expire. A new project starts with the instance's default, 30 days until an instance admin changes New projects keep builds for in Instance settings (it has no environment variable, and it doesn't touch existing projects). Each project then changes its own in its settings. A file is deleted only once no build or site uses it.
The newest approved baseline on the default branch, for each build name, never expires, because later builds compare with it. Older baselines expire like any build, so choose a retention longer than the longest time a branch lives.
Garbage collection
Section titled “Garbage collection”The worker runs a retention pass every 6 hours. One pass:
- Remove deleted workspaces. Permanently removes workspaces that were deleted more than 30 days ago.
- Expire old data. Expires old builds and site versions.
- Clear undo records. Removes expired undo records.
- Mark unused files. Un-marks files that became referenced again, and marks files nothing uses (screenshots, diffs, thumbnails, site files, and uploads that were never finished).
- Delete marked files. Deletes files that have been marked for longer than the grace period.
The grace period (Unused files are deleted after in Instance settings, or GC_GRACE_HOURS; default 24 hours) protects files that are about to be used again: a new upload that needs a marked file clears the mark, and each file is checked once more, under a lock, just before it's deleted. Several processes can run a pass at once.
Run it by hand
Section titled “Run it by hand”circi admin storage usage # sizes by kind, and what is waiting to be deletedcirci admin storage gc --dry-run # what would be deleted; changes nothingcirci admin storage gc # run a pass nowcirci admin storage gc --grace-hours 0 # delete unused files without waitingThe dry run doesn't simulate builds and sites that are past retention.
Other cleanups
Section titled “Other cleanups”Both are also limits in Instance settings: a variable that is set wins and locks the field, otherwise the saved value applies.
| Variable | Default | What it does |
|---|---|---|
JOB_RETENTION_DAYS |
14 | Finished background jobs (done or failed). 0 keeps them. |
UPLOAD_TIMEOUT_MINUTES |
60 | Not a deletion: a build still uploading after this long fails and names the missing shards. 0 never. |
Webhook delivery history keeps the latest 50 deliveries per webhook.