Skip to main content

ghbot

Validate Security Maintenance PyPI version Python versions License: MIT

An async command-line tool that scans GitHub repositories across one or more owners and reports on them. ghbot is a small engine — repository discovery, bounded-concurrency execution, a GitHub API layer, and report rendering — plus a set of processors that each answer one question about a repository (security posture, open issues, …).

Requirements

  • By default, the GitHub CLI (gh), installed and authenticated (gh auth login).
  • Alternatively, an API token in GITHUB_API_TOKEN when using --env or env = true.

Authentication

By default, ghbot has no credentials of its own. At startup it runs gh auth token and uses the token that gh already holds from your gh auth login — it does not generate a new token. Your effective access is therefore exactly your gh login's scopes.

Use the global -e / --env option, or set env = true in ghbot.toml, to read the API token from GITHUB_API_TOKEN instead. --no-env overrides env = true for one invocation and returns to the default gh auth token source. Environment-token mode never invokes gh; it fails clearly if that variable is unset or empty. GITHUB_TOKEN is not used, so workflow tokens cannot change local command behaviour accidentally.

The selected token is fetched once, cached in memory for the duration of the run, and never written to disk. In the default mode, if gh is missing or you are not logged in, ghbot stops with a clear message. gh is used only for the default token source — all repository data is then fetched by calling the GitHub REST API directly (via httpx + gidgethub), not by shelling out to gh for each request.

Running

uvx ghbot --owner <owner> <command> [options]

--owner may be repeated or comma-separated, and targets a GitHub user or organisation. ghbot scans repositories accessible to the configured token and skips archived repositories:

uvx ghbot --owner acme security
uvx ghbot --owner acme,globex issues --json --labels

(From a source checkout, use uv run ghbot … instead of uvx ghbot ….)

Commands (built-in processors)

security — open security findings

Scans each repository for open Dependabot, code-scanning, and secret-scanning alerts, and open Dependabot pull requests (and how many are ready to merge once approvals are ignored).

uvx ghbot --owner acme security [--plain | --table | --json] [--output FILE]
Option Meaning
--plain (default) Summary + a per-repo block for repos with findings
--table Markdown table, one row per repo with findings
--json Structured output for every scanned repo
--output FILE Write the report to a file instead of stdout

Counts that are unavailable (no access / feature off) show as N/A in text and null in JSON; 0 means accessible with nothing open.

issues — open issues and pull requests

Lists open issues and pull requests per repository, each tagged by type (issue or pr).

uvx ghbot --owner acme issues [--plain | --table | --json] [--labels] [--output FILE]
Option Meaning
--plain (default) Per-repo header + #<n> [<type>] <title> lines
--table One row per item: Repository │ # │ Type │ Description
--json repositories[] with open_item_count and an items[] array
--labels Include GitHub labels (+label in plain, a Labels column in table, a labels[] array in JSON)
--output FILE Write the report to a file

The summary splits Open issues and Open PRs. Plain/table omit repos with nothing open; JSON includes every scanned repo.

drift — commits since the latest stable release

Finds repositories whose configured default branch has commits newer than their latest published stable GitHub release. Repositories without a stable release, or with no commits since it, are not listed. For each reported repository, drift also indicates whether its GitHub Actions workflows appear configured to publish to PyPI; this is configuration detection only and does not query PyPI.

uvx ghbot --owner acme drift [--plain | --table | --json] [--output FILE]
Option Meaning
--plain (default) Summary + per-repository release, publication time, branch, commit count, and PyPI configuration
--table Markdown table for repositories with commits since release
--json Structured summary and reportable repositories; unknown PyPI configuration is null
--output FILE Write the report to a file instead of stdout

info — repository summary statistics

Gathers per-repository facts (description, languages, contributors, latest release, file count, open PRs/issues, security alerts). These are collected and logged during the scan; info does not currently render a stdout report.

Global options

Global options go before the command:

Option Meaning
--owner <o> Owner(s) to scan; repeatable or comma-separated
--concurrency <n> Max repositories processed at once (default 16)
--config <path> Config file (see below)
-e, --env / --no-env Read the API token from GITHUB_API_TOKEN, or override env = true to use gh auth token
--verbose / --quiet Console log level: debug / warnings-only
--log-file <path> Also write logs to a file
--log-level <lvl> File log level: trace/debug/info/warn/error
--log-json Structured JSON logs to the log file
--requests Log HTTP request/response detail

Configuration

Options can be set in ghbot.toml (current directory) or ~/.config/ghbot/config.toml. Some CLI flags override the file (notably --owner, --concurrency, --log-file, and --log-json); --env enables environment-token mode and --no-env disables it for one invocation.

owners = ["acme", "globex"]
concurrency = 16
log-level = "info"
log-json = false
env = true  # use GITHUB_API_TOKEN instead of gh auth token

How it works

authentication source
      ├─ `--env`, or `env = true` without `--no-env` ─► GITHUB_API_TOKEN
      └─ `--no-env`, or otherwise ────────────────────► gh auth token
      │
scan_repositories(owners)          discover each accessible non-archived repo
      │  DiscoveredRepository(owner, metadata, owner_type) stream
TaskPool (bounded concurrency)     one processor instance per repo, run in parallel
      │
Processor.run() ─► RepoResult      fetch via the GitHub API, return structured results
      │
report renderer                    plain / table / JSON
  • GitHub API access goes through a single wrapper that maps HTTP failures to typed errors (not-found, rate-limit, transient) so processors handle them uniformly.
  • Resilience: a failed step yields a partial result rather than aborting the run; rate limits abort the pool cleanly.

License

MIT — see LICENSE.md.

Metadata

Release files for ghbot 0.30.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ghbot 0.30.0
File Size Uploaded Provenance Actions
ghbot-0.30.0.tar.gz 21.4 kB Without provenance Details for ghbot-0.30.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ghbot 0.30.0
File Interpreter ABI Platform Actions
ghbot-0.30.0-py3-none-any.whl Python 3 none any Details for ghbot-0.30.0-py3-none-any.whl

Total release size: 49.7 kB

Release files / ghbot-0.30.0.tar.gz

Download URL ghbot-0.30.0.tar.gz
Size 21.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2f2da2a767b9b2184f8532ba2c3330283f8c238209b21d5a4b96879178d7c258
BLAKE2b-256 checksum
How to use checksums
72b68e8362fad48fa08a0ecb02a573d7376a74bfece7f96412f61a3e261512b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ghbot-0.30.0-py3-none-any.whl

Download URL ghbot-0.30.0-py3-none-any.whl
Size 28.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91ce05e314f4c6c9ad30514b2a0ccadea0a6eae2824f9e146b5a0327c3e594d6
BLAKE2b-256 checksum
How to use checksums
50b77b3e53d2769a5ba598cca8f8787c24c3099aa71a3979d1db4ef0ea7a6cc7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ghbot 0.30.0

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