gh-prune 0.1.1

CLI to prune GitHub workflow runs

gh-prune

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.

Prerequisites

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

Installation

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
   

Build and Run Locally

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
   

Usage

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

1. Health Check (doctor)

Verifies that the GitHub CLI is installed and correctly authenticated.

python3 doctor.py doctor

2. List Workflows (workflow-list)

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

3. List Workflow Runs (workflow-run-list)

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

4. Delete Old Runs (workflow-run-delete)

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

5. Prune All Runs (workflow-run-prune)

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

Help

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

python3 doctor.py docs