> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Azure DevOps as an alert source

> Turn Azure DevOps work items into pages and incidents in incident.io.

Teams often raise production problems as Azure DevOps work items, for example a Bug filed by your support team. Connect Azure DevOps to incident.io to page the right people when that happens.

Azure DevOps sends work item events to incident.io through service hooks, which you create in each project you want alerts from. Each work item becomes one alert, which takes its title and description from the work item and links back to it. A snapshot of the work item's fields lands in the alert payload's `work_item` field, so you can use them to power [alert attributes](https://docs.incident.io/alerts/attributes-and-priorities.md) and routing.

> [!NOTE]
>
> The Azure DevOps alert source is rolling out gradually. If you don't see it when you create a source, contact [support@incident.io](mailto:support@incident.io).

## Instructions

Before you start, [connect the Azure DevOps integration](https://docs.incident.io/integrations/azure-devops.md#connecting-azure-devops). To copy the service hook password from incident.io, you need permission to manage organization settings.

1. Head over to the [Alerts](https://app.incident.io/~/on-call/alert-routes/sources) section in your incident.io dashboard.

2. Select the **Sources** tab at the top of the page.

3. Press the **Create source** button.

4. Search for **Azure DevOps** and click **Continue** to create the alert source.

5. Select the Azure DevOps projects that should send work items to this source. Projects come from your catalog, so a newly connected integration can take a few minutes to list them.

6. In Azure DevOps, open one of those projects, go to **Project settings → Service hooks**, and click **Create subscription**.

7. Select **Web Hooks**, then click **Next**.

8. Set the trigger to **Work item created**. Add filters if you only want some work items to alert, for example by work item type or area path. Click **Next**.

9. Paste the **URL**, **Basic authentication username**, and **Basic authentication password** from the incident.io setup page, then click **Test** and **Finish**.

10. Repeat steps 6 to 9 with the **Work item updated** trigger, then repeat both service hooks for every project you selected.

11. Create or update a work item in one of the selected projects. If it's set up correctly, the alert appears in incident.io.

If nothing arrives, check the service hook's delivery history under **Project settings → Service hooks** in Azure DevOps, and check the Azure DevOps integration is still connected under [Settings → Integrations](https://app.incident.io/~/settings/integrations).

> [!TIP]
>
> If you already sync incident tickets to Azure DevOps, your projects have a **Work item updated** service hook pointing at incident.io. That hook feeds this alert source too, so you only need to add **Work item created**.

Each incident.io organization can have one Azure DevOps alert source. Add every project to it, then use alert routes to send work items from different projects to different teams.

## What each work item event does

| Azure DevOps event | What incident.io does |
| - | - |
| Work item created | Opens an alert for the work item |
| Work item updated | Updates the work item's alert, and resolves it once the work item is closed |
| Work item commented on | Accepted, and no alert is opened or updated |

Alerts are deduplicated on the work item ID, so you're paged once per work item however often it changes. A work item counts as closed once Azure DevOps records it as completed, resolved, or closed, depending on your project's process template.

> [!WARNING]
>
> You can't resolve these alerts from incident.io. Close the work item in Azure DevOps and the alert resolves with it.

Resolving the alert doesn't resolve an incident on its own. For triage incidents, turn on **Decline triage incidents if the linked alerts are resolved** on the alert route. For live incidents, trigger a [workflow](https://docs.incident.io/workflows/getting-started.md) on alert resolution.

## Route alerts by team

The recommended approach is to tag each work item with an identifier for its team. Tags arrive as one semicolon-separated string at `work_item.tags`, so split it on `;` into a Team [alert attribute](https://docs.incident.io/alerts/attributes-and-priorities.md). Azure DevOps tags can't contain commas or semicolons.

Alternatively, give each team its own area path and file work items under it. Add the full area path, for example `Shop\Payments`, as an alias on the team's catalog entry, then read `work_item.area_path` into the Team attribute. See [routing alerts to teams](https://docs.incident.io/alerts/team-routing.md) for what to do with the attribute once it's set.

The `work_item` field also carries the work item's type, state, priority, severity, iteration path, and creator. Custom fields are there too, with dots in their names replaced by underscores, so `Custom.OwningTeam` becomes `work_item.Custom_OwningTeam`. Empty fields are left out, and values longer than 4 KB are cut short.

## Reuse the work item as the incident ticket

If you [sync incident tickets to Azure DevOps](https://docs.incident.io/integrations/azure-devops.md#incident-tickets), incident.io avoids creating a duplicate work item for incidents created from this source.

When an alert from this source creates an incident, and the incident ticket template for that incident uses the same project and work item type as the alert's work item, the original work item becomes the incident's ticket. Otherwise, incident.io creates a new ticket as usual.

Once alerts are arriving, [create an alert route](https://docs.incident.io/alerts/getting-started.md) to filter, group, and escalate them, or to automatically create incidents.