Wednesday, November 18, 2026

Azure DevOps: Dry Run a Pipeline with the Preview REST API

In this post, let's have a look at the Azure DevOps Pipelines Preview REST API, and how we can use it to validate a YAML pipeline without actually running it.

The only way to know what a YAML pipeline really turns into is usually to queue it. The Preview API does a dry run instead: Azure DevOps compiles the YAML exactly as it would for a real run, and gives us back the final YAML. Nothing is queued, so nothing shows up under the pipeline's runs.

The pipeline

Let's take a simple pipeline with one parameter.
trigger: none

parameters:
  - name: environment
    type: string
    default: dev
    values:
      - dev
      - qa

pool:
  vmImage: ubuntu-latest

steps:
  - script: echo Deploying to ${{ parameters.environment }}
    displayName: Deploy

Calling the Preview API

It's a POST against the pipeline, with previewRun set to true (api-version 7.1, latest as of today, it will change).
POST https://dev.azure.com/{organization}/{project}/_apis/pipelines/{pipelineId}/preview?api-version=7.1
Let's call it from PowerShell. For the token, I am using the Azure CLI. 499b84ac-1321-427f-aa17-267ca6975798 is the resource ID of Azure DevOps, and it is the same for every organization. And we are passing a value for the environment parameter through templateParameters, the same way we would when queuing a run.
$azureDevOpsResourceId = "499b84ac-1321-427f-aa17-267ca6975798"
$organization = "<Organization>"
$project = "<Project>"
$pipelineId = "<PipelineId>"

$token = az account get-access-token `
    --resource $azureDevOpsResourceId `
    --query accessToken `
    --output tsv

$uri = "https://dev.azure.com/$organization/$project/_apis/pipelines/$pipelineId/preview?api-version=7.1"

$body = @{
    previewRun = $true
    templateParameters = @{
        environment = "qa"
    }
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{ Authorization = "Bearer $token" } `
    -ContentType "application/json" `
    -Body $body

$response.finalYaml
The response has a single property, finalYaml.
trigger:
  enabled: false
parameters:
- name: environment
  type: string
  default: dev
  values:
  - dev
  - qa
stages:
- stage: __default
  jobs:
  - job: Job
    pool:
      vmImage: ubuntu-latest
    steps:
    - task: CmdLine@2
      displayName: Deploy
      inputs:
        script: echo Deploying to qa

The expression is resolved to qa, and we can see what Azure DevOps does behind the scenes: the steps are wrapped in a default stage and job, the pool is moved down to the job, and script becomes the CmdLine@2 task.

If we pass a value that isn't allowed, say prod, the call fails with the same error a real run would give us.
{
  "message": "The 'environment' parameter value 'prod' is not a valid value.",
  "typeKey": "PipelineValidationException"
  // Omitted for brevity
}

After all of these calls, the pipeline still has no runs.

There are two more properties worth knowing. yamlOverride lets us send YAML that isn't committed yet and preview that instead. And resources.repositories.self.refName (for example refs/heads/feature/my-change) previews another branch, which is handy for diffing the finalYaml of a branch against main before merging.

Keep in mind this only covers what's known at compile time. It won't tell you whether a service connection is authorized, an agent is available, or a runtime variable resolves.

More read:

Hope this helps.

Happy Coding.

Regards,
Jaliya

No comments:

Post a Comment