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:
- Python 3.x
- GitHub CLI (
gh):- macOS:
brew install gh - Windows/Linux: See GitHub CLI Installation
- macOS:
- Python Dependencies:
typerrich
Installation
-
Clone the repository:
git clone https://github.com/ifaakash/gh-prune.git cd gh-prune
-
Install dependencies:
pip install typer rich
-
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).
-
Create and Activate Virtual Environment:
python3 -m venv venv source venv/bin/activate
-
Build and Install:
rm -rf dist/ build/ *.egg-info python3 -m build pip3 uninstall gh-prune -y pip3 install dist/gh_prune-*.whl --force-reinstall twine check dist/* twine upload dist/*
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
Metadata
Release files for gh-prune 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gh_prune-0.1.2.tar.gz | 6.6 kB | Without provenance | Details for gh_prune-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gh_prune-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for gh_prune-0.1.2-py3-none-any.whl |
Total release size: 14.9 kB
Release files / gh_prune-0.1.2.tar.gz
| Download URL | gh_prune-0.1.2.tar.gz |
|---|---|
| Size | 6.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c0a986f91679016de73d54ec4e1cf811f56fb3f40adcfe29fe96d51265018019
|
|
BLAKE2b-256 checksum How to use checksums |
196deb764b24a6ea4e000ba9eaf28203bc5502836e482a29bac6795f23424c52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / gh_prune-0.1.2-py3-none-any.whl
| Download URL | gh_prune-0.1.2-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf136fe28bf3d6dfff088f989ad15418cdb73096c845bfb5a96085e82a706b7d
|
|
BLAKE2b-256 checksum How to use checksums |
a3d653c961843e5c5c56aa9ab779c6e3421d41d47ca58749d62caa4e4ce645e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for gh-prune 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.