__                                                                 
          /  |                                                                
  ______  $$ |____            ______    ______   __    __  _______    ______  
 /      \ $$      \  ______  /      \  /      \ /  |  /  |/       \  /      \ 
/$$$$$$  |$$$$$$$  |/      |/$$$$$$  |/$$$$$$  |$$ |  $$ |$$$$$$$  |/$$$$$$  |
$$ |  $$ |$$ |  $$ |$$$$$$/ $$ |  $$ |$$ |  $$/ $$ |  $$ |$$ |  $$ |$$    $$ |
$$ \__$$ |$$ |  $$ |        $$ |__$$ |$$ |      $$ \__$$ |$$ |  $$ |$$$$$$$$/ 
$$    $$ |$$ |  $$ |        $$    $$/ $$ |      $$    $$/ $$ |  $$ |$$       |
 $$$$$$$ |$$/   $$/         $$$$$$$/  $$/        $$$$$$/  $$/   $$/  $$$$$$$/ 
/  \__$$ |                  $$ |                                              
$$    $$/                   $$ |                                              
 $$$$$$/                    $$/                                               

gh-prune is a command-line utility designed to help you manage and prune GitHub Actions workflow runs efficiently. It interacts with the GitHub CLI (gh) to list, inspect, and delete workflow runs, helping you maintain a clean repository and manage usage limits.

Before using gh-prune, ensure you have the following installed:

1. Python 3.x
2. GitHub CLI (gh):
   • macOS: brew install gh
   • Windows/Linux: See GitHub CLI Installation
3. Python Dependencies:
   • typer
   • rich

1. Clone the repository:

   git clone https://github.com/ifaakash/gh-prune.git
   cd gh-prune

2. Install dependencies:

   pip install typer rich

3. Authenticate with GitHub:

   gh auth login --hostname github.com

To build and run the project locally, it is highly recommended to use a separate virtual environment (venv).

1. Create and Activate Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate

2. Build and Install:

   rm -rf dist/
   python3 -m build
   pip3 install dist/gh_prune-*.whl --force-reinstall

The tool is executed via doctor.py. Below are the available commands.

Verifies that the GitHub CLI is installed and correctly authenticated.

python3 doctor.py doctor

Lists all workflows in a specified repository, showing their names, IDs, and states.

Syntax:

python3 doctor.py workflow-list [OWNER/REPO]

Example:

python3 doctor.py workflow-list ifaakash/gh-prune

Lists the recent runs of a specific workflow file.

Syntax:

python3 doctor.py workflow-run-list [OWNER/REPO] [WORKFLOW_FILENAME]

Example:

python3 doctor.py workflow-run-list ifaakash/gh-prune pylint.yml

Deletes old workflow runs but keeps a specified number of the most recent ones. Useful for cleaning up history while retaining the latest status.

Syntax:

python3 doctor.py workflow-run-delete [OWNER/REPO] [WORKFLOW_FILENAME] --keep [N] --limit [M]

Options:

• --keep: Number of recent runs to keep (default: 5).
• --limit: Number of runs to fetch for processing (default: 30).
• --yes / -y: Skip confirmation prompt.

Example:

python3 doctor.py workflow-run-delete ifaakash/news-agent cron-workflow.yml --keep 180 --limit 200

Deleting ALL runs for a specific workflow up to a specified limit. Use with caution.

Syntax:

python3 doctor.py workflow-run-prune [OWNER/REPO] [WORKFLOW_FILENAME] --limit [M]

Options:

• --limit: Number of runs to fetch and delete (default: 30).
• --yes / -y: Skip confirmation prompt.

Example:

python3 doctor.py workflow-run-prune ifaakash/news-agent cron-workflow.yml --limit 200

To see a tabular summary of commands and examples directly in the terminal, run:

python3 doctor.py docs