$ show microsoft/ghqr
ghqr is a Go-based CLI tool for scanning GitHub enterprises, organizations, and repositories against a comprehensive set of best-practice rules. It produces actionable reports in Markdown, Excel, and JSON formats, with prioritized findings, remediation plans, and manual checklists. The tool also includes an MCP (Model Context Protocol) server for AI assistant integration, enabling interactive scanning and recommendations via stdio or HTTP/SSE. A deterministic mock generator allows demos and testing without live API calls. The architecture follows a composable pipeline pattern: initialization, data loading (from live API or JSON replay), enterprise/GHES/organization/repository discovery and scanning, evaluation against YAML-defined rules, and report rendering. Scanners use both REST and GraphQL APIs with batch queries, rate-limit handling, and tri-state boolean support for GHES on-prem instances. The rule registry is embedded as YAML files, loaded at startup into a typed registry that evaluators reference by stable rule IDs. Key entry points are the `ghqr scan`, `ghqr mcp`, `ghqr mock`, and `ghqr list-recommendations` commands. External dependencies include the GitHub API (REST and GraphQL), the `excelize` library for Excel output, and the `mcp-go` library for MCP protocol support. The tool is containerized via Docker and published to GHCR, with install scripts for Linux, macOS, and Windows.
The LLM identified 4 files worth highlighting for reuse:
Defines the Stage interface and ScanPipelineBuilder for composing scan stages. Each stage implements Execute, Skip, and Name methods, allowing flexible pipeline construction with conditional execution. The builder provides a fluent API (WithStage, Build) and supports replay mode by skipping live API stages. This pattern is reusable for any multi-step data processing or ETL pipeline.
Creates a shared HTTP transport with connection pooling and automatic retry on GitHub primary and secondary rate limits. Uses exponential backoff and respects Retry-After headers. The transport is reused across all GitHub API clients (REST and GraphQL), ensuring efficient resource usage. This component can be extracted for any project needing resilient HTTP calls with rate-limit handling.
Implements batch fetching of repository data via GraphQL aliases, fetching up to 5 repos per request to stay within GitHub's complexity limits. Includes proactive sleep before requests to avoid secondary rate limits and handles pagination. The conversion layer (batchDataToRepositoryNode) allows reuse of existing mapping functions. This pattern is reusable for any GraphQL API with batch query needs.
Generates synthetic GitHub entity data (enterprises, orgs, repos) with configurable profiles (clean, typical, noisy) and deterministic seeds. Produces JSON that matches the scan output schema, enabling round-trip testing of the pipeline without live API calls. The generator is self-contained and can be adapted for any system needing realistic mock data for demos or integration tests.