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.

Create a folder for installing the ghqr binary.

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 (Cloud)
ghqr scan -e my-enterprise

# 4. Scan a GitHub Enterprise Server (GHES) instance
export GH_TOKEN=<your-ghes-personal-access-token>
ghqr scan --ghes ghes.example.com

# 1. Set your GitHub token
$env:GITHUB_TOKEN="<your-personal-access-token>"

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

# 3. Scan a GitHub Enterprise (Cloud)
.\ghqr scan -e my-enterprise

# 4. Scan a GitHub Enterprise Server (GHES) instance
$env:GH_TOKEN="<your-ghes-personal-access-token>"
.\ghqr scan --ghes ghes.example.com

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

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

For GitHub Enterprise Server scanning, create a PAT on your GHES instance with these scopes:

The GHES token is read from GH_TOKEN or GITHUB_TOKEN (in that order). Tokens without site_admin produce a degraded scan: license, admin stats, audit log, and management settings are reported as unavailable rather than treated as misconfigured.

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 -o my-org

# Scan a GitHub Enterprise (Cloud)
ghqr scan -e my-enterprise

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.

ghqr supports scanning on-premise GitHub Enterprise Server instances to assess security posture, configuration best practices, and compliance.

1. Set your GHES token — Create a Personal Access Token on your GHES instance with site_admin scope:

   export GH_TOKEN=<your-ghes-personal-access-token>

   ghqr reads the token from GH_TOKEN or GITHUB_TOKEN (in that order).

2. Run a GHES scan — Pass the GHES hostname (without protocol) via the --ghes flag:

   # Scan a single GHES instance
   ghqr scan --ghes ghes.example.com
   
   # Scan multiple GHES instances
   ghqr scan --ghes ghes1.example.com --ghes ghes2.example.com
   
   # Combine GHES scan with GitHub.com enterprise scan
   ghqr scan -e my-enterprise --ghes ghes.example.com
   
   # Scan with custom output name
   ghqr scan --ghes ghes.example.com -n my-ghes-audit-2026

The GHES audit log scanner detects these additional server-specific events:

• staff.fake_login — Admin impersonation of another user
• staff.unlock — Admin unlock of a user account
• staff.set_site_admin — Admin privilege escalation
• user.suspend / user.unsuspend — User account state changes

These are in addition to the standard events (repo.destroy, org.remove_member, etc.).

Some GHES configuration items cannot be verified automatically via the API. The scan report will flag these for manual review:

• Audit log forwarding (syslog) — Verify in Site Admin → Monitoring → Log forwarding
• Backup configuration — Verify GitHub Enterprise Server Backup Utilities (backup-utils) are configured and tested
• High Availability (HA) — Verify replica configuration if HA is required for your deployment

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}"
      }
    }
  }
}

MCP scan tool accepts these optional array arguments:

• enterprises
• organizations
• repositories (owner/repo)
• ghes_instances (GHES hostnames, for example ghes.example.com)

When using ghes_instances, ensure GH_TOKEN/GITHUB_TOKEN is valid for all specified instances.

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)

If ghqr cannot connect to your GHES instance:

1. Verify GH_TOKEN or GITHUB_TOKEN is set and was created on the GHES instance (not on github.com)
2. Ensure the hostname is correct and reachable from your network (e.g. ghes.example.com)
3. The token must have site_admin scope for full scanning capabilities
4. If some checks show "not available", the token may lack sufficient permissions — re-create with site_admin scope
5. GHES instances behind a VPN or firewall require network access from the machine running ghqr

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!

Azure DevOps Quick Review - a dedicated tool for Azure DevOps inspired by GitHub Quick Review (ghqr).

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.