ghqc is a Quality Control (QC) management system for data analysis workflows. It uses GitHub Issues as the unit of tracking: each file under QC gets a GitHub Issue, issues are grouped into Milestones, and the full QC lifecycle is managed through ghqc.
Available as both an interactive CLI and an embedded web UI.
flowchart TB
A([Create Issue]) --> B[Review File]
B --> C{Review Complete?}
C -- Changes Needed --> D[Comment with Diff]
D --> E[Implement Changes]
E --> B
C -- Approved --> F([Approve & Close Issue])
F -- Iterate for each file --> G([Close Milestone])
G --> H([Generate Record])
G --> I([Archive])
- Create — Open a GitHub Issue for a file, assign a checklist and reviewers.
- Review — The reviewer works through the checklist on GitHub, and optionally post a comment on the issue with a diff between their local, uncommitted changes and a commit.
- Comment — Post a comment on the issue linking two commits, with an optional diff and note, to document changes made in response to review feedback.
- Iterate — Repeat the review → comment cycle until the file is ready.
- Approve — Close the issue with an approval comment pinning the reviewed commit.
- Record — Generate a PDF summarizing the completed QC for a milestone.
- Archive — Bundle the files into a zip archive.
Each file under QC has a dedicated GitHub Issue. ghqc manages the full issue lifecycle:
| Command | Description |
|---|---|
ghqc issue create |
Create a new QC issue for a file |
ghqc issue comment |
Post a comment with commit diff to document changes made (author) |
ghqc issue review |
Post a review comment comparing working directory to a commit (reviewer) |
ghqc issue approve |
Approve the issue at a specific commit and close it |
ghqc issue unapprove |
Reopen an approved issue with a reason |
ghqc issue status |
Print the QC status, git status, and checklist progress |
Issues are grouped into Milestones for organizational purposes.
| Command | Description |
|---|---|
ghqc milestone status |
Tabular summary of all issues across selected milestones |
ghqc milestone record |
Generate a PDF QC record for selected milestones |
ghqc milestone archive |
Generate a zip archive of the record and associated files |
ghqc reads checklists, a logo, and options from a separate configuration repository.
| Command | Description |
|---|---|
ghqc configuration setup |
Clone the configuration repository |
ghqc configuration status |
Display configuration directory and available checklists |
| Command | Description |
|---|---|
ghqc sitrep |
Print a situation report: binary version, repository info, and configuration status |
| Command | Description |
|---|---|
ghqc ui |
Start the embedded web UI server and open the browser (ui feature) |
ghqc serve |
Start the REST API server without the embedded UI (api feature) |
Running ghqc ui serves an embedded React application. The UI provides:
- Status tab — Kanban board of all issues, grouped by QC status
- Create tab — Wizard for creating new QC issues
- Record tab — PDF record generation with file upload for context pages
- Archive tab — Archive generation
- Configuration tab — Configuration repo setup and status
cargo build --features cli --releasecargo build --features cli,ui --releasecargo run --features cli,api -- serve --port 3104
cd ui && bun run devghqc requires a configuration repository providing checklists, a logo, and optional settings. See the configuration docs for full details.
Quick setup:
# Using environment variable
export GHQC_CONFIG_REPO=https://github.com/your-org/your-config-repo
ghqc configuration setup
# Or pass directly
ghqc configuration setup https://github.com/your-org/your-config-repoAn example configuration repository is available at a2-ai/ghqc.example_config_repo.