Skip to content

Latest commit

 

History

History
530 lines (343 loc) · 23.9 KB

configure-pipelines-work-tracking.md

File metadata and controls

530 lines (343 loc) · 23.9 KB
title titleSuffix description ms.technology ms.topic ms.author author monikerRange ms.date
Configure pipelines to support integration
Azure DevOps
Learn how to configure pipelines to support integration with Azure Boards and work tracking
devops-agile
how-to
kaelli
KathrynEE
>= tfs-2018
08/13/2021

Configure pipelines to support work tracking

[!INCLUDE temp]

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.

:::image type="content" source="media/pipelines-integration/concept-link-types-pipelines.png" alt-text="Conceptual image of link types that link 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 are 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 details, 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 details, 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 details, see Automatically link work items later in this article. :::column-end::: :::column span="1"::: YAML, Azure DevOps Server 2020 and later
Classic, TFS 2018 and later :::column-end::: :::row-end:::

::: moniker range=">= azure-devops-2020" :::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"::: Required to populate Deployment control in work item form with Integrated in release stage links. For details, 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 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"::: 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 details, see Create work item on failure later in this article.
:::column-end::: :::column span="1"::: TFS 2018 and later versions :::column-end::: :::row-end:::

::: moniker range=">= azure-devops-2020" :::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 details, 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

Open pipeline settings, build options, or integration options

YAML

Open Pipeline settings

::: moniker range=">= azure-devops-2020"

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

  1. 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="Open Pipeline settings.":::

    The Pipeline Settings dialog appears. For details on automatic linking, see Automatically link work items later in this article.

    :::image type="content" source="media/pipelines-integration/pipeline-settings-enable-link-work-items.png" alt-text="YAML Pipeline settings dialog.":::

::: moniker-end ::: moniker range="< azure-devops-2020" This setting isn't available for Azure DevOps Server 2019 or earlier versions. ::: moniker-end

Classic Build

Build properties

Open the build pipeline, choose to edit the pipeline, and then choose the Options tab.

::: moniker range=">= azure-devops-2019" :::image type="content" source="media/pipelines-integration/open-classic-build-properties-options.png" alt-text="Screenshot of Classic Build pipeline, Options tab."::: ::: moniker-end ::: moniker range="tfs-2018" :::image type="content" source="media/pipelines-integration/open-classic-build-properties-options-tfs-2018.png" alt-text="Build and Release pipeline Build properties dialog, TFS-2018."::: ::: moniker-end

The Build properties page appears.

::: moniker range=">= azure-devops-2019" :::image type="content" source="media/pipelines-integration/classic-build-options.png" alt-text="Build properties dialog.":::

For details on each setting, use one of the following links:

::: moniker-end

::: moniker range="tfs-2018" :::image type="content" source="media/pipelines-integration/build-properties-tfs-2018.png" alt-text="Build properties dialog, TFS-2018.":::

For details on each setting, use one of the following links:

::: moniker-end

Classic Release

Release integration options

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

::: moniker range=">= azure-devops-2020"

[!div class="mx-imgBorder"] Screenshot of Integrations options for Classic pipelines

For details on each setting, use one of the following links:

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

[!div class="mx-imgBorder"] Screenshot of Integrations options for Classic pipelines, Azure DevOps 2019 and earlier versions

For details on each setting, use one of the following links:

Automatically link work items to builds

YAML

::: moniker range=">= azure-devops-2020"

  1. Open Pipeline settings as describe 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

::: moniker range="< azure-devops-2020" This feature isn't supported for YAML pipelines in Azure DevOps Server 2019. ::: moniker-end

Classic Build

  1. Open pipeline Build properties as describe in Build properties.

  2. Enable Automatically link work items included in this run. Add the branches to include or exclude.
    :::image type="content" source="media/pipelines-integration/auto-link-work-items-classic-build-pipeline.png" alt-text="Screenshot of Automatically link work items in this build property settings.":::

    Once enabled, Integrated in build are generated for all work items linked to the selected branches in each run.

    To view a list of work items linked to the build, choose the Related link on the Summary page.

    :::image type="content" source="media/pipelines-integration/build-view-work-items.png" alt-text="Screenshot of link to view work items linked to build.":::

Classic Release

::: moniker range=">= azure-devops-2019"

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

  1. Open Options>Integrations as describe in Release integration options.

  2. Check the Report deployment status to Work checkbox. Map the Deployment type to each stage, or leave Unmapped.

    :::image type="content" source="media/pipelines-integration/report-deployment-status-boards-4-environments.png" alt-text="Screenshot of Report deployment status to Boards, Classic, 4 environments.":::

    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 link to view work items linked to a release.":::

::: moniker-end

::: moniker range="TFS-2018" Refer to the Classic Build procedures. ::: moniker-end

When we establish traceability between work items and builds/releases, there are the following two aspects:

  • List the work items that were newly built as part of a build. You can find this when you're looking at a build instance.
  • List the builds that this work item was built in. You can find the list in the "Development" section in a work item form. The setting to "Automatically link new work in this build" has nothing to do with how we compute the first bulleted item. It only influences how we compute the second bulleted item.

The computation for the first bullet is as follows for a build: Let's say, for example, that you started a new build. Whatever the setting, we compute a list of new commits for the build. We do the following tasks:

  • We find the commit c2 that is being built now.
  • We find the commit c1 that was built in the last successful build of the same branch (Build.SourceBranch).
  • We find all the commits between c1 and c2 (in the commit tree).

It could happen that there's no last known successful build on the same branch. For example, when you run a build for the first time on a branch, or when all the previous builds on a branch have been deleted (possibly through retention policies). The list could be long in these cases.

Once we have the list of commits, we enumerate all the work items associated with each of those commits. This is the list that you see in a build.

::: moniker range=">= azure-devops-2020"

Report deployment status to Boards (Classic)

Prior to choosing your integration options, you should 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 checkboxc. 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.

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

::: moniker-end

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, see the Create Bug on Release failure marketplace extension.

  1. Open pipeline build options as describe 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 in build options.":::

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 options.":::

  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.":::

Classic Build

  1. Open pipeline Build properties as describe in Build properties.

  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-build-status-badge.png" alt-text="Screenshot of classic build properties, status badge section.":::

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 Classic release enable deployment status badge 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 enable deployment status badge with three stages that you can copy.":::

  3. Save your pipeline.

::: moniker range=">= azure-devops-2019"

Report deployment status to the repository host (Classic)

When you 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.

[!div class="mx-imgBorder"] Screenshot of Integrations options for Classic pipelines, report deployment status to the repository host

The deployment status is displayed in the following sections of Azure Repos:

  • 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 a commit gets deployed to multiple release pipelines, with multiple stages, each has an entry in the badge with status that's shown for each stage. By default, when you create a release pipeline, deployment status is posted 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-2020"

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, Report deployment status to Jira":::

To support integration with Jira issue tracking, install Azure Pipelines integration with 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. Learn more about setting up the integration in our documentation.To learn more about installation and setup, see Integrate with Jira Issue tracking.

::: moniker-end

Related articles