Azure DevOps Cheat Sheet

# The CLI ships as an extension to the Azure CLI
az extension add --name azure-devops
az extension update --name azure-devops
 
# Sign in interactively (uses your az login context)
az login
 
# Or authenticate the DevOps extension with a PAT (legacy / CI without OIDC)
export AZURE_DEVOPS_EXT_PAT="<pat>"
echo "$AZURE_DEVOPS_EXT_PAT" | az devops login --organization https://dev.azure.com/myorg

az devops configure --defaults \
  organization=https://dev.azure.com/myorg \
  project=myproject
 
az devops configure --list           # show current defaults

az devops project list --output table
az repos list --output table
az pipelines list --output table
az pipelines runs list --top 10 --output table
az boards work-item show --id 1234 --output json
 
# Open the current repo's project in the browser
az repos show --repository myrepo --open

# Queue a run on a branch, optionally passing parameters/variables
az pipelines run --name "ci-build" --branch main \
  --parameters environment=dev \
  --variables imageTag=1.2.3
 
az pipelines runs show --id 98765
az pipelines runs artifact list --run-id 98765

trigger:
  branches:
    include: [ main ]
 
pool:
  vmImage: ubuntu-latest   # Microsoft-hosted agent
 
stages:
  - stage: build
    jobs:
      - job: compile
        steps:
          - task: UseDotNet@2
            inputs:
              packageType: sdk
              version: 8.0.x
          - script: dotnet build --configuration Release
            displayName: Build

steps:
  - script: echo "runs in the default shell (cmd on Windows, bash on Linux)"
  - bash: |
      set -euo pipefail
      echo "always bash; fail fast"
  - pwsh: |
      $ErrorActionPreference = 'Stop'
      Write-Host "always PowerShell 7"
  - task: Bash@3            # the task form gives retry, condition, env, etc.
    inputs:
      targetType: inline
      script: ./scripts/test.sh
    retryCountOnTaskFailure: 2

jobs:
  - job: build
    steps: [ { script: make build } ]
 
  - job: test
    dependsOn: build                       # ordering + implicit success gate
    condition: succeeded()
    steps: [ { script: make test } ]
 
  - job: notify
    dependsOn: [ build, test ]
    condition: always()                    # run even if upstream failed
    steps: [ { script: ./notify.sh } ]

jobs:
  - job: test
    strategy:
      matrix:
        linux:   { imageName: ubuntu-latest }
        windows: { imageName: windows-latest }
        mac:     { imageName: macos-latest }
      maxParallel: 3
    pool:
      vmImage: $(imageName)
    steps:
      - script: ./run-tests.sh

# CI trigger with path and branch filters
trigger:
  batch: true                 # queue one run for accumulated pushes
  branches:
    include: [ main, release/* ]
    exclude: [ docs/* ]
  paths:
    include: [ src/** ]
    exclude: [ "**/*.md" ]
 
# PR trigger (YAML PR triggers work for GitHub repos; for Azure Repos,
# configure PR validation via branch policies instead - see Permissions)
pr:
  branches:
    include: [ main ]
 
# Scheduled trigger (cron is UTC)
schedules:
  - cron: "0 2 * * *"
    displayName: Nightly build
    branches: { include: [ main ] }
    always: false             # only run if the source changed since last run
 
# Trigger off another pipeline completing
resources:
  pipelines:
    - pipeline: upstream
      source: upstream-ci
      trigger:
        branches: { include: [ main ] }

parameters:                    # typed, set at queue time, expanded at compile time
  - name: environment
    type: string
    default: dev
    values: [ dev, test, prod ]
 
variables:                     # macro variables, expanded at runtime as $(name)
  buildConfiguration: Release
  isMain: $[ eq(variables['Build.SourceBranch'], 'refs/heads/main') ]
 
steps:
  - script: echo "Deploying to ${{ parameters.environment }} as $(buildConfiguration)"

variables:
  - group: shared-nonprod          # links a variable group (Library)
  - name: localOnly
    value: foo
 
# Pull secrets straight from Key Vault via a service connection
steps:
  - task: AzureKeyVault@2
    inputs:
      azureSubscription: 'sc-prod-oidc'
      KeyVaultName: 'kv-prod-uks'
      SecretsFilter: 'db-password,api-key'

  - bash: ./deploy.sh
    env:
      DB_PASSWORD: $(db-password)   # explicit mapping; do not interpolate $(secret) into a script body

# templates/build-steps.yml
parameters:
  - name: configuration
    type: string
    default: Release
steps:
  - script: dotnet build -c ${{ parameters.configuration }}
    displayName: Build (${{ parameters.configuration }})

# azure-pipelines.yml
steps:
  - template: templates/build-steps.yml
    parameters:
      configuration: Release

# pipeline in an app repo
extends:
  template: pipeline.yml@templates      # from a repository resource
  parameters:
    image: myapp
 
resources:
  repositories:
    - repository: templates
      type: git
      name: platform/pipeline-templates
      ref: refs/tags/v3.1.0             # pin templates to a tag, not a moving branch

# Create a WIF (OIDC) Azure RM service connection via CLI/REST is limited;
# the portal flow is: Project Settings → Service connections → New →
# Azure Resource Manager → Workload Identity federation (automatic).
# Then grant the federated identity RBAC on the target scope:
az role assignment create \
  --assignee "<app-or-uami-client-id>" \
  --role "Contributor" \
  --scope "/subscriptions/<sub-id>/resourceGroups/rg-prod"

steps:
  - task: AzureCLI@2
    inputs:
      azureSubscription: 'sc-prod-oidc'   # the WIF service connection
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: az group list -o table

# Microsoft-hosted: clean VM per job, no maintenance, 1 hr (public) / 60 hr job limits
pool:
  vmImage: ubuntu-latest
 
# Self-hosted: your infra, persistent tooling, private network access
pool:
  name: 'linux-selfhosted'
  demands:
    - agent.os -equals Linux
    - docker                       # custom capability you registered

# On the agent host (Linux), after downloading the agent package:
./config.sh --unattended \
  --url https://dev.azure.com/myorg \
  --auth pat --token "$AZP_TOKEN" \
  --pool 'linux-selfhosted' \
  --agent "$(hostname)" \
  --acceptTeeEula
sudo ./svc.sh install && sudo ./svc.sh start

resources:
  containers:
    - container: build
      image: mcr.microsoft.com/dotnet/sdk:8.0
    - container: redis             # a service container
      image: redis:7
 
jobs:
  - job: test
    pool: { vmImage: ubuntu-latest }
    container: build               # steps execute inside this image
    services:
      redis: redis                 # reachable on the docker network by name
    steps:
      - script: dotnet test
        env:
          REDIS_HOST: redis

stages:
  - stage: deploy_prod
    jobs:
      - deployment: web
        environment: production          # creates/uses an Environment resource
        strategy:
          runOnce:                       # also: rolling, canary
            deploy:
              steps:
                - script: ./deploy.sh

Project Settings → Repositories → <repo> → Policies → Branch (main):
  ✅ Require a minimum number of reviewers (>=2, reset votes on new push)
  ✅ Check for linked work items
  ✅ Build Validation  → your CI pipeline (this is how PR CI runs on Azure Repos)
  ✅ Require resolution of all comments
  ✅ Limit merge types (squash) + restrict who can bypass policies

steps:
  - script: |
      curl -s -H "Authorization: Bearer $(System.AccessToken)" \
        "$(System.CollectionUri)_apis/build/builds?api-version=7.1"
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)   # not exposed unless mapped

steps:
  # Pipeline artifacts (fast, for build outputs between stages/runs)
  - publish: $(System.DefaultWorkingDirectory)/dist
    artifact: webapp
 
  - download: current
    artifact: webapp
 
  # Dependency cache (keyed on a lockfile hash)
  - task: Cache@2
    inputs:
      key: 'npm | "$(Agent.OS)" | package-lock.json'
      path: $(npm_config_cache)

stages:
  - stage: plan
    jobs:
      - job: tf_plan
        pool: { vmImage: ubuntu-latest }
        steps:
          - task: AzureCLI@2
            inputs:
              azureSubscription: 'sc-prod-oidc'   # WIF service connection
              scriptType: bash
              scriptLocation: inlineScript
              addSpnToEnvironment: true            # exposes idToken / servicePrincipalId / tenantId
              inlineScript: |
                set -euo pipefail
                export ARM_USE_OIDC=true
                export ARM_OIDC_TOKEN="$idToken"
                export ARM_CLIENT_ID="$servicePrincipalId"
                export ARM_TENANT_ID="$tenantId"
                export ARM_SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
                terraform init
                terraform plan -out=tfplan
          - publish: tfplan
            artifact: tfplan
 
  - stage: apply
    dependsOn: plan
    jobs:
      - deployment: tf_apply
        environment: production                    # approval check gates the apply
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: tfplan
                - task: AzureCLI@2
                  inputs:
                    azureSubscription: 'sc-prod-oidc'
                    scriptType: bash
                    scriptLocation: inlineScript
                    addSpnToEnvironment: true
                    inlineScript: |
                      set -euo pipefail
                      export ARM_USE_OIDC=true ARM_OIDC_TOKEN="$idToken"
                      export ARM_CLIENT_ID="$servicePrincipalId" ARM_TENANT_ID="$tenantId"
                      export ARM_SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
                      terraform init
                      terraform apply -auto-approve tfplan

terraform {
  required_providers {
    azuredevops = {
      source  = "microsoft/azuredevops"
      version = "~> 1.0"
    }
  }
}
 
# Auth via env: AZDO_ORG_SERVICE_URL + AZDO_PERSONAL_ACCESS_TOKEN
# (or use the provider's Azure AD / WIF options instead of a PAT).
provider "azuredevops" {}
 
resource "azuredevops_project" "this" {
  name               = "myproject"
  visibility         = "private"
  version_control    = "Git"
  work_item_template = "Agile"
}
 
resource "azuredevops_git_repository" "app" {
  project_id = azuredevops_project.this.id
  name       = "app"
  initialization { init_type = "Clean" }
}
 
# YAML pipeline backed by azure-pipelines.yml in the repo
resource "azuredevops_build_definition" "ci" {
  project_id = azuredevops_project.this.id
  name       = "app-ci"
  repository {
    repo_type   = "TfsGit"
    repo_id     = azuredevops_git_repository.app.id
    branch_name = "refs/heads/main"
    yml_path    = "azure-pipelines.yml"
  }
}
 
# Variable group with a masked secret
resource "azuredevops_variable_group" "shared" {
  project_id   = azuredevops_project.this.id
  name         = "shared-nonprod"
  allow_access = true
  variable {
    name  = "region"
    value = "uksouth"
  }
  variable {
    name         = "apiKey"
    secret_value = var.api_key
    is_secret    = true
  }
}