PipelineGraph.Cli 1.0.2324

Pipeline Graph

A .NET CLI tool that discovers and visualizes which Azure DevOps pipelines use which shared pipeline templates.

Features

• Definition-based dependency scanning — scans all pipeline definitions in an Azure DevOps organization and resolves template: references, including nested/transitive templates across repositories (pipeline definition subcommand).
• Run-based scanning — analyzes completed pipeline runs and reports the full Stage → Job → Step hierarchy with timing, results, worker names, and environment deployments (pipeline run subcommand).
• Run compliancy report — reads a pipeline run JSON report and produces a Markdown summary table showing pipeline runs with optional per-task completion/success checks (pipeline run-compliancy subcommand).
• Single-repo template graph — generates a Mermaid dependency graph and a Markdown table of all pipeline templates within a single repository (repo-graph subcommand). Use --exclude-pipelines to automatically detect and omit pipeline definition files.
• JSON report — produces a structured JSON report of template usage across projects and pipelines.
• Mermaid dependency graph — generates a Mermaid diagram showing the dependency chains from pipelines through intermediate templates to shared templates.
• Filtering — narrow results by project (--project-filter), by pipeline name (--pipeline-name-filter) or ID (--pipeline-id-filter) for the pipeline run subcommand, or by specific shared template paths (--template-filter, pipeline definition only).
• Flexible authentication — accepts an explicit --token option, the SYSTEM_ACCESSTOKEN / AZURE_DEVOPS_PAT environment variables, or falls back to DefaultAzureCredential (Azure CLI, managed identities, and more).

Prerequisites

• .NET SDK must be installed.

Installation

dotnet tool install --global PipelineGraph.Cli

Quick start

# Authenticate with Azure CLI first
az login

# Scan based on pipeline definitions across the entire organization
pipeline-graph pipeline definition --org https://dev.azure.com/MyOrg

# Scan based on actual pipeline runs across the entire organization
pipeline-graph pipeline run --org https://dev.azure.com/MyOrg

# Generate a dependency graph for a single repository
pipeline-graph repo-graph --org https://dev.azure.com/MyOrg --project MyProject --repo my-templates-repo

Usage

Cross-repo scanning (pipeline definition)

Analyzes pipeline definitions and provides insights on what shared templates are referenced, including nested/transitive templates across repositories.

pipeline-graph pipeline definition [options]

Options:
  --org <org> (REQUIRED)              Azure DevOps organization URL
  --template-repo <repo>              Repository that hosts the shared pipeline templates
  --template-project <project>        Project containing the shared template repository [default: CICD]
  --project-filter <projects>         Restrict scanning to specific project(s) (repeatable)
  --template-filter <templates>       Filter to specific shared template path(s) (repeatable)
  --output <path>                     Path for the JSON report [default: ./pipeline-definition-report.json]
  --graph-output <path>               Path for the Mermaid graph [default: ./pipeline-definition-graph.md]
  --parallelism <n>                   Max concurrent Azure DevOps API requests [default: 10]
  --token <token>                     Azure DevOps access token (overrides env vars and DefaultAzureCredential)
  --verbose                           Enable verbose logging

Run-based scanning (pipeline run)

Analyzes the most recent completed pipeline runs and reports the full Stage → Job → Step hierarchy with timing, results, worker names, and environment deployments. The output is hierarchical: project → pipeline → runs → stages → jobs → steps. Use --begin-date / --end-date to narrow runs to a specific date range. When no date range is specified, all completed runs are analyzed.

pipeline-graph pipeline run [options]

Options:
  --org <org> (REQUIRED)              Azure DevOps organization URL
  --project-filter <projects>         Restrict scanning to specific project(s) (repeatable)
  --pipeline-name-filter <names>      Restrict scanning to specific pipeline(s) by name (repeatable)
  --pipeline-id-filter <ids>          Restrict scanning to specific pipeline(s) by definition ID (repeatable)
  --output <path>                     Path for the JSON report [default: ./pipeline-run-report.json]
  --begin-date <date>                 Start of the date range for pipeline runs
  --end-date <date>                   End of the date range for pipeline runs
  --parallelism <n>                   Max concurrent Azure DevOps API requests [default: 10]
  --token <token>                     Azure DevOps access token (overrides env vars and DefaultAzureCredential)
  --verbose                           Enable verbose logging

Run compliancy report (pipeline run-compliancy)

Reads the JSON output of the pipeline run command and produces a Markdown table summarizing pipeline runs. Optionally checks whether specific tasks (by task ID) completed and succeeded in each run.

pipeline-graph pipeline run-compliancy [options]

Options:
  --input <path> (REQUIRED)           Path to the JSON report produced by 'pipeline run'
  --output <path>                     Path for the Markdown compliancy report [default: ./pipeline-compliancy-report.md]
  --check-task-id <id>                Task ID (GUID) to check in each run — repeat for multiple

The generated Markdown table contains:

• Pipeline — pipeline name with a link to the pipeline definition
• Run — run ID with a link to the pipeline run

For each --check-task-id, two extra columns are added:

• <task name> completed — ✅ if all matching steps completed, ❌ otherwise (linked to the step)
• <task name> succeeded — ✅ if all matching steps succeeded, ❌ otherwise (linked to the step)

Single-repo template graph

pipeline-graph repo-graph [options]

Options:
  --org <org> (REQUIRED)              Azure DevOps organization URL
  --project <project> (REQUIRED)      Azure DevOps project name containing the repository
  --repo <repo> (REQUIRED)            Name of the repository to scan
  --branch <branch>                   Branch to scan (defaults to the repository's default branch)
  --exclude-pipelines                 Detect and exclude YAML files that are pipeline definitions
  --mermaid-output <path>             Path for the Mermaid graph [default: ./repo-mermaid.md]
  --table-output <path>               Path for the Markdown table [default: ./repo-table.md]
  --parallelism <n>                   Max concurrent Azure DevOps API requests [default: 10]
  --token <token>                     Azure DevOps access token (overrides env vars and DefaultAzureCredential)
  --verbose                           Enable verbose logging

Authentication

The tool tries the following credential sources in order:

Running in Azure Pipelines

Use the pipeline's built-in System.AccessToken to authenticate. The Build Service identity must have read access to the projects/repos you want to scan (this is the default for repos in the same organization).

steps:
  - task: DotNetCoreCLI@2
    displayName: Install pipeline-graph
    inputs:
      command: custom
      custom: tool
      arguments: install --global PipelineGraph.Cli

  - script: pipeline-graph pipeline definition --org $(System.CollectionUri) --template-repo shared-templates
    displayName: Run pipeline-graph
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Note: System.AccessToken is not mapped into the environment by default — you must pass it explicitly via the env: block as shown above. Alternatively, use the --token option:

- script: pipeline-graph pipeline definition --org $(System.CollectionUri) --token $(System.AccessToken)

If the Build Service identity needs access to repos in other projects, grant the "<Project> Build Service (<org>)" account Reader permission on those projects.

Examples

Scan all projects in organization and generate a report filtered to all templates in a specific repo:

pipeline-graph pipeline definition \
  --org https://dev.azure.com/MyOrg \
  --template-project Templates \
  --template-repo shared-templates

Scan all projects in organization and generate a report filtered to a single template:

pipeline-graph pipeline definition \
  --org https://dev.azure.com/MyOrg \
  --template-project Templates \
  --template-repo shared-templates \
  --template-filter steps/build/dotnet.yml

Scan a specific project and generate a report filtered to a single template:

# Use --project-filter multiple times to scan several projects
# Use --template-filter multiple times to match several templates
pipeline-graph pipeline definition \
  --org https://dev.azure.com/MyOrg \
  --project-filter MyProject \
  --template-repo shared-templates \
  --template-filter steps/build/dotnet.yml

Analyze actual pipeline runs to see stages, jobs, and steps:

pipeline-graph pipeline run \
  --org https://dev.azure.com/MyOrg

Analyze pipeline runs for a specific project within a date range:

pipeline-graph pipeline run \
  --org https://dev.azure.com/MyOrg \
  --begin-date 2025-01-01 \
  --end-date 2025-01-31

Analyze runs for specific pipelines by name:

pipeline-graph pipeline run \
  --org https://dev.azure.com/MyOrg \
  --pipeline-name-filter "My Build Pipeline" \
  --pipeline-name-filter "My Deploy Pipeline"

Analyze runs for specific pipelines by definition ID:

pipeline-graph pipeline run \
  --org https://dev.azure.com/MyOrg \
  --pipeline-id-filter 42 \
  --pipeline-id-filter 187

Generate a dependency graph

pipeline-graph repo-graph \
  --org https://dev.azure.com/MyOrg \
  --project CICD \
  --repo shared-templates \
  --branch main

Generate a dependency graph of all relations between templates in a single repository, pipelines are excluded:

pipeline-graph repo-graph \
  --org https://dev.azure.com/MyOrg \
  --project CICD \
  --repo shared-templates \
  --exclude-pipelines

Generate a dependency graph with custom output paths:

pipeline-graph repo-graph \
  --org https://dev.azure.com/MyOrg \
  --project CICD \
  --repo shared-templates \
  --mermaid-output ./docs/graph.md \
  --table-output ./docs/table.md

Generate a check report from a pipeline run report:

pipeline-graph pipeline check \
  --input ./pipeline-run-report.json

Generate a check report verifying specific tasks completed and succeeded:

pipeline-graph pipeline check \
  --input ./pipeline-run-report.json \
  --check-task-id e213ff0f-5d5c-4791-802d-52ea3e7be1f1 \
  --check-task-id 5bfb729a-a7c8-4a78-a7c3-8d717bb7c13c \
  --output ./check-report.md