> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/project-management/azure-devops.md).

# Azure DevOps

Create and link Azure DevOps work items from tickets, and keep each ticket up to date as engineering moves the work

Azure DevOps is Microsoft's platform for planning and tracking engineering work. Connecting Azure DevOps to Harmony lets agents hand a ticket to engineering without leaving Harmony: create a work item from the ticket, or link one that already exists. Harmony then follows each linked work item. When engineering finishes the work, the ticket says so, and it can resolve itself once every linked work item is done.

{% hint style="info" %}
Harmony supports Azure DevOps Services (`dev.azure.com`). Azure DevOps Server (on-premises) is not supported.
{% endhint %}

### What the Azure DevOps integration enables

| Capability               | Description                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create Work Items        | Create a work item from a ticket in an allowed project, prefilled with the ticket's title, description and attachments                            |
| Link Existing Work Items | Search by ID or title and link a work item that already exists. One ticket can link several work items, and several tickets can link the same one |
| Live State               | Each linked work item shows its current Azure DevOps state on the ticket                                                                          |
| Internal Notes           | The ticket gets an internal note whenever a linked work item changes state, is removed, or is restored                                            |
| Auto-Resolve             | Once every linked work item is done, the ticket resolves and the requester gets the usual resolution message                                      |
| Link Back to Harmony     | Each work item carries a hyperlink to the Harmony ticket and names the requester                                                                  |
| Per-Desk Control         | Choose which desks can use Azure DevOps. It is off for every desk until you add it                                                                |

### Prerequisites

* **Azure DevOps Services Organization**: With the projects your engineering teams work in
* **Microsoft Work Account**: A member of that organization. Harmony acts as this account for everything it does in Azure DevOps, so it needs permission to:
  * View, create, and edit work items in the projects you allow
  * Edit service hook subscriptions on those projects. Project Administrators have this by default
* **Harmony Account**: Active Harmony workspace with admin access

### Connect Azure DevOps to Harmony

#### Step 1: Navigate to Integrations

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Azure DevOps** under **Project Management** and click its card

#### Step 2: Sign in with Microsoft

1. Click **Connect**. You will be redirected to Microsoft to sign in
2. Sign in with the work account Harmony should act as, and accept the requested permissions

{% hint style="info" %}
Work items Harmony creates or updates are attributed to the account that connected. Choose an account your engineering teams will recognize, such as a shared service account.
{% endhint %}

#### Step 3: Choose the Organization, Projects, and Desks

Once connected, the Azure DevOps card shows these settings:

| Setting              | Description                                                                                                                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Organization**     | The Azure DevOps organization Harmony works in. The list shows the organizations the connecting account is a member of. Once saved, it cannot be changed: linked work items are IDs in this organization. To use another organization, disconnect and connect again |
| **Allowed projects** | Agents can only create, search, and link work items in these projects                                                                                                                                                                                               |
| **Desks**            | Click **Add desk** and choose each desk that can use Azure DevOps. Agents on a listed desk can create and link work items, and the desk's tickets resolve when their work items are done                                                                            |

Click **Save Changes**. Harmony registers service hooks on each allowed project, so work item changes reach Harmony as they happen. There is nothing to set up in Azure DevOps by hand.

{% hint style="warning" %}
If saving shows **Settings saved, but Harmony couldn't register the Azure DevOps service hooks**, your settings were saved but the connecting account cannot edit service hook subscriptions on the selected projects. Tickets still update, but only every 15 minutes instead of within moments. Grant the permission in Azure DevOps (for example, by making the account a Project Administrator), then save again.
{% endhint %}

### Create a Work Item from a Ticket

1. Open the ticket and click **More actions** (**⋯**) > **Create Azure DevOps work item**
2. Choose the **Project** and the **Work item type**. Types that are hidden or disabled in Azure DevOps are not listed
3. Review the **Title** and **Description**. They start as the ticket's title and description
4. Fill in the fields that the work item type requires. Defaults set in your Azure DevOps process are filled in for you. Optional fields are not shown; set them in Azure DevOps afterward
5. Click **Create work item**

The new work item gets:

* **Title and description** as entered. The description starts with the requester's name and email and a link to the Harmony ticket. On a **Bug**, this goes into **Repro Steps**; on other types, into **Description**
* **A hyperlink** to the Harmony ticket on the work item's **Links** tab
* **The ticket's attachments**, up to 25 MB each. If a file can't be added, Harmony names it in a warning and creates the work item without it
* **Area and Iteration**: not set by Harmony, so Azure DevOps places the work item at the project's root area and iteration

The ticket lists the work item under **Linked tickets**, and an internal note records it. You can create one work item per ticket. After that, the menu item no longer appears, but you can still link more work items.

{% hint style="info" %}
Required fields of these types can be filled in from Harmony: text, number, date and time, yes/no, picklists, and people (entered as an email address). If a work item type requires a field of any other type and the field has no default, Harmony cannot create that type and lists the fields that block it. Give those fields a default value in your Azure DevOps process, or contact Harmony Support to set a fixed value for them.
{% endhint %}

### Link an Existing Work Item

1. Open the ticket. On the **Linked tickets** card, click **Link** > **Link Azure DevOps work item**
2. Search by work item ID or by words from its title. Harmony searches the allowed projects and shows up to 25 matches, most recently changed first. Work items already linked to the ticket are shown but can't be picked
3. Choose the work item and click **Link**

Harmony adds a hyperlink to the ticket on the work item, and an internal note records the link. Work items that have been removed cannot be linked.

To unlink a work item, click the unlink icon next to it on the **Linked tickets** card. Harmony also removes the ticket's hyperlink from the work item, and an internal note records the change.

### How Work Item Changes Reach the Ticket

Harmony reads each work item's **state category** rather than its state name, so the Agile, Scrum, Basic, and CMMI processes, and custom processes built on them, all work the same way:

| Azure DevOps state category            | Harmony treats the work item as                                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Proposed, In Progress                  | Active                                                                                                           |
| Resolved, Completed                    | Done. A state named **Resolved** also counts as done, even in the In Progress category (as on the Agile process) |
| Removed, or deleted to the recycle bin | Removed, shown as **Removed in ADO**                                                                             |

When a linked work item changes, the ticket shows its new state, and Harmony writes an internal note naming the work item and its new state. Some changes also move the ticket:

| Change                        | What happens to the ticket                                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Done**                      | When every linked work item is done (removed ones don't count), the ticket is resolved and the requester gets the usual resolution message |
| **Reopened** (done to active) | A ticket Harmony resolved moves back to **In Progress**. A ticket an agent resolved stays resolved                                         |
| **Removed or deleted**        | The ticket moves to **In Progress** so an agent can decide what happens next. A ticket an agent resolved stays resolved                    |
| **Restored**                  | The work item shows its current state again                                                                                                |
| **Any other state change**    | Only the note and the new state                                                                                                            |

Harmony never changes a closed or canceled ticket, and never resolves a ticket that is pending approval.

Changes arrive within moments through the service hooks Harmony registers. A check every 15 minutes picks up anything a service hook missed.

### What Harmony Syncs

**To Azure DevOps:**

* New work items: title, description with the requester and a link to the ticket, the required fields, and the ticket's attachments
* A hyperlink to the Harmony ticket on every work item you create or link, removed again when you unlink
* Service hook subscriptions on the allowed projects, for state changes, deletions, and restores

**From Azure DevOps:**

* The state, title, and type of each linked work item
* Your organizations, projects, work item types, and their fields, for the pickers in Harmony

Nothing else syncs. Harmony never changes a work item's state, and comments do not sync in either direction.

### Use Cases

<details>

<summary>Escalate a Bug to Engineering</summary>

A user reports that an internal app crashes on login. The agent creates a Bug from the ticket. The requester's details, the reproduction steps, and the screenshots all reach engineering in Repro Steps and attachments. When engineering closes the bug, the ticket resolves and the requester is told.

</details>

<details>

<summary>Many Tickets, One Work Item</summary>

Twelve people report the same outage. Agents link every ticket to the one work item engineering is tracking. When that work item is done, all twelve tickets resolve together.

</details>

<details>

<summary>One Ticket, Several Work Items</summary>

A request needs work from two teams, each tracking it in its own project. The agent links both work items. The ticket resolves only after both are done.

</details>

<details>

<summary>Work That Was Dropped</summary>

Engineering removes a work item as a duplicate. The ticket gets a note and moves back to In Progress, so the agent can link the surviving work item or follow up with the requester.

</details>

### Troubleshooting

**"Create Azure DevOps work item" is not in More actions** - check that the ticket's desk is listed under **Desks** in the integration settings, and that you can edit the ticket. A ticket that already has a work item created from it no longer offers the action; link more work items from the **Linked tickets** card instead. Newly saved settings can take a few minutes to reach open tickets; reload the page to pick them up sooner.

**"Couldn't load organizations from Azure DevOps", or no organizations are listed** - the connecting account must be a member of at least one Azure DevOps Services organization. Add the account to the organization, then reopen the integration card.

**"No Azure DevOps projects are allowed yet"** - no projects have been chosen yet. An admin needs to select them under **Allowed projects**.

**"Cannot create this work item"** - the work item type requires a field Harmony can't fill in. Give the listed fields a default value in your Azure DevOps process, choose a different work item type, or contact Harmony Support.

**"Settings saved, but Harmony couldn't register the Azure DevOps service hooks"** - the connecting account needs permission to edit service hook subscriptions on the allowed projects. Grant it, then save the settings again.

**A work item doesn't appear in search** - search covers only the allowed projects and matches the work item ID or words in its title. Deleted work items don't appear, and removed ones can't be linked.

**"Some attachments weren't added to the work item"** - files over 25 MB, or files Azure DevOps refused, are left out. Attach them to the work item in Azure DevOps directly.

**The ticket didn't update when a work item changed** - if the service hooks aren't registered, changes arrive with the next 15-minute check. Save the integration settings to register them again, and check the warning above if saving reports a problem.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/project-management/azure-devops.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
