Skip to content

configure-pipelines-work-tracking.md

Latest commit

 

History

History
411 lines (283 loc) · 22.2 KB

configure-pipelines-work-tracking.md

File metadata and controls

411 lines (283 loc) · 22.2 KB
title Configure pipelines to support integration
titleSuffix Azure DevOps
description Learn how to configure pipelines to support integration with Azure Boards and work tracking
ms.subservice azure-devops-pipelines-integrations
ms.topic how-to
ms.author jukullam
monikerRange <= azure-devops
ms.date 01/07/2026
ms.custom cross-service, sfi-image-nochange

Configure pipelines to support work tracking

[!INCLUDE version-lt-eq-azure-devops]

To support integration and traceability across Azure DevOps Services with pipelines, you can configure several options. You can report pipeline status, copy the syntax for status badges, and set up automatic linking of work items to builds and releases.

Supported pipeline and work tracking integration features

Several features provide support for end-to-end traceability as user stories and features move through the development cycle. As with Azure Repos, you can link work items to pipeline objects with the following link types: Build, Integrated in build, and Integrated in release. You can create the Integrated in release environment link by enabling the Report release status to Boards option in Classic release pipelines.

:::image type="content" source="media/pipelines-integration/concept-link-types-pipelines.png" alt-text="Screenshot of conceptual diagram showing link types that connect work items to Azure Pipelines objects.":::

The following table summarizes the integration points between Azure Boards and Azure Pipelines. Options and configuration steps differ depending on whether you're configuring a YAML or Classic pipeline, and your Azure DevOps version. Most options are supported for pipelines run against an Azure Repos Git repository unless otherwise noted.

:::row::: :::column span="2"::: Feature :::column-end::: :::column span="2"::: Description :::column-end::: :::column span="1"::: Supported versions :::column-end::: :::row-end:::

:::row::: :::column span="2"::: Manually link work items to builds
:::column-end::: :::column span="2"::: You can link from a work item to builds within the same project or other projects within the organization. For more information, see Link to work items from other objects. :::column-end::: :::column span="1"::: All versions :::column-end::: :::row-end:::

:::row::: :::column span="2"::: View builds linked to from a work item :::column-end::: :::column span="2"::: You can view all builds linked to from a work item, whether manual or automatically linked, from the Links tab. For more information, see Link to work items from other objects, View list of linked objects. :::column-end::: :::column span="1"::: All versions :::column-end::: :::row-end:::

:::row::: :::column span="2"::: Automatically link work items to builds
:::column-end::: :::column span="2"::: Required to populate the Development control with Integrated in build links. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Azure Pipelines is associated with a set of work items and commits. For more information, see Automatically link work items later in this article. :::column-end::: :::column span="1"::: YAML, Azure DevOps Server 2020 and later :::column-end::: :::row-end:::

::: moniker range="<=azure-devops" :::row::: :::column span="2"::: Automatically link work items to releases and report deployment status to a work item (Classic only) :::column-end::: :::column span="2"::: You need this task to populate the Deployment control in the work item form with Integrated in release stage links. For more information, see Report deployment status to Boards later in this article. :::column-end::: :::column span="1"::: Azure DevOps Server 2020 and later
:::column-end::: :::row-end:::

::: moniker-end :::row::: :::column span="2"::: View list of work items linked to a build or release :::column-end::: :::column span="2"::: Review and open the work items included in a build or release.
:::column-end::: :::column span="1"::: YAML, Azure DevOps Server 2020 and later :::column-end::: :::row-end:::

:::row::: :::column span="2"::: Create work item on failure (Classic) :::column-end::: :::column span="2"::: Automatically create a work item when a build fails, and optionally set values for work item fields. For more information, see Create work item on failure later in this article.
:::column-end::: :::column span="1"::: All versions :::column-end::: :::row-end:::

::: moniker range="<=azure-devops" :::row::: :::column span="2"::: Query Work Items task, ensure the number of matching work items returned from a query is within a threshold. :::column-end::: :::column span="2"::: Use this task to ensure the number of matching items returned by a work item query is within the configured thresholds. For more information, see Query Work Items task, Control deployments with gates and approvals.
:::column-end::: :::column span="1"::: Azure DevOps Server 2020 and later versions :::column-end::: :::row-end:::

::: moniker-end

Prerequisites

  • To configure the integration options for a Classic release pipeline, you must have permissions to edit the release.
  • To link work items to commits and pull requests, you must set your Edit work items in this node permission to Allow for the Area Path assigned to the work item. By default, the Contributors group has this permission set.
  • To view work items, you must set your View work items in this node permission to Allow for the Area Path assigned to the work item.

Open pipeline settings, build options, or integration options

YAML

Open Pipeline settings

::: moniker range="<=azure-devops"

For YAML-defined release pipelines, you configure the integration through the Pipeline settings dialog.

  • Open the pipeline, choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: More actions, and then choose Settings.

    :::image type="content" source="media/pipelines-integration/open-pipeline-settings.png" alt-text="Screenshot of YAML pipeline with More actions menu open showing the Settings option.":::

    The Pipeline Settings dialog appears. For more information on automatic linking, see Automatically link work items.

    :::image type="content" source="media/pipelines-integration/pipeline-settings-enable-link-work-items.png" alt-text="Screenshot of YAML Pipeline settings dialog with Automatically link new work items in this build option.":::

::: moniker-end

Classic Release

Release integration options

For Classic release pipelines, open Pipelines > Releases, select your pipeline to edit it, and then choose Options. Select Integrations.

::: moniker range="<=azure-devops" :::image type="content" source="media/pipelines-integration/integration-options-classic.png" alt-text="Screenshot of Integrations options for Classic pipelines showing deployment status configuration settings.":::

For more information on each setting, see:

::: moniker range="<=azure-devops"

Automatically link work items to builds or releases

By enabling automatic linking, you can track the builds or releases that incorporated work without having to manually search through a large set of builds or releases. Every successful build associated with the work item automatically appears in the Development control of the work item form. Each release stage associated with the work item automatically appears in the Deployment control of the work item form.

::: moniker-end

YAML

::: moniker range="<=azure-devops"

  1. Open Pipeline settings as described in Open Pipeline settings.

  2. Enable Automatically link new work in this build.

    :::image type="content" source="media/pipelines-integration/pipeline-settings-enable-link-work-items.png" alt-text="Screenshot of Pipeline settings dialog, Automatically link work items in this build.":::

    Once enabled, Integrated in build links are generated for all work items linked to the selected pull request with each release run. ::: moniker-end

Classic Release

::: moniker range="<=azure-devops"

Before you choose integration options, set up the release stages as described in Define your multi-stage continuous deployment (CD) pipeline.

  1. Open Options>Integrations for the release pipeline as describe in Release integration options.

  2. Check the Report deployment status to Boards checkbox. Map the Deployment type to each stage, or leave Unmapped. Select this option if you want to create links to all work items that represent associated changes to the source, when a release is complete. This option must be enabled in order for the work item form Deployment control to work.

    :::image type="content" source="media/pipelines-integration/release-settings-stages-1.png" alt-text="Screenshot of Report deployment status to Boards option in Classic release with five stages selected.":::

    To view a list of work items linked to the release, choose Release (old view) from :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: More commands, and then choose the Work Items tab.

    :::image type="content" source="media/pipelines-integration/release-pipeline-view-work-items.png" alt-text="Screenshot of release pipeline Work Items tab displaying work items linked to the release.":::

  3. Save your pipeline.

Verify the integration

To verify the integration is working, perform the following steps:

  1. Link one or more work items to a commit or pull request in Azure Repos Git repository. For more information, see:

  2. Run the pipeline.

  3. Open one of the linked work items and view the Deployment control. As shown in the following image, the Deployment control shows release information for two release stages for work items that linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards.

:::image type="content" source="../../boards/work-items/media/deployments-control/deployment-control-intro.png" alt-text="Screenshot of Work item form showing the Deployment control with deployment stage information.":::

::: moniker-end

What work items are included in automatic linking?

When developing your software, you can link work items when you create a branch, commit, or pull request. Or, you can initiate a branch, commit, or pull request from a work item, automatically linking these objects as described in Drive Git development from a work item. For example, here we create a new branch from the Cancel order form user story.

:::image type="content" source="media/pipelines-integration/create-branch-link-work-item.png" alt-text="Screenshot of Create branch dialog showing work item link options.":::

When you automatically link work items to builds, the following computations are made:

  • For a first-time build:

    • Identify all work items linked to the branch, commits, and pull requests associated with the build.

  • For subsequent builds:

    • Identify all work items associated with the current commit (C1) being built.
    • Identify all work items associated with the commit (C2) of the last successful build of the same source branch.
    • Identify all work items associated with the commits between C1 and C2 in the commit tree.

Create work item on build failure (Classic)

If a build pipeline fails, you can automatically create a work item to track getting the problem fixed. You can specify the work item type and set options to automatically assign it to the requestor or other fields. The requestor corresponds to the person that triggered the build.

Tip

The option to Create work item on failure is only supported for Classic pipelines. To accomplish this with a YAML pipeline, you can use a marketplace extension like Create Bug on Release failure or you can implement it yourself using Azure CLI or REST API calls.

  1. Open pipeline build options as described in Build properties.

  2. Enable Create work item on failure and choose the type of work item to create. Optionally check the Assign to requestor checkbox to set the Assign To field and add fields to set within the work item to create.

    For example, here we choose the Bug work item type and specify the Priority and Tags fields and their values.

    :::image type="content" source="media/pipelines-integration/create-work-item-failure-yaml.png" alt-text="Screenshot of Create work item on failure option in build options with Bug work item type selected.":::

  3. Save your pipeline.

To learn the reference name for a field, look it up from the Work item field index. For custom fields you add through an inherited process, Azure DevOps assigns a reference name based on friendly field name prefixed with Custom. For example, you add a field named DevOps Triage. The reference name is Custom.DevOpsTriage. No spaces are allowed within the reference name.

Get or enable a status badge

YAML

  1. Open pipeline :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: More Actions and choose Status badge.

    :::image type="content" source="media/pipelines-integration/yaml-pipeline-more-actions-menu-options.png" alt-text="Screenshot of YAML pipeline More Actions menu with Status badge option.":::

  2. Choose the branch and scope of interest, and then choose :::image type="icon" source="../../media/icons/copy.png" border="false"::: Copy to clipboard to copy the image or Markdown syntax.

    :::image type="content" source="media/pipelines-integration/status-badge-yaml.png" alt-text="Screenshot of YAML pipeline status badge dialog showing branch and scope selection options.":::

Classic Release

Select this option if you want to display the latest outcome of a stage deployment on an external website.

  1. Check the Enable the deployment status badge checkbox. And then, select the stages for which you want to display the outcome. By default, all the stages defined for the release are selected.

    :::image type="content" source="media/pipelines-integration/enable-status-badge-3-stages.png" alt-text="Screenshot of Enable the deployment status badge option with three stages selected.":::

  2. Choose :::image type="icon" source="../../media/icons/copy.png" border="false"::: Copy to clipboard to copy the image or Markdown syntax.

    :::image type="content" source="media/pipelines-integration/classic-release-status-badge-3-stages.png" alt-text="Screenshot of Classic release status badge dialog showing three stages with copyable badge markup.":::

  3. Save your pipeline.

::: moniker range="<=azure-devops"

Report deployment status to the repository host (Classic)

When your code is stored in an Azure Repos Git repository, you can configure your release pipeline to display a badge on the Azure Repos pages. The badge indicates where the specific commit got deployed and whether the deployment is passing or failing. This option improves the traceability from code commit to deployment.

:::image type="content" source="media/pipelines-integration/classic-report-deployment-status.png" alt-text="Screenshot of Integrations options for Classic pipelines showing Report deployment status to the repository host settings.":::

Azure Repos displays the deployment status in the following sections:

  • Files: Indicates the status of the latest deployment for the selected branch.
  • Commits: Indicates the deployment status for each commit (requires the continuous integration (CD) trigger to be enabled for your release).
  • Branches: Indicates the status of the latest deployment for each branch.

If you deploy a commit to multiple release pipelines with multiple stages, each stage appears in the badge with its status. By default, when you create a release pipeline, it posts deployment status for all stages. However, you can selectively choose the stages for which deployment status should be displayed in the status badge (for example, show only the production stage). Your team members can select the status badge to view the latest deployment status for each of the selected stages of the release pipelines.

::: moniker-end

::: moniker range="<=azure-devops"

Report deployment status to Jira (Classic)

Include Jira issues in work items and create links to all issues on stage completion. Install Azure Pipelines for Jira app in Jira Software cloud and add organization to create a connection.

:::image type="content" source="media/pipelines-integration/integration-options-classic-jira.png" alt-text="Screenshot of Integrations options for Classic pipelines showing Report deployment status to Jira settings.":::

To support integration with Jira issue tracking, install Azure DevOps for Jira and connect your Azure DevOps organizations with your Jira Software instance. You can connect multiple organizations with one instance and get data for all your teams and related projects. For more information, see Connect Azure DevOps to Jira.

::: moniker-end

Related articles