GHQR: GitHub Quick Review

If you are looking for a way to quickly assess the configuration of your GitHub organizations and repositories, you might want to try GitHub Quick Review (ghqr): a CLI tool that scans your GitHub enterprises, organizations, and repositories and generates a detailed report with findings and recommendations based on the GitHub Well-Architected Framework.

The GitHub Well-Architected Framework

#

The GitHub Well-Architected Framework is a community-driven set of best practices curated by GitHub’s own engineers, partners, and customers. It’s structured around five pillars:

• Productivity – streamlined workflows and automation to accelerate team velocity.
• Collaboration – transparent project management and inclusive practices.
• Application Security – embedding security at every stage of development.
• Governance – policies and controls that balance innovation with oversight.
• Architecture – scalable, resilient GitHub environments at enterprise scale.

ghqr acts as an automated lens over these pillars, translating them into concrete, actionable findings against your actual GitHub configuration. Think of it as a Well-Architected review you can run from your terminal in seconds — covering everything from branch protections and secret scanning to Copilot policies and audit log streaming.

What ghqr evaluates

#

The tool covers a broad surface area, spanning both organization-level and repository-level settings:

Findings are prioritized by severity and category, so you can focus remediation efforts where they matter most. The output is available in Markdown, Excel (.xlsx) (default), and JSON — making it easy to attach results to a ticket, share with other teams, or feed into a pipeline.

Installation

#

Pick whatever fits your environment:

Linux / macOS

#

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

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

Docker

#

docker pull ghcr.io/microsoft/ghqr:latest

You can also grab a binary directly from the releases page.

Authentication

#

ghqr uses a Personal Access Token (PAT) set as an environment variable:

export GITHUB_TOKEN=<your-personal-access-token>

To get meaningful results across all check categories, make sure your token carries the right scopes:

A token with missing scopes will still run, but findings for those areas will be skipped silently. Double-check your scopes if results look incomplete.

Running your first scan

#

Scanning an organization is a single command:

ghqr scan -o my-org

For a full GitHub Enterprise scan:

ghqr scan -e my-enterprise

If your organization uses GitHub Enterprise Cloud with Data Residency (ghe.com), point ghqr at your custom subdomain:

ghqr scan -o my-org -H mycompany.ghe.com
# or
export GH_HOST=mycompany.ghe.com
ghqr scan -o my-org

For large enterprises, don’t worry about rate limits — ghqr handles GitHub API rate limiting automatically with exponential backoff.

Going further: the MCP Server

#

One of the more interesting features of ghqr is its built-in MCP (Model Context Protocol) server, which lets AI assistants like GitHub Copilot trigger scans and query results conversationally. This opens up workflows like asking Copilot directly: “What are the branch protection issues in my org?” and getting a structured answer back without leaving your editor.

Start the MCP server in stdio mode for IDE integration:

ghqr mcp

Or expose it over HTTP for remote or web-based access:

ghqr mcp --mode http --addr :8080

To wire it up with VS Code and GitHub Copilot, add this to your .vscode/mcp.json:

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

Once configured, the following MCP tools become available to your AI assistant:

A practical complement to the Well-Architected assessment

#

The GitHub Well-Architected Framework provides self-guided assessment checklists for each pillar. ghqr is a great way to back those checklists with real data from your environment — instead of answering “Is secret scanning enabled?” from memory, you get a concrete answer with a list of affected repositories and a direct link to the remediation documentation.

Running ghqr before a Well-Architected review gives you a head start and a clear remediation backlog to work from.

If you have any feedback, questions or issues, head over to the GitHub issues page: https://github.com/microsoft/ghqr/issues

Hope it helps!

References:

• ghqr GitHub repo
• GitHub Well-Architected Framework