ado-git-repo-insights 5.9.0

Extract Azure DevOps Pull Request metrics to SQLite and generate PowerBI-compatible CSVs.

ADO Git Repo Insights

[!NOTE] Python Compatibility: Python 3.10 uses pandas 2.x; Python 3.11+ uses pandas 3.x. Python 3.10 support will be evaluated in a future release.

Extract Azure DevOps Pull Request metrics to SQLite and generate PowerBI-compatible CSVs.

---

🚀 Quick Start

Choose your path:

I want to...	Use
Analyze PRs for my team via Azure DevOps pipelines	ADO Extension
Run analysis locally or integrate into custom CI/CD	Python CLI

---

☁️ Azure DevOps Extension

The ADO Extension provides a self-contained pipeline task with a built-in PR Insights Dashboard directly in your Azure DevOps project.

What you get:

• Pipeline task that extracts PR metrics automatically
• Interactive dashboard in your ADO project navigation
• No Python installation required
• PowerBI-compatible CSV exports

Get started: Extension User Guide

Minimal Pipeline Example

variables:
    - group: ado-insights-secrets # Contains PAT_SECRET

steps:
    - task: ExtractPullRequests@2
      inputs:
          organization: "MyOrg"
          projects: "Project1,Project2"
          pat: "$(PAT_SECRET)"

    - publish: $(Pipeline.Workspace)/aggregates
      artifact: aggregates

---

🐍 Python CLI

The Python CLI provides full control for local analysis, custom scripts, and non-ADO CI/CD systems.

Installation

Recommended: pipx (handles PATH automatically)

pipx install ado-git-repo-insights

Alternative: uv (fast, modern)

uv tool install ado-git-repo-insights

Advanced: pip (manual PATH setup may be needed)

pip install ado-git-repo-insights
# If 'ado-insights' not found, run: ado-insights setup-path

Verify installation: ado-insights --version

Diagnose issues: ado-insights doctor

Get started: CLI User Guide

Basic Usage

# Extract PR data
ado-insights extract \
  --organization MyOrg \
  --projects "Project1,Project2" \
  --pat $ADO_PAT \
  --database ./ado-insights.sqlite

# Generate CSVs for PowerBI
ado-insights generate-csv \
  --database ./ado-insights.sqlite \
  --output ./csv_output

# View local dashboard
ado-insights build-aggregates --db ./ado-insights.sqlite --out ./dataset
ado-insights dashboard --dataset ./dataset --open

---

📚 Documentation

👤 For End Users

Document	Description
Extension User Guide	Complete setup for ADO Extension users
CLI User Guide	Complete setup for Python CLI users
Troubleshooting	Common issues and solutions

📖 Reference

Document	Description
CLI Command Reference	All CLI commands and options
Task Input Reference	Extension task configuration
CSV Schema	PowerBI-compatible output format
Dataset Contract	Dashboard data format specification
Architecture	System design and data flow diagrams

⚙️ Operations

Document	Description
Runbook	Monitoring, recovery, and operational procedures
Data Retention	Storage model and security posture

🛠️ For Developers

Document	Description
Contributing Guide	How to contribute to this project
Development Setup	Setting up the development environment
Testing Guide	Running and writing tests
UI Bundle Sync	Dashboard UI synchronization process
Changelog	Version history and release notes

📋 Governance

Document	Description
Invariants	25 non-negotiable system invariants
Definition of Done	Completion criteria for features
Victory Gates	Verification checkpoints

---

⚖️ Feature Comparison

Feature	CLI	Extension
Installation	pip install	ADO Marketplace
Requires Python	Yes	No (bundled)
Pipeline syntax	Script steps	Task step
Works outside ADO	Yes	No
PR Insights Dashboard	Local server	Built into ADO
Configuration	YAML file or CLI args	Task inputs
Flexibility	Higher	Standard

---

⚡ How It Works

1. Extract — Fetches completed PRs from Azure DevOps REST API
2. Store — Persists data in SQLite with UPSERT semantics
3. Generate — Produces PowerBI-compatible CSVs and dashboard aggregates
4. Visualize — View metrics in the PR Insights Dashboard

The system uses incremental extraction by default (daily) with optional backfill mode to catch late changes (reviewer votes, status updates).

---

🔒 Security

• PAT with Code (Read) scope — Minimum required permission
• PATs are never logged — Secrets are redacted from all output
• No secrets stored at rest — Database contains only PR metadata
• Dashboard access — Requires Build Read permission on the analytics pipeline

---

💬 Support

• Issues & Features: GitHub Issues
• Publisher: OddEssentials

---

📄 License

MIT