llm-wiki/raw/articles/microsoft-ghqr-github-quick-review-2026.md

---
source_url: "https://github.com/microsoft/ghqr"
ingested: 2026-07-02
sha256: dd59f33991f228bf76e894e6db96684ddc16916bd67812d5446a7d00e806c7d4
discovered_from:
  platform: discord
  channel_id: "1028287639918497822"
  channel_name: "chat"
  message_id: "1522177939561644194"
  author_id: "890908900520505354"
  posted_at: "2026-07-02T09:51:41.490000000Z"
  message_excerpt: |-
    Microsoft GitHub Quick Review repo
---

[![build](https://github.com/microsoft/ghqr/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/ghqr/actions/workflows/build.yml)
[![CodeQL](https://github.com/microsoft/ghqr/actions/workflows/codeql.yml/badge.svg)](https://github.com/microsoft/ghqr/actions/workflows/codeql.yml)
[![Github All Releases](https://img.shields.io/github/downloads/microsoft/ghqr/total.svg)]()

# 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

| Area | Scope | Examples |
|------|-------|---------|
| **Security** | Org, Repo | Dependabot alerts, secret scanning, code scanning, GHAS |
| **Access Control** | Org, Repo | 2FA enforcement, member privileges, SAML SSO, CODEOWNERS |
| **Branch Protection** | Repo | Required reviews, status checks, admin enforcement |
| **Copilot** | Org | Seat usage, content exclusions, policy configuration, MCP settings |
| **Governance** | Org | IP allow lists, repository creation policies, fork policies |
| **Audit Log** | Enterprise, Org | Audit log streaming, suspicious event detection |
| **Community** | Repo | Contributing guide, issue templates, code of conduct |
| **Actions** | Org, Repo | Workflow permissions, allowed actions, self-hosted runners |
| **Dependencies** | Repo | Dependabot version updates, security updates |
| **Metadata** | Repo | Description, topics, visibility, archival status |

### GitHub Enterprise Server (GHES)

| Area | Examples |
|------|---------|
| **Server Configuration** | Version currency, subdomain isolation, TLS, private mode |
| **Authentication** | Auth mode (SAML/LDAP/CAS), open signup, password authentication |
| **License** | Seat utilization, license expiration warnings |
| **Security** | GHAS enablement, secret scanning, push protection, code scanning |
| **Dependencies** | Dependabot alerts and security updates enablement |
| **Actions** | GitHub Actions enablement, self-hosted runner security |
| **Audit Log** | Suspicious event detection, log forwarding, staff impersonation |
| **Infrastructure** | Admin SSH access, site admin count, backup-utils, HA replicas |
| **Admin Stats** | User/org/repo counts, suspended user ratio, disabled orgs |

## 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
bash -c "$(curl -fsSL https://raw.githubusercontent.com/microsoft/ghqr/main/scripts/install.sh)"
```

Or download the latest release from the [releases page](https://github.com/microsoft/ghqr/releases).

### Windows

```powershell
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](https://github.com/microsoft/ghqr/releases).

### Docker

```bash
docker pull ghcr.io/microsoft/ghqr:latest
```

### Build from Source

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

## Quick Start Linux / macOS

```bash
# 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
```
## Quick Start Windows
```PowerShell
# 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

```


## Usage

### Authentication

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

- **Personal Access Token (PAT)**: Set the `GITHUB_TOKEN` environment variable

#### Required Token Scopes (GitHub.com)

| Scope | Purpose |
|-------|---------|
| `read:org` | Read organization settings and members |
| `read:enterprise` | Read enterprise settings |
| `repo` | Read repository settings, branch protection, and security features |
| `read:audit_log` | Read audit log configuration |
| `read:user` | Read user information |
| `copilot` | Read Copilot seat and policy information |

#### Required Token Scopes (GHES)

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

| Scope | Purpose |
|-------|---------|
| `site_admin` | Read server settings, license, admin stats, and audit log |
| `read:org` | Read organization settings and members |
| `repo` | Read repository settings and security features |
| `read:audit_log` | Read audit log events |

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.

### GitHub Enterprise Cloud with Data Residency (GHE.com)

If your organization uses [GitHub Enterprise Cloud with data residency](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/about-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

```bash
# 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](#github-enterprise-cloud-with-data-residency-ghecom).

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

```bash
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:

```bash
# 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:

| Flag | Default | Description |
|------|---------|-------------|
| `-o, --orgs` | `1` | Number of organizations to synthesize |
| `-r, --repos` | `5` | Number of repositories per organization |
| `-e, --enterprise` | _(none)_ | Optional enterprise slug wrapping all orgs |
| `--profile` | `typical` | Distribution profile: `clean`, `typical`, or `noisy` |
| `--seed` | `0` | RNG seed for reproducible output (`0` = time-based) |
| `-O, --output` | `ghqr_mock_<timestamp>.json` | Output JSON path |
| `--render` | `false` | After writing JSON, replay it through the scan pipeline to produce md/xlsx |

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/`](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. **Set your GHES token** — Create a Personal Access Token on your GHES instance with `site_admin` scope:

   ```bash
   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:

   ```bash
   # 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

| Category | Checks |
|----------|--------|
| **Server Version** | Installed version detection, supported release verification |
| **Authentication** | Auth mode (built-in/SAML/LDAP/CAS), open signup, password auth |
| **Networking** | Subdomain isolation (critical), private mode, TLS enforcement |
| **License** | Seat utilization, expiration warnings (30/90 days) |
| **Advanced Security** | GHAS enablement, secret scanning, push protection, code scanning |
| **Dependencies** | Dependabot alerts and security updates enablement |
| **Actions** | GitHub Actions enablement, self-hosted runner security guidance |
| **Audit Log** | Suspicious event detection, log forwarding recommendations |
| **Infrastructure** | Site admin count, backup-utils verification, HA replica checks |
| **Admin Stats** | User/org/repo counts, suspended user ratio, disabled orgs |

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

```bash
# 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`:

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

#### Available MCP Tools

| Tool | Description |
|------|-------------|
| `scan` | Scan GitHub enterprises, organizations, or repositories for best practices and security recommendations |

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.

## Troubleshooting

### Common Issues

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

```bash
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 [Required Token Scopes](#required-token-scopes-githubcom))
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-enterprise-cloud-with-data-residency-ghecom))

### GHES Connection Errors

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

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

```bash
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](https://github.com/microsoft/ghqr/issues)
- For questions and discussion: [GitHub Discussions](https://github.com/microsoft/ghqr/discussions)

## Contributors

Thanks to everyone who has contributed!

<a href="https://github.com/microsoft/ghqr/graphs/contributors">
  <img src="https://contributors-img.web.app/image?repo=microsoft/ghqr" />
</a>

## Acknowledgements
[Azure DevOps Quick Review](https://github.com/microsoft/adoqr) - 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](CODE_OF_CONDUCT.md).

## 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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.