# Azure DevOps

> Sync work items between Orangescrum and Azure Boards without creating two conflicting sources of truth.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/cloud/integrations/azure-devops

---
> **Pro and Premium**
>
> The Azure DevOps integration requires Pro Unlimited or above.

Connects Orangescrum projects to Azure Boards so work items stay aligned across
both — typically where engineering lives in Azure DevOps while planning,
resourcing and client reporting happen in Orangescrum.

## Decide the ownership model first

This is the decision that determines whether the integration helps or creates
constant confusion.

> **Two systems that can both edit the same field will disagree**
>
> Not "might" — will. Decide which system owns which field **before** connecting,
> write it down, and configure the sync to match.

A model that works in practice:

| Field | Owned by | Why |
| --- | --- | --- |
| Title, description | Either, synced | Rarely contested |
| **Status** | Azure DevOps | Engineers update it where they work |
| **Assignee** | Azure DevOps | Same reason |
| **Priority, dates** | Orangescrum | Planning happens here |
| **Estimates** | Orangescrum | Feeds velocity and budget |

## Connecting

**Open project settings → Integrations**

    Configured per project.

**Authorise Azure DevOps**

    Use a service account, not an individual's. A connection tied to a person
    breaks when they leave.

**Select the organisation and project**

    Map one Orangescrum project to one Azure Boards project.

**Map work item types**

    Azure's User Story, Bug and Task map to your Orangescrum types. Get this
    right — a bad mapping is tedious to unpick once items exist.

**Map statuses**

    Azure states to your
    [custom statuses](https://helpdesk.orangescrum.com/guide/cloud/tasks/custom-fields-and-statuses). Any state
    without a mapping will not sync.

**Set the sync direction per field**

    Following the ownership model you agreed.

## Test before trusting

**Start with one small project**

    Never a live one with hundreds of items.

**Create an item on each side**

    Confirm it appears in the other, with the fields you expect.

**Edit the same item on both sides**

    Deliberately create a conflict and see what happens. This is the behaviour
    you most need to understand.

**Then roll out**

    One project at a time.

## Keeping it healthy

- **Don't rename statuses casually**: A rename on either side breaks the mapping silently. Update both.

- **Watch the sync log**: Failures are usually quiet. Check it rather than waiting for someone to notice a stale item.

- **Agree where to comment**: Comments in two places means half the conversation is invisible to half the team. Pick one.

- **Review quarterly**: Mappings drift as both tools evolve.

## Troubleshooting

**Items stopped syncing**

    Check the credential first — Azure tokens expire. Then check whether a
    status or work item type was renamed.

**Some items sync, others don't**

    Almost always an unmapped work item type or status. Items in an unmapped
    state are skipped.

**Fields keep reverting**

    Both sides own the field and are overwriting each other. Fix the sync
    direction — this is the ownership model problem.

**Duplicates appeared**

    Usually a reconnection that did not recognise existing links. Stop the sync
    before cleaning up, or you will be deleting duplicates faster than they are
    recreated.

## Is it worth it?

- **Yes**: Engineering genuinely lives in Azure Boards, and planning or client reporting genuinely lives in Orangescrum. Both are used daily.

- **Probably not**: One tool is barely used. Syncing two systems where one is abandoned adds complexity and no benefit — consolidate instead.

- [All integrations](https://helpdesk.orangescrum.com/guide/cloud/integrations/overview): What else you can connect.