ado-git-repo-insights 101.28.1

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

ADO Git Repo Insights

[!NOTE] Python Compatibility: Requires Python 3.12 or later. Uses pandas 3.x.

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@3
      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.

# Install (recommended)
pipx install ado-git-repo-insights

# Extract → CSV → dashboard
ado-insights extract --organization MyOrg --projects "Project1,Project2" --pat $ADO_PAT --database ./ado-insights.sqlite
ado-insights generate-csv --database ./ado-insights.sqlite --output ./csv_output
ado-insights build-aggregates --db ./ado-insights.sqlite --out ./dataset
ado-insights dashboard --dataset ./dataset --open

Get started: CLI User Guide — covers uv and pip install paths, configuration files, and CI/CD integration.

---

📚 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
Demo Data Versioning	Canonical demo build and parity policy
UI Bundle Sync	Dashboard UI synchronization process
Changelog	Version history and release notes

📋 Governance

Document	Description
Invariants	Non-negotiable system invariants
Definition of Done	Completion criteria for features
Verification 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).

Comment extraction is opt-in via --include-comments on extract; to cover PR comments for history that predates enabling it, run the one-time backfill-comments subcommand — see the extension guide or CLI guide.

---

🤖 ML Features (Optional)

The dashboard supports optional ML-powered features: time-series forecasting for cycle time and throughput (zero-config, no API key) and AI insights for bottleneck analysis (requires an OpenAI API key, ~$0.001–0.01 per pipeline run, only aggregated metrics sent — never PR content, identities, or code).

Setup and troubleshooting: Enable ML Features

---

🛠️ Developer Setup

• Recommended: open in a Dev Container — handles all per-platform tooling automatically.
• Native setup (advanced): docs/development/setup.md.
• Contributing: CONTRIBUTING.md.

---

🔒 Security

PATs use minimum Code (Read) scope, are never logged, and are never persisted at rest. Full posture: docs/SECURITY.md.

---

💬 Support

• Issues & Features: GitHub Issues
• Publisher: OddEssentials

---

📄 License

MIT