microsoft/adoqr

microsoft/adoqr

Description: Azure DevOps Quick Review: Evaluate your enterprise and organizations against Azure DevOps best practices

Language: PowerShell

License: MIT

Stars: 54

Forks: 7

Open issues: 8

Created: 2026-05-14T15:04:58Z

Pushed: 2026-05-29T17:52:45Z

Default branch: main

Fork: no

Archived: no

README:

Azure DevOps Quick Review

Azure DevOps Quick Review (adoqr) is a PowerShell-based tool that analyzes Azure DevOps organizations and projects to evaluate adherence to Azure DevOps best practices and Microsoft recommendations. It produces a comprehensive review of your ADO resources so you can easily identify misconfigured settings, gaps, and high-impact areas for improvement.

This is a sister tool to GitHub Quick Review (ghqr) — same idea, same shape of output, but purpose-built for Azure DevOps.

A bundled GitHub Copilot skill is included to help you refine the script, interpret results, and explore remediation options through natural language in VS Code.


What adoqr Checks

> Browse the full controls reference: Controls reference → > — a searchable catalogue of every control evaluated by adoqr, with descriptions, > step-by-step remediation, and links to Microsoft Learn.

Azure DevOps Quick Review evaluates your ADO resources across the following areas, with 120+ individual best-practice checks:

| Category | Scope | Examples | |---|---|---| | Identity & Access | Organization, Project | AAD/Entra ID auth, guest and external users, admin group sizing, service-account hygiene | | Governance | Organization, Project | Public projects, third-party OAuth, extension review, audit log streaming | | Pipelines & Actions | Project, Pipeline | Inherited permissions, fork protections, CI triggers, approvals, agent pools | | Secrets & Credentials | Pipeline, Repo | Build/release secrets, credential scanning, secure files, variable groups | | Repos & Branch Protection | Project, Repo | Branch policies, required reviewers, build validation, inactive repos | | Service Connections | Project | Project scoping, recipient access, federated credentials | | Resources | Project | Variable groups, secure files, environments, feeds | | PAT Hygiene | User | Critical scopes, full-access tokens, expiry |

Scan Results

The output of an adoqr run includes:

• Recommendations — prioritized findings with severity, affected areas, and a step-by-step fix
• Organization summary — a single view of org-level posture
• Per-project reports — best-practice adoption for each project
• Executive dashboard — KPI cards, an adoption ring, and a project comparison table
• Not checked explanations — reason categories and scoped details for controls that need permissions, prerequisites, configuration data, or manual review
• Remediation plan — every unique action ranked by impact, with links to Microsoft Learn

Each run creates a timestamped folder under assessments/ (e.g. assessments/myorg-2026-04-12-143022/) so previous results are preserved. The folder contains:

| File | Description | |---|---| | *-org-assessment.md | Organization-level Markdown report | | *--assessment.md | Per-project Markdown reports | | *-executive-summary.html | Visual HTML dashboard with KPIs, adoption ring, and project comparison | | *-remediation-plan.html | Prioritized remediation actions ranked by impact, with step-by-step fix instructions and Microsoft Learn links |

Installation

Prerequisites

• PowerShell 5.0+ (PowerShell 7+ recommended for parallel execution)
• Azure CLI v2.81.0+
• Azure DevOps Azure CLI extension (azure-devops) - installed automatically on first run if missing
• An Azure CLI session authenticated with access to the target ADO organization (az login)
• GitHub Copilot extension for VS Code (optional, for skill-assisted workflows)

Clone Repository

git clone https://github.com/microsoft/adoqr.git

Run PowerShell Script

# 1. Sign in
az login

# 2. Review an organization
.\invoke-adoqr.ps1 -Organization "MyOrg"

# 3. Review specific projects only
.\invoke-adoqr.ps1 -Organization "MyOrg" -Project "WebApp","API"

Reports are saved to a timestamped subfolder under assessments/. The executive HTML summary auto-opens in your browser when the assessment completes.

If the Azure DevOps Azure CLI extension is not already installed, adoqr installs it automatically before the review starts.

Configuration File (optional)

By default adoqr flags repositories and projects as inactive after 180 days without a commit. If you want a different threshold, create a settings file named adoqr.settings.psd1 in the same directory as invoke-adoqr.ps1:

# Copy the example file and uncomment / edit the values you want to change
Copy-Item adoqr.settings.example.psd1 adoqr.settings.psd1

Edit the new file and uncomment the setting you want to override, for example:

@{
# Flag repos / projects with no commits in the last 90 days (default: 180)
InactiveRepoDays = 90
}

adoqr.settings.psd1 is listed in .gitignore so your local overrides are never committed. All settings are optional — only add the keys you want to change.

Usage

Authentication

adoqr supports the following authentication method:

• Azure CLI session — the script obtains an Azure DevOps bearer token from

the active az session. No PAT is required.

# Interactive sign-in (recommended)
az login

# Confirm the active subscription / tenant
az account show

The signed-in identity needs at least Project Collection Valid Users access to the target organization. For full coverage of admin-group and audit checks, the identity should be a Project Collection Administrator.

The -IncludeGraphCheck switch additionally calls Microsoft Graph and requires the User.Read.All permission to be consented for the same identity.

Running Assessments

| Parameter | Required | Description | |---|---|---| | -Organization | Yes | The ADO organization URL (e.g. https://dev.azure.com/MyOrg) or short name (MyOrg). | | -Project | No | One or more project…