pipeline-debug

name	pipeline-debug
description	Debug and understand Azure DevOps pipeline configurations. Use when a pipeline fails, when setting up CI/CD for a new repo, or when tracing variable resolution across templates.

Pipeline Debug

Helps debug, understand, and configure Azure DevOps pipelines across CPP repositories by tracing template references, variable resolution, and pipeline structure.

When to Use

• User asks "why did my pipeline fail", "debug this pipeline", "trace this variable"
• User wants to set up CI/CD for a new repo
• User needs to understand how shared templates work
• User wants to find which template defines a specific step or variable

Process

Step 1: Identify the Pipeline

Read the repo's azure-pipelines.yml (or azure-pipelines.yaml). This is the entry point.

Step 2: Trace Template References

CPP pipelines use shared templates from cpp-azure-devops-templates. Template references look like:

resources:
  repositories:
    - repository: cppAzureDevOpsTemplates
      type: github
      name: hmcts/cpp-azure-devops-templates
      ref: refs/heads/main

stages:
  - template: pipelines/context-verify.yaml@cppAzureDevOpsTemplates

For each template reference:

1. Read the template file from cpp-azure-devops-templates/
2. Map the parameters passed from the calling pipeline to the template's parameter definitions
3. Recursively follow any nested template references (stages → steps → tasks)

Step 3: Trace Variable Resolution

Variables are resolved in this order (later overrides earlier):

1. Pipeline-level variables — defined in azure-pipelines.yml
2. Variable groups — referenced by name, stored in Azure DevOps
3. Template parameters — passed explicitly to templates
4. Runtime expressions — ${{ variables.xxx }}, $[ variables.xxx ]
5. Macro syntax — $(variableName) resolved at runtime

Step 4: Identify Common Pipeline Types

Repo Type	PR Template	Merge Template	Key Steps
Context services	context-verify.yaml	context-validation.yaml	Maven build, SonarQube, JaCoCo
UI apps	ui-verify.yaml	ui-validation.yaml	npm install, lint, test, build
Terraform modules	terratest.yaml	—	terraform init, validate, plan, test
Docker images	image-publish.yaml	—	Docker build, ACR push
Helm charts	Custom in cpp-helm-chart	—	Helm lint, package, ACR push

Step 5: Common Failure Patterns

Symptom	Likely Cause	Where to Look
settings.xml not found	Secure file download failed	Check DownloadSecureFile task and file name
SonarQube analysis failed	Wrong project key or missing token	Check sonarQubeProjectKey parameter
mvn: command not found	Wrong agent pool or missing tool	Check pool and task: Maven@4 config
npm ERR! 403	.npmrc not configured for private registry	Check secure file .npmrc download
docker push failed	ACR login failed or wrong registry	Check containerRegistry service connection
terraform plan failed	Backend config mismatch or missing vars	Check backend-config parameters
Helm lint failed	Chart.yaml version mismatch or missing deps	Check helm dependency update step

Step 6: Generate Debugging Report

## Pipeline Analysis: [repo-name]

### Pipeline Type
[context-verify / ui-verify / custom]

### Template Chain
1. azure-pipelines.yml
   └─ pipelines/context-verify.yaml@cppAzureDevOpsTemplates
      ├─ stages/build.yaml
      │   └─ steps/maven-build.yaml
      └─ stages/quality.yaml
          └─ steps/sonarqube-scan.yaml

### Variables Resolved
| Variable | Value | Source |
|----------|-------|--------|
| sonarQubeProjectKey | uk.gov.moj.cpp... | pipeline parameter |
| mavenGoals | clean verify | template default |

### Issues Found
- [description of any problems]

### Recommended Fix
- [specific fix with file and line references]

Key Files in cpp-azure-devops-templates

cpp-azure-devops-templates/
├── pipelines/
│   ├── context-verify.yaml         # Context service PR validation
│   ├── context-validation.yaml     # Context service merge build
│   ├── ui-verify.yaml              # UI app PR validation
│   ├── ui-validation.yaml          # UI app merge build
│   ├── terratest.yaml              # Terraform module testing
│   └── image-publish.yaml          # Docker image publishing
├── stages/                         # Reusable stage definitions
├── steps/                          # Reusable step definitions
└── variables/                      # Shared variable files

Deployment Pipelines

For deployment-related issues, also check:

• cpp-aks-deploy/aks-deploy.yaml — main AKS deployment pipeline
• cpp-aks-deploy/helmsman.toml — Helmsman deployment configuration
• cpp-aks-deploy/helmsman_vars/*.env — environment-specific variables
• Approval gates: non-live auto-resumes on timeout; live requires CPP DevOps SC approval