GitHub Quick Review

• 1: Overview
• 2: Install
• 3: Usage
• 4: Recommendations
• 5: Contribution Guidelines
• 6: Troubleshooting and Support
• 7: Resources and References

1 - Overview

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 security posture, allowing them to easily identify security gaps, misconfigured settings, and areas for improvement.

What ghqr Checks

GitHub Enterprise Cloud / Organizations / Repositories

GitHub Enterprise Server (GHES)

Scan Results

The output generated by GitHub Quick Review (ghqr) includes the following sheets when using the default Excel format:

• 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: All findings with recommendations and links to documentation

Output Formats

GitHub Quick Review (ghqr) supports three output formats:

• Excel (.xlsx) (default): Multi-sheet workbook with all findings, summaries, and links
• Markdown (.md): Text-based report suitable for inclusion in wikis or pull requests
• JSON: Machine-readable output suitable for integration with other tools or pipelines

Recommendation Severity Levels

Each recommendation is assigned one of the following severity levels:

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.

2 - Install

Install on Linux or macOS

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

Or download the latest release from the releases page.

Install on 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.

Install with Docker

docker pull ghcr.io/microsoft/ghqr:latest

Run a scan using Docker:

docker run --rm \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  ghcr.io/microsoft/ghqr:latest \
  scan -o my-org

Build from Source

Requires Go 1.24 or higher.

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

The compiled binary is placed in the bin/ directory.

3 - Usage

Authentication

GitHub Quick Review (ghqr) requires a GitHub Personal Access Token (PAT). Set the GITHUB_TOKEN environment variable before running any scan.

Required Token Scopes for GitHub.com

Required Token Scopes for GHES

Create a Personal Access Token on your GHES instance with these scopes:

Note: For GHES, ghqr reads the token from GH_TOKEN first, then falls back to GITHUB_TOKEN. 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.

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

Running Scans

Scan a Single Organization

export GITHUB_TOKEN=<your-personal-access-token>
ghqr scan -o my-org

Scan a GitHub Enterprise

ghqr scan -e my-enterprise

Scan a GitHub Enterprise Server Instance

export GH_TOKEN=<your-ghes-personal-access-token>
ghqr scan --ghes ghes.example.com

Scan Multiple GHES Instances

ghqr scan --ghes ghes1.example.com --ghes ghes2.example.com

Combine GitHub.com Enterprise and GHES Scans

ghqr scan -e my-enterprise --ghes ghes.example.com

Specify a Custom Output Name

ghqr scan -o my-org -n my-org-audit-2026

GitHub Enterprise Server (GHES) Scan Details

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

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 flags 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

Output Formats

GitHub Quick Review (ghqr) supports three output formats: xlsx (default), markdown, and json.

xlsx (Default)

The default output format produces an Excel workbook with multiple sheets covering all findings, organization summaries, and repository details.

ghqr scan -o my-org

markdown

Generate a Markdown report suitable for wikis, pull request descriptions, or archiving alongside code:

ghqr scan -o my-org --markdown

json

Generate a machine-readable JSON report for integration with other tools or pipelines:

ghqr scan -o my-org --json

Changing the Output File Name

Use the -n flag to set a custom output file name:

# Linux / macOS
timestamp=$(date '+%Y%m%d%H%M%S')
ghqr scan -o my-org -n "ghqr_report_$timestamp"

# Windows PowerShell
$timestamp = Get-Date -Format 'yyyyMMddHHmmss'
.\ghqr scan -o my-org -n "ghqr_report_$timestamp"

Replaying a Previous Scan

To re-evaluate rules or re-render reports without re-querying the GitHub API, replay an existing scan JSON file:

ghqr scan --from-json ghqr_20260417_143426.json

The scan stages are skipped, and a fresh output file is produced. No GitHub API calls or token are required.

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 testing the renderers without a GitHub token, generate a synthetic scan:

# 1 org with 5 repos (defaults)
ghqr mock

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

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

Mock Command Flags

MCP Server (Model Context Protocol)

GitHub Quick Review includes a Model Context Protocol (MCP) server that enables AI assistants and tools to interact with ghqr functionality. The MCP server can run in two modes.

stdio Mode (Default)

The stdio mode is designed for integration with tools like VS Code and AI assistants that communicate via standard input/output:

ghqr mcp

HTTP/SSE Mode

The HTTP/SSE mode allows the MCP server to be accessed over HTTP, enabling remote access and web-based integrations:

# Start on default port (:8080)
ghqr mcp --mode http

# Start on a custom port
ghqr mcp --mode http --addr :3000

# Start with a specific host and port
ghqr mcp --mode http --addr localhost:9090

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

The scan tool accepts these optional array arguments:

• enterprises - Enterprise slugs to scan
• organizations - Organization slugs to scan
• repositories - Repository full names in owner/repo format
• ghes_instances - GHES hostnames (for example ghes.example.com)

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

Listing All Recommendations

You can list all available recommendations in the built-in registry:

# List as a formatted table
ghqr list-recommendations

# Filter by scope
ghqr list-recommendations --scope repository

# Filter by severity
ghqr list-recommendations --severity critical

# Filter by category
ghqr list-recommendations --category branch_protection

# Output as JSON
ghqr list-recommendations --json

# Output as a Markdown table
ghqr list-recommendations --markdown

Debugging

Use the --debug flag to enable verbose logging for any command:

ghqr scan -o my-org --debug

Help

Get help for any command by running:

ghqr --help
ghqr scan --help
ghqr mcp --help
ghqr mock --help

4 - Recommendations

GitHub Quick Review (ghqr) evaluates your GitHub resources against the following best-practice recommendations. Each recommendation has a stable ID, scope, category, and severity level.

Recommendations are grouped by scope:

• repository - Evaluated against each scanned repository
• organization - Evaluated against each scanned organization
• enterprise - Evaluated against a GitHub Enterprise Cloud tenant
• ghes - Evaluated against a GitHub Enterprise Server appliance

Severity levels range from critical (immediate risk) to info (informational observation). See the Overview for a full description of severity levels.

5 - Contribution Guidelines

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Adding or Modifying Recommendations

Recommendations are stored as YAML files under internal/recommendations/definitions/. Each file maps to a scope (repository, organization, enterprise, ghes). To add a new recommendation:

1. Open the appropriate YAML file for the scope (e.g., internal/recommendations/definitions/repository/security.yaml).

2. Add a new entry following the existing schema:

   - id: repo-sec-010
     scope: repository
     title: Short human-readable title
     category: security
     severity: high
     description: What the check evaluates and why it matters.
     recommendation: Actionable remediation guidance.
     learnMore: https://docs.github.com/...
     tags: [security]
     enabled: true
   

3. Implement the corresponding evaluation logic in internal/scanners/bestpractices/.

4. Add a unit test covering the positive (issue found) and negative (no issue) paths.

5. Run make test before submitting your pull request.

Contributing to Documentation

The following packages are required to build and run the documentation site locally:

• git
• hugo (extended edition, version 0.110.0 or higher)
• nodejs (version 18 or higher)

Running the Docs Site Locally

1. Fork the ghqr repository and clone it locally.

2. Navigate to the docs folder:

   cd ghqr/docs
   

3. Install Node modules:

   npm install
   

4. Start the Hugo development server:

   hugo server
   

5. Open your browser at http://localhost:1313/ghqr/.

6 - Troubleshooting and Support

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

ghqr scan -o my-org --debug

Authentication Errors

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 Usage - Authentication).
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 Usage - GHE.com).

GHES Connection Errors

If ghqr cannot connect to your GitHub Enterprise Server 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 the token 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 (5,000 requests/hour for REST, 5,000 points/hour for GraphQL). For large enterprises or organizations, ghqr handles rate limiting automatically with exponential backoff. If a scan is taking a long time, this is expected behavior for large environments.

Unexpected or Missing Findings

• Ensure your token has all the required scopes listed in Usage - Authentication.
• Confirm the organization or enterprise slug is correct and that the token has been granted SSO access if your enterprise uses SAML.
• For repositories that show no findings, verify the token has repo scope (not just public_repo).

Support

This project uses GitHub Issues to track bugs and feature requests. Before logging an issue, please check the troubleshooting steps above.

Please search the existing issues before filing new ones to avoid duplicates.

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

Support for this project is limited to the resources listed above.

7 - Resources and References

GitHub Documentation

• GitHub Advanced Security
• Branch Protection Rules
• Repository Rulesets
• Dependabot Alerts
• Secret Scanning
• Code Scanning (CodeQL)
• GitHub Actions Security
• GitHub Enterprise Cloud with Data Residency
• GHES Administration
• GHES Backup Utilities
• Requiring 2FA in an Organization
• GitHub Copilot for Organizations
• Model Context Protocol (MCP)

Related Projects

• Azure DevOps Quick Review (adoqr) - A dedicated tool for Azure DevOps inspired by ghqr
• Azure Quick Review (azqr) - The sister project for Azure resource compliance scanning