GitHub Quick Review (ghqr) is a powerful command-line interface (CLI) tool that analyzes GitHub enterprises, organizations, and repositories to ensure compliance with GitHub best practices and security recommendations. Its main objective is to offer users a comprehensive assessment of their GitHub resources, allowing them to easily identify security gaps, misconfigured settings, and areas for improvement.

GitHub Quick Review (ghqr) evaluates your GitHub resources across the following areas:

The output generated by GitHub Quick Review (ghqr) includes:

• Recommendations: Prioritized findings with severity and category
• Organizations: Summary of all scanned organizations and their posture
• Repositories: Per-repository findings with branch protection, security features, and access settings
• Issues Sheet: All findings with recommendations and links to documentation

Outputs are available in Markdown (.md), Excel (.xlsx) (default) and JSON formats.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/microsoft/ghqr/main/scripts/install.sh)"

Or download the latest release from the releases page.

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/microsoft/ghqr/main/scripts/install.ps1'))

Or download the latest release from the releases page.

docker pull ghcr.io/microsoft/ghqr:latest

git clone https://github.com/microsoft/ghqr.git
cd ghqr
make

# 1. Set your GitHub token
export GITHUB_TOKEN=<your-personal-access-token>

# 2. Scan an organization
ghqr scan -o my-org

# 3. Scan a GitHub Enterprise
ghqr scan -e my-enterprise

GitHub Quick Review (ghqr) supports the following authentication methods:

• Personal Access Token (PAT): Set the GITHUB_TOKEN environment variable

If your organization uses GitHub Enterprise Cloud with data residency, your API endpoints are on a custom ghe.com subdomain instead of github.com.

Specify your hostname using either:

• The --hostname / -H flag: ghqr scan -o my-org -H mycompany.ghe.com
• The GH_HOST environment variable: export GH_HOST=mycompany.ghe.com

# Scan a single organization
ghqr scan

For GitHub Enterprise Cloud with Data Residency, see Data Residency.

To iterate on evaluation rules or re-render reports without re-querying GitHub, replay an existing scan JSON file:

ghqr scan --from-json ghqr_20260417_143426.json

The scan stages are skipped — no GitHub API calls or token are required — and a fresh <input>_replay_<timestamp>.json (plus xlsx/markdown when enabled) is produced. Note: the JSON renderer compacts collaborators and deploy_keys arrays into summaries, so per-collaborator and per-deploy-key rules cannot be re-evaluated from a replayed file.

For demos, report-template development, or load-testing the renderers without a GitHub token, generate a synthetic scan JSON for any number of organizations and repositories:

# 1 org with 5 repos (defaults)
ghqr mock

# 3 orgs, 10 repos each, wrapped in an enterprise; deterministic output
ghqr mock -o 3 -r 10 -e mock-ent --seed 42

# Generate JSON and immediately render markdown + xlsx in one shot
ghqr mock -o 5 -r 20 --profile noisy --render

Flags:

The generator emits only raw entity facts — recommendations and summaries are computed by the existing evaluation stage when the file is replayed via --from-json. This keeps mock data automatically in sync with the rule definitions in internal/recommendations/definitions/. No GitHub API calls are made; no token is required.

Run ghqr -h for all available commands and options.

GitHub Quick Review includes an MCP server that enables AI assistants to interact with ghqr functionality:

# Start MCP server in stdio mode (for IDE integration)
ghqr mcp

# Start MCP server in HTTP/SSE mode (for remote/web access)
ghqr mcp --mode http --addr :8080

Add to your .vscode/mcp.json:

{
  "servers": {
    "ghqr": {
      "type": "stdio",
      "command": "ghqr",
      "args": ["mcp"],
      "env": {
        "GITHUB_TOKEN": "${input:githubToken}"
      }
    }
  }
}

If you encounter any issue while using GitHub Quick Review (ghqr), run with the --debug flag:

ghqr scan -o my-org --debug

If you receive 401 Unauthorized or 403 Forbidden errors:

1. Verify your GITHUB_TOKEN is set and valid
2. Check that your token has the required scopes (see Required Token Scopes)
3. For enterprise resources, ensure your token has read:enterprise scope and that SSO is authorized for the enterprise
4. If using GitHub Enterprise Cloud with Data Residency (GHE.com), ensure you pass --hostname or set GH_HOST (see Data Residency)

GitHub API has rate limits (5000 requests/hour for REST, 5000 points/hour for GraphQL). For large enterprises or organizations, ghqr handles rate limiting automatically with exponential backoff.

Make sure you have Go 1.26.x or higher installed.

git clone https://github.com/microsoft/ghqr.git
cd ghqr
make

This project uses GitHub Issues to track bugs and feature requests. Please search existing issues before filing a new one.

• For bugs and feature requests: GitHub Issues
• For questions and discussion: GitHub Discussions

Thanks to everyone who has contributed!

This project has adopted the Microsoft Open Source Code of Conduct.

Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.