ContribCheck: GitHub Issue Readiness Checker

An evidence-based CLI and API that checks whether a GitHub issue is genuinely ready for an open-source contribution.

ContribCheck identifies blockers that issue-discovery lists often miss: dependency issues, missing base branches, existing assignments, comment claims, competing pull requests, unhealthy default-branch CI, and missing contribution guidance.

It does not predict whether a maintainer will merge a pull request. Every result is linked to observable GitHub state, and signals that cannot be verified are reported as unknown instead of silently passing.

Real-World Example

Two open issues from the same repository can look equally available while having very different readiness states.

Blocked by a prerequisite

contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/986 \
  --actor gokul-debugger

Lyrics models
https://github.com/sigma67/ytmusicapi/issues/986
Verdict: BLOCKED

FAILURE  Dependencies        Blocked by 1 open issue(s).
FAILURE  Base branch         Required branch `ytmusicapi-2` does not exist.
PASS     Assignment          Assigned to the requested contributor.
PASS     Competing PRs       No open pull request referencing this issue was found.

Next actions
- Wait for the listed dependency issues to close.
- Ask the maintainer to create or clarify the required base branch.
- Read the repository contribution guide before creating a branch.

ContribCheck prevents work from starting too early: the contributor is assigned, but the required dependency and base branch are not ready.

Ready for contribution

contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/941

get_song() can return stale likeStatus right after rate_song()
https://github.com/sigma67/ytmusicapi/issues/941
Verdict: READY

PASS  Dependencies        No open blockers reported.
PASS  Assignment          The issue is unassigned.
PASS  Comment claims      No other contributor appears to have claimed it.
PASS  Competing PRs       No open pull request referencing this issue was found.
PASS  Default branch CI   Latest runs for 4 workflow(s) are green.
PASS  Maintainer response A maintainer first replied after approximately 8 hours.

Next actions
- Read the repository contribution guide before creating a branch.
- Comment with a concise implementation plan before starting work.

Here the evidence supports beginning the contribution workflow, while still recommending coordination with the maintainer.

Why It Exists

Labels such as good first issue and help wanted are useful discovery signals, but they do not guarantee that an issue is actionable. A contribution can still be blocked by another issue, depend on a branch that has not been created, overlap an existing pull request, or wait in a repository whose default CI is already failing.

ContribCheck performs that second-stage verification before a contributor invests hours in setup and implementation.

Checks

The overall result is one of:

• ready: no blocking, warning, or unknown signals were found
• caution: manual review is needed
• blocked: a hard prerequisite is not satisfied

Installation

ContribCheck requires Python 3.11 or newer.

pipx install contribcheck

Alternatively, install it into an existing Python environment with pip install contribcheck. The optional web service is available with pip install "contribcheck[server]".

Public GitHub requests work without authentication, but GitHub applies a much smaller anonymous rate limit. Set a token for regular use:

export GITHUB_TOKEN="your-fine-grained-token"

Read-only access to public metadata is sufficient. Do not grant write permissions.

CLI

Inspect by URL:

contribcheck inspect https://github.com/owner/repository/issues/123

Inspect by shorthand and emit JSON:

contribcheck inspect owner/repository#123 --actor your-username --json

Use the result in CI or a script:

contribcheck inspect owner/repository#123 --fail-on caution

Exit codes are 0 for a completed inspection, 1 for an operational error, and 2 when the configured readiness threshold is reached.

Render a portable GitHub-flavored Markdown report:

contribcheck inspect owner/repository#123 --markdown
contribcheck inspect owner/repository#123 --markdown --output report.md

Markdown reports include the issue title and URL, verdict, check summaries, linked evidence, and next actions. --markdown and --json cannot be used together. Existing terminal output remains the default.

Inspect several candidates from a text file while preserving input order:

# candidates.txt
sigma67/ytmusicapi#986
https://github.com/plotly/plotly.js/issues/7750

contribcheck batch candidates.txt --actor your-username
contribcheck batch candidates.txt --json --fail-on caution

Batch JSON uses a stable top-level object with schema_version, ordered results, and a summary containing total, success, failure, and verdict counts. Each failed item is reported independently instead of discarding successful inspections. Batch concurrency defaults to four and can be changed with --concurrency.

Batch exit codes are 0 when processing completes without reaching the configured threshold, 1 when input or processing fails for at least one item, and 2 when a successful report reaches the configured --fail-on threshold.

GitHub Enterprise Server

Set the API endpoint with GITHUB_API_URL, or override it for one command with --base-url:

export GITHUB_API_URL="https://github.example.com/api/v3"
contribcheck inspect https://github.example.com/team/project/issues/123
contribcheck inspect team/project#123 --base-url https://github.example.com/api/v3

The precedence is CLI option, GITHUB_API_URL, then https://api.github.com. The endpoint must be HTTP or HTTPS and cannot contain credentials, query parameters, or fragments. Tokens are sent only to the configured API endpoint.

Python SDK

import asyncio

from contribcheck import GitHubClient, IssueAnalyzer


async def main() -> None:
    async with GitHubClient() as client:
        report = await IssueAnalyzer(client).inspect(
            "https://github.com/sigma67/ytmusicapi/issues/986",
            actor="gokul-debugger",
        )
    print(report.status)
    print(report.check("dependencies").summary)


asyncio.run(main())

HTTP API

Install server dependencies and start FastAPI:

pip install -e '.[server]'
contribcheck serve

Open http://127.0.0.1:8000/ for the browser interface or http://127.0.0.1:8000/docs for the interactive API documentation. The browser interface sends only the issue reference and optional actor to the local API. It does not accept, store, or log GitHub tokens.

Call the API directly:

curl -X POST http://127.0.0.1:8000/v1/inspect \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://github.com/sigma67/ytmusicapi/issues/986",
    "actor": "gokul-debugger"
  }'

The service accepts an optional Authorization: Bearer ... header. It never stores the token.

Docker

docker build -t contribcheck .
docker run --rm -p 8000:8000 -e GITHUB_TOKEN contribcheck

Development

This repository uses uv for reproducible development environments:

uv sync --all-extras --dev
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests
uv run pytest --cov=contribcheck --cov-report=term-missing

Tests use a mocked GitHub transport and do not consume API quota.

Contributing

Contributions are welcome. Start with the good first issues or browse tasks marked help wanted.

Read CONTRIBUTING.md, comment with a short implementation plan, and wait for confirmation before starting work that changes a public contract.

Current Limitations

• Comment-claim detection is conservative text matching, not proof of ownership.
• Competing PR detection can miss work that never references the issue.
• Maintainer responsiveness is measured only on the inspected issue in this release.
• Explicit base-branch detection depends on recognizable wording in the issue body.
• Private repositories require a token with appropriate read access.
• GitHub remains the source of truth; always review linked evidence before acting.

Roadmap

• Repository-wide maintainer response statistics
• Local clone and development-environment readiness checks
• GitHub App checks embedded directly in issue conversations
• Browser extension for one-click inspection
• Configurable organization policies and output formats

License

MIT