GitHub Quick Review

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.

What ghqr Checks

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

GitHub Enterprise Cloud / Organizations / Repositories

GitHub Enterprise Server (GHES)

Scan Results

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.

Installation

Create a folder for installing the ghqr binary.

Linux / macOS

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

Or download the latest release from the releases page.

Windows

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

docker pull ghcr.io/microsoft/ghqr:latest

Build from Source

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

Quick Start Linux / macOS

# Option A: Authenticate with the gh CLI (recommended — no env vars needed)
gh auth login

# Option B: Set a Personal Access Token manually
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
gh auth login --hostname ghes.example.com   # recommended
# or: export GH_TOKEN=<your-ghes-personal-access-token>
ghqr scan --ghes ghes.example.com

Quick Start Windows

# Option A: Authenticate with the gh CLI (recommended — no env vars needed)
gh auth login

# Option B: Set a Personal Access Token manually
$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
gh auth login --hostname ghes.example.com   # recommended
# or: $env:GH_TOKEN="<your-ghes-personal-access-token>"
.\ghqr scan --ghes ghes.example.com

Usage

Authentication

GitHub Quick Review (ghqr) resolves credentials via a chain, similar to Azure's DefaultAzureCredential:

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. gh CLI config — run gh auth login once and ghqr picks it up automatically
4. System keyring (macOS Keychain, Linux Secret Service)

For GHES, GITHUB_TOKEN is scoped to github.com only (CVE-2024-53859). Use GH_TOKEN or gh auth login --hostname <ghes-host> instead.

Required Token Scopes (GitHub.com)

Note: Organization code security configurations (settings.security.code_security_configurations in the JSON output) are read with read:org, but GitHub also requires the token user to be an organization owner or security manager. Otherwise ghqr records them as not readable (*_readable: false with a *_unavailable_reason of forbidden, not_found, or error) instead of failing the scan. These configurations replace the deprecated *_enabled_for_new_repos organization fields, which can report false for organizations that set defaults through a default code security configuration.

Required Token Scopes (GHES)

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

The GHES token is read from GH_TOKEN first, then the gh CLI config (run gh auth login --hostname <host>), then GITHUB_TOKEN as a backward-compat fallback.

GitHub Enterprise Cloud with Data Residency (GHE.com)

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

Running Scans

# 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.

Replaying Enrichment from a Previous Scan

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.

Generating Synthetic (Mock) Scans

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.

Scanning GitHub Enterprise Server (GHES)

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

Setup

1. Authenticate for your GHES instance — Choose the recommended approach or use a PAT:

   # Recommended: authenticate once with the gh CLI
   gh auth login --hostname ghes.example.com
   
   # Alternative: set a Personal Access Token
   export GH_TOKEN=<your-ghes-personal-access-token>
   

   ghqr resolves the GHES token via: GH_TOKEN env var → gh CLI config → system keyring → GITHUB_TOKEN (backward compat).

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
   

What GHES Scan Checks

GHES-Specific Suspicious Audit Events

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.).

Manual Verification Items

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

MCP Server (Model Context Protocol)

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

Configuring with VS Code / GitHub Copilot

Add to your .vscode/mcp.json:

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

Available MCP Tools

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, run gh auth login --hostname <host> or set GH_TOKEN for each GHES instance.

Troubleshooting

Common Issues

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

ghqr scan -o my-org --debug

Authentication Errors

If you receive 401 Unauthorized or 403 Forbidden errors:

1. Verify your token is resolved: run gh auth status or check GH_TOKEN/GITHUB_TOKEN env vars
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)

GHES Connection Errors

If ghqr cannot connect to your GHES instance:

1. Verify authentication: run gh auth status --hostname <ghes-host>, or check that GH_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

Rate Limiting

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.

Building Locally

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

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

Support

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

Contributors

Thanks to everyone who has contributed!

Acknowledgements

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

Code of Conduct

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

Trademark Notice

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.