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.
Two open issues from the same repository can look equally available while having very different readiness states.
contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/986 \
--actor gokul-debuggerLyrics 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.
contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/941get_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.
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.
| Check | Evidence | Effect |
|---|---|---|
| Issue state | GitHub issue state | Closed issues block work |
| Dependencies | GitHub issue dependency API | Open dependencies block work |
| Base branch | Explicit branch named in the issue body | A missing required branch blocks work |
| Assignment | Current assignees | Another assignee blocks uncoordinated work |
| Comment claims | Explicit work-claim phrases | Produces a caution |
| Competing PRs | Timeline cross-references and PR search | Produces a caution |
| Scope | Issue body and acceptance-language markers | Warns when clarification may be needed |
| Contribution guide | Repository tree | Warns when standard guidance is absent |
| Repository health | Archive status and recent push activity | Blocks archived repositories, warns on inactivity |
| Default CI | Latest completed workflow run per workflow | Warns about pre-existing failures |
| Maintainer response | Comment author association and timestamps | Reports issue-level responsiveness |
The overall result is one of:
ready: no blocking, warning, or unknown signals were foundcaution: manual review is neededblocked: a hard prerequisite is not satisfied
ContribCheck requires Python 3.11 or newer.
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .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.
Inspect by URL:
contribcheck inspect https://github.com/owner/repository/issues/123Inspect by shorthand and emit JSON:
contribcheck inspect owner/repository#123 --actor your-username --jsonUse the result in CI or a script:
contribcheck inspect owner/repository#123 --fail-on cautionExit codes are 0 for a completed inspection, 1 for an operational error, and 2 when the configured readiness threshold is reached.
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())Install server dependencies and start FastAPI:
pip install -e '.[server]'
contribcheck serveOpen http://127.0.0.1:8000/docs, or 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 build -t contribcheck .
docker run --rm -p 8000:8000 -e GITHUB_TOKEN contribcheckThis 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-missingTests use a mocked GitHub transport and do not consume API quota.
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.
- 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.
- 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
MIT