How to run an Azure Pipeline from an Azure Boards work item

Azure Boards does not have a "run pipeline" button. A work item can show the branches, pull requests, builds, and deployments connected to it, but there is no native action that starts an Azure Pipeline from the ticket.

Teams still want one, usually for the same reason: a ticket is ready for QA, staging, or UAT, and someone needs to deploy its branch. This guide compares the practical options, from fully manual to a deploy button on the work item, and when each one fits.

Quick comparison

Option 1: queue the pipeline manually

1. Open the work item and note the linked branch or pull request in the Development section.
2. Open Azure Pipelines and select the deployment pipeline.
3. Click Run pipeline.
4. Change the branch from the default to the work item's branch. For a PR, use its source branch.
5. Under Variables, set any values the pipeline expects, such as the work item ID.
6. Click Run.

This is the baseline every team has. It needs no setup, but it depends on someone copying the branch correctly every time, and the run has no connection to the ticket unless you pass the work item ID yourself.

Option 2: the Azure DevOps CLI or REST API

If you already know the branch, you can queue the run from a terminal or script. With the Azure DevOps CLI:

az pipelines run \
  --org https://dev.azure.com/YOUR_ORG \
  --project "YOUR_PROJECT" \
  --id 42 \
  --branch feature/1482-invoice-export \
  --variables workItemId=1482

Or with the Pipelines REST API, which is what most custom tools and chat bots call:

POST https://dev.azure.com/YOUR_ORG/YOUR_PROJECT/_apis/pipelines/42/runs?api-version=7.1
Content-Type: application/json

{
  "resources": {
    "repositories": {
      "self": { "refName": "refs/heads/feature/1482-invoice-export" }
    }
  },
  "variables": {
    "workItemId": { "value": "1482" }
  }
}

Both set the run's source branch and pass workItemId as a queue-time variable. The variable must be marked as settable at queue time in the pipeline, or the run is rejected. See queue-time variables and parameters.

The catch is the branch name. The CLI and API need it as input, so a script that starts from a work item must also read the work item's relations, find the branch or PR link, and resolve a PR to its source branch. That is a small tool to build and maintain.

Option 3: a service hook that triggers a pipeline

Azure DevOps service hooks can call a URL when a work item is created or updated, for example when its State changes to Ready for QA. Azure Pipelines can receive that call through an Incoming WebHook service connection and a webhook resource in YAML:

resources:
  webhooks:
    - webhook: WorkItemReady          # name used in the service hook URL
      connection: BoardsWebhook       # an "Incoming WebHook" service connection

trigger: none

steps:
  - script: echo "Work item ${{ parameters.WorkItemReady.resource.workItemId }} changed"

Then add a service hook subscription with the Web Hooks consumer on the Work item updated event, filtered to the field change you care about, pointing at the webhook URL for WorkItemReady.

This is fully automatic, but it has limits for deployments:

• Webhook-triggered runs start on the pipeline's default branch, not the work item's branch. To deploy the feature branch, the pipeline has to look up the linked branch and check it out itself.
• There is no confirmation step. Moving a card on the board deploys, including by accident.
• The webhook payload describes the work item change. Mapping it to a branch, environment, and permission check is up to your pipeline scripts.

Service hooks are a good fit for notifications, status sync, and jobs that should always run on a state change. They are a poor fit for "deploy this ticket's branch now, on request."

Option 4: a deploy button on the work item with BranchDeploy

BranchDeploy is an Azure DevOps Marketplace extension that adds a BranchDeploy action to the work item toolbar. It covers the gap the other options leave: it starts from the ticket, uses the branch the ticket is linked to, and asks before it runs.

1. A project admin enters the pipeline ID, environment name, and allowed branch patterns once in Project Settings → BranchDeploy.
2. Anyone with queue permission opens a work item and clicks BranchDeploy.
3. BranchDeploy reads the Development links and resolves the branch. A linked pull request resolves to its source branch.
4. A confirmation step shows the work item, repository, branch, and environment.
5. On confirm, the pipeline is queued with that branch as its source, plus optional environment and workItemId variables, and the run link appears straight away.

Runs are queued as the signed-in user, so existing pipeline permissions, approvals, and checks still apply. For a full setup walkthrough, see deploy an Azure Repos branch from an Azure Boards work item.

Which option should you use?

• A few deploys a month, all by developers: manual runs are fine.
• You are building your own tooling or bot: use the REST API, and resolve the linked branch from work item relations.
• Something should always happen when a ticket changes state: use a service hook, ideally for notifications or non-branch jobs.
• QA, testers, or delivery managers deploy tickets to test environments: use a deploy button so nobody copies branch names.

Frequently asked questions

Can Azure Boards trigger a pipeline when a work item changes state?

Yes, indirectly. A service hook on Work item updated can call an Azure Pipelines incoming webhook. The run starts on the pipeline's default branch, so it is not a direct way to deploy the ticket's feature branch.

How do I pass the work item ID to the pipeline?

Define a variable such as workItemId that can be set at queue time, then set it when you run the pipeline: in the Run pipeline dialog, with --variables on the CLI, or in the variables object of the REST API. BranchDeploy can set it for you.

Does the work item show the pipeline run afterwards?

Azure Boards can show builds and deployments linked to a work item through its Development and Deployment sections, depending on your pipeline and project settings. BranchDeploy also shows the run link as soon as the run is queued.

Does BranchDeploy work with classic build pipelines?

Yes. It queues a build pipeline by ID, which covers YAML pipelines and classic build pipelines. Classic Release pipelines are not supported.