gh-runs-cleanup
GitHub CLI extension
gh-runs-cleanup
helps you safely bulk-delete GitHub Actions workflow
runs with dry-run previews, explicit confirmation,
filtering by workflow, branch, age, and status, plus
retry handling and machine-readable JSON summaries.
--dry-run
and
--confirm--jsonInstall
Install the extension once, then use dry runs to preview cleanup safely before deleting anything.
gh extension install Nick2bad4u/gh-runs-cleanupRequirements
gh
installed and authenticated22.18+, 24+, or 26+Features
No destructive action happens unless you opt in
with
--confirm
or
--yes
.
Filter by workflow, branch, event, actor, commit, created date, age threshold, and run status.
Retries with backoff, fail-fast, max-failures, ordering, and exclusion filters help avoid noisy cleanup runs.
Use
--json
for machine-readable summaries in scheduled
workflows, scripts, or local tooling.
Process runs in
oldest
,
newest
, or
none
mode to match your retention strategy.
Works with existing
gh
authentication and repository context instead of
requiring a separate service or config file.
Usage
gh runs-cleanup --repo owner/repo --dry-rungh runs-cleanup --repo owner/repo --status failure,cancelled --confirmgh runs-cleanup --repo owner/repo --status failure --before-days 30 --confirmgh runs-cleanup --repo owner/repo --all-statuses --exclude-workflow CI,Release --dry-runFilters & controls
| Category | Options |
|---|---|
| Repository |
--repo
|
| Workflow selection |
--workflow
,
--exclude-workflow |
| Branch selection |
--branch
,
--exclude-branch |
| Status & age |
--status
,
--all-statuses
,
--before-days
,
--created |
| Execution controls |
--max-delete
,
--order
,
--max-retries
,
--retry-delay-ms
,
--fail-fast
,
--max-failures |
| Output |
--verbose
,
--quiet
,
--json |
JSON mode
gh runs-cleanup \
--repo owner/repo \
--status failure \
--before-days 14 \
--dry-run \
--json{
"attempted": 0,
"deleted": 0,
"dryRun": true,
"durationMs": 112,
"failed": 0,
"failedIds": [],
"matched": 42,
"repo": "owner/repo",
"skippedByExclusion": 3,
"statuses": ["failure"],
"skippedByAge": 19
}Start with a dry run, confirm only what you want to remove, and automate the rest with JSON output and scheduled jobs.