ghbot
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_TOKENwhen using--envorenv = 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.