Connecting Azure DevOps

The Azure DevOps integration does the same job as the Jira one: it reads a copy of your board into Works, links plan items to work items, raises proposals when a work item reaches a done state, and sends a governed status or comment back. Read Connecting Jira first for what the integration does and does not do, field ownership, the pull schedule and the outbound governance. All of that applies to Azure DevOps too. This page covers only what is different.

Prerequisites

1. Licence. Tracker integration is included from the Enterprise edition, for both providers.
2. Permission. Setting up a connection needs the Admin role. Linking needs permission to edit Deliver, within reach of the item.
3. A personal access token (PAT). Works authenticates with a PAT only. Microsoft Entra ID sign-in for Azure DevOps is not supported, so an instance that needs it cannot connect today.
4. Your Azure DevOps details: the organisation URL, for example https://dev.azure.com/your-org, and the project name.
5. Encryption key. Same as Jira. The PAT is stored encrypted with the same key as a Jira token.
6. Network. The server must reach your Azure DevOps organisation over HTTPS.

The scopes the PAT needs are under What the PAT must be allowed to do.

What the PAT must be allowed to do

Works calls Azure DevOps REST API version 7.1 with the PAT (basic authentication, empty user name). Read from the client’s calls (adoClient.ts), against Microsoft’s own scope names:

Works does	Azure DevOps call	PAT scope
Test the connection; list the project’s teams	Read the project; list its teams	Project and team (read)
Read work item types and their states; pull work items	Work item types and states; a WIQL query; work items in batches	Work items (read)
Send a comment	Add a comment to a work item (preview API 7.1-preview.3)	Work items (read and write)
Move a state	Update the work item’s state	Work items (read and write)

A connection that only pulls needs the first two rows. Create the PAT for the single organisation, and set an expiry you can manage. Scope names are those on Microsoft’s “OAuth 2.0 authentication for Azure DevOps REST APIs” and PAT pages (vso.project, vso.work, vso.work_write).

Connect and set up boards

You need the Admin role.

1. Open the account menu, then Admin, then Integrations, then New connection.

2. On Connect, choose Azure DevOps and fill in:

   • Name, for example “Delivery Boards”.
   • Organisation URL.
   • Personal access token. It is stored encrypted and never shown again.
   • Project: the Azure DevOps project name.

   There is no account email field.

3. Select Test connection, then Continue.

4. On Boards, each team in the project is offered as a board. Tick the teams that should feed the programme.

5. On Scope, choose one set for the whole programme, or one per workstream. For a programme-wide set, choose what a workstream is: a Feature, or “Not a Feature: I will link by hand”.

6. On Statuses, give each state a meaning: Not started, In progress, Done, Blocked (stays In progress), or Not mapped. Azure DevOps has no board columns to list, so states are listed per work item type, and each is labelled with its item type. They are pre-filled from Azure DevOps’s own categories: Proposed is Not started; InProgress and Resolved are In progress; Completed is Done; Removed is Not mapped.

7. On Preview, check the changes. The preview counts the Features on the chosen boards. Saving links nothing.

8. Select Save.

What differs from Jira

	Jira Cloud	Azure DevOps
Credential	Account email and API token	Personal access token only
Where it lives	Site URL, for example https://your-domain.atlassian.net	Organisation URL, for example https://dev.azure.com/your-org
Project field	The project key	The project name
Linking identifier	An issue key, such as OTB-123	A bare number, such as 42. Work items have no project-prefixed key
Boards	Real boards, with columns	One per team, scoped by the team’s area paths
Statuses listed	Per board	Per work item type
Workstream is	An Epic	A Feature
Moving a status	A workflow transition to the first target status the issue currently offers	Sets the work item’s state, trying each target state in turn; only a refusal moves on to the next
Connection test	Reads the account’s own details	Reads the named project, because a bare PAT has no equivalent call
API version	Jira Cloud REST version 3 and the agile API	Pinned to 7.1. The comment call uses 7.1-preview.3

Differences in behaviour you may notice

• A work item’s assignee, title, state and changed date are shown as external, exactly like Jira’s.
• The pull reads work items through a query over the teams’ area paths, in batches of 200.
• The outbound allow-list, comment money check, ledger, pause and resume work the same way.
• The same failure names appear: unauthorized, forbidden, not_found, rate_limited, timeout, network_error, unexpected_status and unexpected_response_shape. A 10-second timeout and up to three attempts for reads apply.

Troubleshooting

• Test connection fails. Check the organisation URL, project name and PAT. The test reads the project, so the token must be allowed to read it. Use Replace credential to enter a new PAT, for example after it expires.
• No teams listed. The token cannot read the project’s teams. It needs the Project and team (read) scope.
• A state is refused on push. The work item’s process may not have that state. Works tries each target state you gave in turn. Add a state your process has under Status moves.
• Everything else is as for Jira. See its troubleshooting section.

What happens when a PAT expires: Azure DevOps rejects it and Works names the failure as unauthorized. Use Replace credential to enter a new one.