Skip to main content

License Open Source Love MIT License Maintained GitHub last commit Python PRs Welcome

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):
  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/ 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)

Source distribution for gh-prune 0.1.2
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)

Table of built distributions (wheels) for gh-prune 0.1.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page