Thanks for your interest. This project is small and bash-script-driven; the contribution workflow is correspondingly lightweight.
Open a regular GitHub issue for anything except security reports — bug reports, feature requests, doc fixes, questions about behaviour.
Security issues go through SECURITY.md, not the public tracker. See its "Reporting a vulnerability" section.
- Fork the repo and create a feature branch off
develop(the default branch). - Make your change. The required
syntaxCI check runs three things and they must all be clean:bash -n zhpython -m py_compile mcp_server.py zh_api.py zh_graphql_ops.py similarity.pypython -m pytest tests/
- Open the PR against
develop. Themainbranch only receives release PRs fromdevelop(it's the stable line that the tags point at). - Address review feedback. Once approved and CI passes, a maintainer will merge.
The first time an outside contributor opens a PR, GitHub holds Actions execution pending maintainer approval — this is the "Require approval for all outside collaborators" gate documented in SECURITY.md §1. The PR is fine; it just may sit briefly before workflows start.
syntax(required) — bash and Python syntax checks plus the pytest suite across Python 3.10/3.11/3.12. Must pass before merge intodevelopormain. No secrets needed; runs on every push and PR including from forks.- Claude code review — automated PR review using a subscription-bound OAuth token. Output appears as a PR comment and drives the
review-gatecheck (below). - Semgrep security scan (advisory): free, token-free Semgrep OSS (
p/python,p/bash,p/secrets,p/ci) runs first on every PR and posts a single sticky findings comment, which the Claude code review folds into its analysis. No API key; advisory.
The review's verdict is enforced, not just advisory. After the main review posts, a cheap single-purpose second pass (verdict-extract) reads it and emits one machine line, and review-gate turns that into a check:
- PASS — the review reported no HIGH/CRITICAL findings. Green.
- BLOCK — at least one HIGH/CRITICAL finding (a correctness bug on a common path, a security/data-loss issue, a build/release breakage, or a CI Tests failure). Push a fix — the review re-runs on every push and can clear it — or a maintainer overrides. Style, missing-tests double-counting, and speculative hardening deliberately do not block.
- INCONCLUSIVE — the review or the extractor didn't complete (usually a transient API throttle) or emitted no parseable verdict. Distinct, re-runnable, and also red: a flaky run never reads as a clean pass. Re-run via Actions → Claude Code Review → Run workflow (with the PR number), or override.
Override: a maintainer (write/maintain/admin) applies the review-ack label, honored only when applied at or after the current head commit (a stale ack can't clear a finding on newly-pushed code). Admin branch-protection bypass is the emergency break-glass.
PRs that edit .github/workflows/claude-code-review.yml itself: the review action refuses to run on a PR that modifies its own workflow file (a token-exfiltration guard — "Workflow validation failed … this is normal"). Such a PR shows the review failed and the gate INCONCLUSIVE; that's expected. Merge it via the non-review checks (syntax, semgrep) plus diff review; subsequent PRs are reviewed normally.
The interactive @claude bot is available for maintainer-triggered triage. Only comments authored by OWNER, MEMBER, or COLLABORATOR accounts trigger it, by design — outside contributors who type @claude won't get a response, to bound subscription-quota burn. See SECURITY.md §5 for the rationale.
zhfollows the existingcmd_*function pattern. New subcommands should mirror the closest existing analogue (cmd_blockfor a single mutation,cmd_epic_addfor a multi-arg batched mutation, etc.).- The MCP server's GraphQL-direct surface lives in
zh_api.py(config / auth / repo+workspace resolution / transport) andzh_graphql_ops.py(queries and mutations). New MCP tools that need direct GraphQL access should follow that split — keep query strings + business logic inzh_graphql_ops, route every API call throughRepoContext.queryso the unit tests can mock at one place. - Personal identifiers (real ticket numbers, org names, paths) don't belong in the repo. The agent file at
agents/zenhub.mdis a deliberately generic template. - Updates to commands should be reflected in
README.md,CLAUDE.md, andagents/zenhub.mdtogether — they all describe the same surface from different angles.
Run the suite in a dedicated virtualenv, not your global interpreter:
python -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pytest tests/ -vThe tests mock the network entirely (no live ZenHub or GitHub calls), so they're fast and don't need credentials. requirements-dev.txt is the single declared source for the test dependencies (pytest + numpy); CI installs from the same file, so a local venv run matches CI exactly.
Why a venv matters here: the suite imports its fixtures through the tests namespace package (tests/ has no __init__.py). If a different project that ships a regular tests package is editable-installed (pip install -e) into the interpreter you run pytest with, that regular package shadows this one and tests._fixtures fails to import (a regular package outranks a namespace package on sys.path). A clean .venv per the commands above is immune to whatever is installed globally. This is also exactly how CI stays reliable: it runs in a fresh, isolated environment every time.