Octopus Deploy Documentation

Azure DevOps Work Item Tracking Integration

Last updated

Octopus 2019.7.6 introduced support to integrate Octopus with Azure DevOps work items. The integration includes the ability to:

  • Automatically add links to Azure DevOps work items from releases and deployments in Octopus.
  • Retrieve release notes from Azure DevOps work item comments for automatic release note generation.

How Azure DevOps Integration Works

Octopus Azure DevOps integration - how it works diagram

  1. Associate code changes with their relevant work items in any of the following ways:
    • Edit a pull request in Azure DevOps, and use the Work Items panel to select a work item.
    • Edit a work item in Azure DevOps, and use the Development panel to add a pull request link (before build), or a commit link, or a build link.
    • When you commit code. If you enable the repository setting: Automatically create links for work items mentioned in a commit comment under Project Settings (Repositories), you can include # followed by a valid work item ID in the commit message. For example, git commit -a -m "Fixing bug #42 in the web client".
  2. The Octopus Deploy plugin for your build server pushes the commits to Octopus. These are associated with a package ID and version (The package can be in the built-in Octopus repository or an external repository).
  3. The Azure DevOps Issue Tracker extension in Octopus uses the build information to request work item references from Azure DevOps.

Octopus release with Azure DevOps work items

  1. When creating the release which contains the package version, the work items are associated with the release. These are available for use in release notes, and will be visible on deployments.

Octopus deployment with generated release notes


The ability to push the build information to Octopus, which is required for Azure DevOps integration, is currently only available in the official Octopus plugins:

Configuring Azure DevOps Integration

The following steps explain how to integrate Octopus with Azure DevOps:

  1. Configure your build server to push build information to Octopus. This is required to allow Octopus to know which work items are associated with a release.
  2. Configure the Azure DevOps connection in Octopus Deploy.

Configure your Build Server to Push Build Information to Octopus

To integrate with Azure DevOps work items, Octopus needs to understand which work items are associated with a release. Octopus does this by using the build information associated with any packages contained in the release to request work item references from Azure DevOps.

To supply the build information:

  1. Install one of our official build server plugins with support for our build information step.
  2. Update your build process to add and configure the Octopus Build Information step.

If you had previously been using the older functionality on the Create Octopus Release step, you should disable all of the release note options on that step as they use different mechanics and will conflict with the new features.

Legacy create release settings

Connect Octopus to Azure DevOps

  1. Configure the Azure DevOps Issue Tracker extension in Octopus Deploy.

    In the Octopus web portal, navigate to Configuration ➜ Settings ➜ Azure Devops Issue Tracker and set the following values:

    • Azure DevOps Base URL. This tells Octopus where the Azure DevOps instance is located.

    • Unless the Azure DevOps instance is public, you'll need to supply a Personal Access Token (PAT), created in the Azure DevOps User Settings (under Personal access tokens), with authorization to read scopes Build and Work items.

    • Ensure the Is Enabled property is set as well.

  2. Configure the Release Note Options (optional).

    • Release Note Prefix: If specified, Octopus will look for a work item comment that starts with the given prefix text and use whatever text appears after the prefix as the release note, which will be available in the build information as the work item's description. If no comment is found with the prefix then Octopus will default back to using the title for that work item.

    For example, a prefix of Release note: can be used to identify a customer friendly work item title vs a technical feature or bug fix title.

When configured, this integration will retrieve Azure DevOps work item details and add details to your releases and deployments. If you ever need to disable the Azure DevOps Issue Tracker extension you can do so under Configuration ➜ Settings ➜ Azure Devops Issue Tracker.


Welcome! We use cookies and data about how you use our website allow us to improve the website and your experience, and resolve technical errors. Our website uses cookies and shares some of your data with third party analytics companies for these purposes.

If you decline, we will respect your privacy. A single cookie will be used in your browser to remember your preference.