Installation and Usage

Installation and Usage

Requirements

• macOS terminal
• GitHub CLI (gh)
• a GitHub account authenticated with gh auth login
• Xcode or Command Line Tools if you want the native GUI app built locally from source

One-Line Install

From any Mac:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/WayneTechLab/GH-Workflow-Clean/main/install.sh)"

Then log into GitHub CLI:

gh auth login -h github.com
gh-actions-cleanup

Installer behavior:

• the bootstrap installer resolves the latest tagged release before downloading
• the CLI installs everywhere GitHub CLI is available
• the native GUI app is built automatically when the local Mac has a Swift toolchain
• if Swift is missing, the installer falls back to CLI-only and tells you how to add the GUI later
• when possible, the native app installs into /Applications; otherwise it falls back to ~/Applications
• older app and CLI copies are removed first so upgrades are clean

Install

From the project folder:

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

By default, the installer:

• removes stale CLI installs from common macOS bin paths before installing the new version
• removes stale app bundles from /Applications and ~/Applications before reinstalling
• installs the terminal command into a writable bin directory
• installs a native macOS app bundle into ~/Applications
• compiles the GUI locally with Swift when the toolchain is available
• generates the app icon locally during install
• writes the current app version into the bundle metadata and bundled VERSION file
• keeps GitHub authentication in the user's existing gh keychain session

The installer prefers /Applications when that location is writable.

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
./install-gh-actions-cleanup.sh --uninstall-only

Interactive Use

gh-actions-cleanup

App launch:

• open GH Workflow Clean.app from Finder, Spotlight, or Launchpad
• the native app opens a real macOS window

The guided flow can prompt for:

• GitHub host
• authenticated account
• repository target as OWNER/REPO, HOST/OWNER/REPO, or full GitHub URL
• cleanup actions

The GUI also gives you:

• a single-screen native control panel
• a host picker and account picker
• a clear GitHub token status banner
• a repository browser with owner/org loading, search, checkmarks, and select-all
• a manual repo/URL fallback field
• toggles for full cleanup, runs, workflows, artifacts, caches, and dry-run
• a logout button for the selected GitHub account
• a safety arm switch that must be enabled before cleanup runs
• a readable high-contrast live output panel backed by the bundled CLI

Common Commands

Full cleanup:

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

Dry run:

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

Custom host or full repo URL:

gh-actions-cleanup --host github.example.com --repo OWNER/REPO --all --yes
gh-actions-cleanup --repo https://github.example.com/OWNER/REPO --all --yes
gh-actions-cleanup --repo github.example.com/OWNER/REPO --all --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

• Users must authenticate first with gh auth login -h <host>.
• The command uses the selected active GitHub account on the selected host.
• The GUI uses the same gh login state and the same bundled CLI engine.
• If multiple accounts are authenticated on one host, the CLI can switch with gh auth switch and restore the prior active account when the session ends.
• The tool does not embed, print, or save GitHub tokens.
• 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.
• The tool stores only the last host, account, and repo in ~/Library/Application Support/GH Workflow Clean/last-session.env.
• --dry-run is the safest way to verify intended changes before deleting Actions data.
• The native GUI app currently targets macOS 12 or newer.