Installation and Usage

Installation and Usage

Requirements

• macOS terminal
• GitHub CLI (gh)
• a GitHub account authenticated with gh auth login

Install

From the project folder:

chmod +x gh-actions-cleanup install-gh-actions-cleanup.sh
./install-gh-actions-cleanup.sh

By default, the installer:

• installs the terminal command into a writable bin directory
• installs a macOS app bundle into ~/Applications
• generates the app icon locally during install

The installer is intended for macOS and will stop if you run it on another platform.

If the installer uses ~/.local/bin and that path is not already in your shell PATH, add the export line printed by the installer into ~/.zshrc, then open a new terminal.

Install only one target if needed:

./install-gh-actions-cleanup.sh --cli-only
./install-gh-actions-cleanup.sh --app-only

Interactive Use

gh-actions-cleanup

App launch:

• open GH Workflow Clean.app from Finder, Spotlight, or Launchpad
• the app opens Terminal and starts the interactive CLI

The CLI can prompt for:

• GitHub host
• authenticated account
• repository owner
• repository name
• cleanup actions

Common Commands

Full cleanup:

gh-actions-cleanup --repo OWNER/REPO --all --yes

Dry run:

gh-actions-cleanup --repo OWNER/REPO --all --dry-run --yes

Disable workflows only:

gh-actions-cleanup --repo OWNER/REPO --disable-workflows --yes

Delete workflow runs only:

gh-actions-cleanup --repo OWNER/REPO --delete-runs --yes

Delete one exact run by ID or URL:

gh-actions-cleanup --repo OWNER/REPO --run 21023858697 --yes
gh-actions-cleanup --repo OWNER/REPO --run "https://github.com/OWNER/REPO/actions/runs/21023858697/workflow" --yes

Delete only one run series:

gh-actions-cleanup --repo OWNER/REPO --delete-runs --run-filter "Sync Google Analytics Data" --yes

Delete artifacts only:

gh-actions-cleanup --repo OWNER/REPO --delete-artifacts --yes

Delete caches only:

gh-actions-cleanup --repo OWNER/REPO --delete-caches --yes

Notes

• The command uses the selected active GitHub account on the selected host.
• If multiple accounts are authenticated on one host, the CLI can switch with gh auth switch.
• The token in use needs repository and workflow access to delete Actions resources.
• You can target one exact workflow run by numeric ID or GitHub run URL.
• If the active token is invalid or the GitHub API core rate limit is exhausted, the CLI stops early and tells you what to fix before cleanup starts.
• If local gh auth status looks stale but live GitHub API access still works, the CLI warns and continues.
• --dry-run is the safest way to verify intended changes before deleting Actions data.
• The macOS app uses Terminal for the interactive session and may ask for automation permission the first time it launches.