ado-git-repo-insights 101.0.0

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

---

🤖 ML Features (Optional)

The dashboard supports optional ML-powered features for forecasting and insights. These features require additional pipeline configuration.

Predictions (Time-Series Forecasting)

Enable ML-powered forecasting for PR throughput and cycle times. Zero-config — no API key required.

Add to your pipeline YAML:

build-aggregates:
    run-predictions: true

Features:

• Cycle time forecasts using historical trends
• Throughput predictions for capacity planning
• Confidence intervals for forecast accuracy

AI Insights (Optional)

Enable AI-powered analysis of your PR patterns. Requires an OpenAI API key.

Setup:

1. Get an API key from platform.openai.com/api-keys
2. Add OPENAI_API_KEY as a secret variable in your ADO pipeline or variable group
3. Add to your pipeline YAML:

build-aggregates:
    run-insights: true
    openai-api-key: $(OPENAI_API_KEY)

Features:

• Automated bottleneck identification
• Reviewer workload recommendations
• Process improvement suggestions

Cost: Approximately $0.001-0.01 per pipeline run (uses GPT-4o-mini).

Data Privacy: Only aggregated metrics are sent to OpenAI. The following are never sent:

• PR titles, descriptions, or content
• User identities or email addresses
• Code changes or file contents
• Comments or review feedback

Troubleshooting ML Features

State	Cause	Solution
Setup Required	Artifact file not found	Enable feature in pipeline YAML and run pipeline
No Data	Empty forecasts/insights array	Accumulate more historical data (min. 4 weeks recommended)
Invalid Artifact	JSON parse or validation error	Check pipeline logs for generation errors
Unsupported Schema	Version mismatch	Update dashboard extension to latest version

---

🛠️ Developer Setup

Prerequisites

• Node.js 22+
• Python 3.12+ (for backend/CLI)
• pnpm (for extension development)

Extension Development

The extension uses pnpm exclusively. npm is not supported.

# Enable Corepack (provides pnpm)
corepack enable

# Install dependencies
cd extension
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

# Package VSIX
pnpm run package:vsix

Note: The root package.json uses npm for semantic-release tooling. Only the extension/ directory uses pnpm.

Python Development

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .

Demo Parity Build

The public demo and CLI synthetic demo are governed by one canonical demo publish flow:

./scripts/build-demo.sh

This rebuilds the extension UI shell, republishes the GitHub Pages demo surface, regenerates artifacts/demo-enterprise/, and promotes the published mirror under docs/data/.

For manual generated-asset sync outside the full demo build, use:

python scripts/manage_generated_artifacts.py sync --scope ui
python scripts/manage_generated_artifacts.py sync --scope all

Manual Demo Preview

For local manual testing of the synthetic demo dashboard in PowerShell:

cd extension
pnpm install
pnpm run build:ui

cd ..
python scripts/publish-demo-surface.py --source extension/dist/ui --docs-dir docs
python scripts/build-demo-dataset.py

cd docs
python -m http.server 8080

Open http://localhost:8080.

For repeat runs after dependencies are already installed:

cd extension
pnpm run build:ui

cd ..
python scripts/publish-demo-surface.py --source extension/dist/ui --docs-dir docs
python scripts/build-demo-dataset.py

cd docs
python -m http.server 8080

---

🔒 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