Pipelines and Build API Reference

Pipelines and Build API Reference

Comprehensive reference for Azure DevOps Pipelines REST API operations.

Table of Contents

• Pipeline Concepts
• Build Status and Results
• YAML Pipeline Reference
• Pipeline Variables
• Triggers and Resources

Pipeline Concepts

Pipeline Types

Pipeline Hierarchy

Pipeline Definition
    └── Stages
        └── Jobs
            └── Steps (Tasks/Scripts)

Run vs Build

• Pipeline Run: Modern YAML pipeline execution (Pipelines API)
• Build: Classic build or YAML execution (Build API)

Build Status and Results

Build Status Values

Build Result Values

Build Reason Values

YAML Pipeline Reference

Basic Structure

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
      - release/*
    exclude:
      - feature/experimental/*
  paths:
    include:
      - src/*
    exclude:
      - docs/*

pr:
  branches:
    include:
      - main
  autoCancel: true

pool:
  vmImage: 'ubuntu-latest'

variables:
  - name: buildConfiguration
    value: 'Release'
  - group: 'production-secrets'

stages:
  - stage: Build
    displayName: 'Build Stage'
    jobs:
      - job: BuildJob
        displayName: 'Build Application'
        steps:
          - task: DotNetCoreCLI@2
            displayName: 'Build'
            inputs:
              command: 'build'
              projects: '**/*.csproj'

Stage Template

stages:
  - stage: stageName
    displayName: 'Stage Display Name'
    dependsOn: [previousStage]
    condition: succeeded()
    variables:
      stageVar: 'value'
    jobs:
      - job: jobName
        # Job definition

Job Template

jobs:
  - job: JobName
    displayName: 'Job Display Name'
    pool:
      vmImage: 'ubuntu-latest'
    timeoutInMinutes: 60
    cancelTimeoutInMinutes: 5
    dependsOn: [PreviousJob]
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    continueOnError: false
    strategy:
      matrix:
        linux:
          imageName: 'ubuntu-latest'
        windows:
          imageName: 'windows-latest'
      maxParallel: 2
    steps:
      - script: echo Hello

Deployment Job

jobs:
  - deployment: DeploymentName
    displayName: 'Deploy to Production'
    environment: 'production'
    strategy:
      runOnce:
        deploy:
          steps:
            - download: current
              artifact: drop
            - script: ./deploy.sh

Pipeline Variables

Predefined Variables

Variable Syntax

# Macro syntax (compile-time)
variables:
  myVar: 'value'
steps:
  - script: echo $(myVar)

# Template expression (compile-time)
steps:
  - script: echo ${{ variables.myVar }}

# Runtime expression
steps:
  - script: echo $[variables.myVar]

# Environment variable (Bash)
steps:
  - script: echo $MYVAR
    env:
      MYVAR: $(myVar)

# PowerShell
steps:
  - powershell: Write-Host $env:MYVAR
    env:
      MYVAR: $(myVar)

Variable Groups

variables:
  - group: 'my-variable-group'
  - name: localVar
    value: 'local value'

Secret Variables

variables:
  - name: mySecret
    value: $(secretFromLibrary)  # From variable group

steps:
  - script: |
      echo "Using secret (masked in logs)"
      curl -H "Authorization: Bearer $(mySecret)" https://api.example.com
    env:
      MY_SECRET: $(mySecret)

Triggers and Resources

CI Triggers

# Branch triggers
trigger:
  batch: true  # Batch changes
  branches:
    include:
      - main
      - release/*
    exclude:
      - feature/experimental/*
  paths:
    include:
      - src/*
    exclude:
      - '**/*.md'
  tags:
    include:
      - v*
    exclude:
      - v0.*

# Disable CI trigger
trigger: none

PR Triggers

pr:
  autoCancel: true
  drafts: false
  branches:
    include:
      - main
      - release/*
  paths:
    include:
      - src/*
    exclude:
      - docs/*

Scheduled Triggers

schedules:
  - cron: '0 0 * * *'  # Daily at midnight UTC
    displayName: 'Daily Build'
    branches:
      include:
        - main
    always: false  # Only if changes
  - cron: '0 12 * * 0'  # Weekly Sunday noon
    displayName: 'Weekly Build'
    branches:
      include:
        - main
    always: true  # Always run

Pipeline Resources

resources:
  repositories:
    - repository: templates
      type: git
      name: ProjectName/TemplateRepo
      ref: refs/heads/main
    - repository: external
      type: github
      name: org/repo
      endpoint: 'GitHub Connection'

  pipelines:
    - pipeline: upstream
      source: 'Upstream-Pipeline'
      trigger:
        branches:
          include:
            - main

  containers:
    - container: build-container
      image: mcr.microsoft.com/dotnet/sdk:6.0
      options: --privileged

  packages:
    - package: myPackage
      type: npm
      connection: 'npm-connection'
      name: '@scope/package'
      version: 1.0.0

MCP Tool Usage Examples

List Build Definitions

# Using mcp__ado__pipelines_get_build_definitions
params = {
    "project": "MyProject",
    "includeLatestBuilds": True,
    "queryOrder": "LastModifiedDescending",
    "top": 50
}

Get Builds

# Using mcp__ado__pipelines_get_builds
params = {
    "project": "MyProject",
    "definitions": [123, 456],  # Definition IDs
    "statusFilter": 2,  # Completed
    "resultFilter": 8,  # Failed
    "queryOrder": "FinishTimeDescending",
    "top": 20
}

Run Pipeline

# Using mcp__ado__pipelines_run_pipeline
params = {
    "project": "MyProject",
    "pipelineId": 123,
    "resources": {
        "repositories": {
            "self": {
                "refName": "refs/heads/feature-branch"
            }
        }
    },
    "templateParameters": {
        "environment": "staging",
        "runTests": "true"
    },
    "variables": {
        "customVar": {
            "value": "custom-value",
            "isSecret": False
        }
    },
    "stagesToSkip": ["Deploy-Production"]
}

Get Build Logs

# Using mcp__ado__pipelines_get_build_log
params = {
    "project": "MyProject",
    "buildId": 12345
}

# Get specific log
# Using mcp__ado__pipelines_get_build_log_by_id
params = {
    "project": "MyProject",
    "buildId": 12345,
    "logId": 5,
    "startLine": 100,
    "endLine": 200
}

Retry Failed Stage

# Using mcp__ado__pipelines_update_build_stage
params = {
    "project": "MyProject",
    "buildId": 12345,
    "stageName": "Deploy",
    "status": "Retry",
    "forceRetryAllJobs": True
}

Get Pipeline Run

# Using mcp__ado__pipelines_get_run
params = {
    "project": "MyProject",
    "pipelineId": 123,
    "runId": 456
}

Common Pipeline Tasks

Checkout

steps:
  - checkout: self
    clean: true
    fetchDepth: 0
    lfs: true
    submodules: recursive
    persistCredentials: true

Download Artifacts

steps:
  - download: current
    artifact: 'drop'
    patterns: '**/*.dll'

  - task: DownloadPipelineArtifact@2
    inputs:
      buildType: 'specific'
      project: 'ProjectGuid'
      definition: '123'
      buildVersionToDownload: 'latest'
      artifactName: 'drop'
      targetPath: '$(Pipeline.Workspace)/artifacts'

Publish Artifacts

steps:
  - task: PublishPipelineArtifact@1
    inputs:
      targetPath: '$(Build.ArtifactStagingDirectory)'
      artifact: 'drop'
      publishLocation: 'pipeline'

Cache

steps:
  - task: Cache@2
    inputs:
      key: 'npm | "$(Agent.OS)" | package-lock.json'
      restoreKeys: |
        npm | "$(Agent.OS)"
      path: $(npm_config_cache)
    displayName: 'Cache npm packages'