Azure DevOps

Plenty of teams run their delivery on Azure DevOps and are not about to move off it, nor should they have to. The Azure DevOps integration is built for that team: it links your Disco Parrot initiatives, plans, and test cases to ADO work items so the planning you do here and the boards your team already lives on stay in step. A product manager refines the spec in Disco Parrot; an engineer picks up the work on the ADO board; both are looking at one piece of work from two seats.

This page is the how-to: connecting your account, mapping how your concepts line up with ADO work-item types, and reading the link from the Disco Parrot side. For where this fits among the other ways Disco Parrot connects to your stack, read integrations and providers; that page draws the line between a work-item integration like this one and a repository provider or an MCP tool.

Connect your account

Setup is one screen, and the credential is yours, not the workspace's. You open Integrations under Platform, add an Azure DevOps integration, and give it three things: the organization URL, the project, and a personal access token that can reach that project. The platform validates the token against the project before it saves anything, stores it under your account, and provisions the Azure DevOps connection the agent uses to reach your work items.

The split between the workspace and the person is deliberate, and it is the same split that runs through every integration. An admin wires the integration for the workspace once: the organization, the project, the shape of the mappings. Each person who works through it connects their own token, because access to Azure DevOps is a personal thing. When you set up your token, the integration reads and writes ADO as you, with your name on the work, and your access governed by exactly what your token can already reach in ADO. Nothing here widens what you can touch in Azure DevOps; it carries the access you already have into the work you do in Disco Parrot.

That is why a freshly wired integration can show "awaiting your PAT" against your name even though the workspace connection is live. The workspace knowing about the project and you being able to act in it are two different facts, and the integration tracks them separately.

Your personal auth state reads one of three ways: connected, not yet connected, or gone stale if the token stops validating. You always know whether the link will act for you or wait for you.

You can rename the integration, or reconnect a token, from its detail page at any time. The integration name is optional and defaults to the organization and project, so a workspace with one Azure DevOps project rarely needs to set it; a workspace with several names them to tell them apart.

When the token will not validate

Validation runs before anything is stored, so a token that cannot reach the project never becomes a connection that fails quietly later. When it does not validate, the reason is one of a few, and each points at a different fix rather than a generic red X.

• The token cannot reach the project. The organization URL or the project name is off by a character, or the token was issued against a different organization. Check that the URL is the one you would paste into a browser to land on the project, and that the project name matches it exactly.
• The token is missing the access the integration needs. A token scoped to read but not write validates for reading and stops short of the write-back the integration does on your behalf. Reissue it in Azure DevOps with work-item read and write, and reconnect.
• The token expired. Azure DevOps personal access tokens carry an expiry, and one that was fine last month stops validating the day it lapses. This is the same path as a stale token: reconnect with a fresh one, and the integration re-validates against the project and stores the new token under your account.

The reason the platform validates up front, rather than at the first write, is that a credential problem found at setup is a thirty-second fix at your desk. The same problem found mid-run costs an agent the work it was doing and costs you the time to trace why it stopped. Failing early is the cheaper place to fail.

Map how your concepts line up

Disco Parrot and Azure DevOps both describe work as a nesting of records, and the integration's job is to say which of yours is which of theirs. Out of the box it maps to the shape most Azure DevOps projects already use:

Those are starting points, not a cage. The mapping editor lets you change which ADO work-item type each concept maps to, and then map the fields within each one: which Disco Parrot field writes to which ADO field, and which ADO fields get a fixed default value on every write.

The field list you map against is not a guess. When you pick a work-item type, the integration reads the real fields for that type live from your project over the Azure DevOps REST API, so a team that has customized its work-item process sees exactly the fields it actually has, custom ones included, rather than a generic set someone hardcoded. The mapping reflects your Azure DevOps, not a textbook version of it.

A default value is for the field that should read the same on everything the integration writes, regardless of what the Disco Parrot side says. Area Path and Iteration Path are the usual ones: every Feature this integration creates belongs under the same part of the board, so you set it once as a default rather than carrying it as a field nobody edits. A default is also how you satisfy a field your process marks required but Disco Parrot has no concept for, so the work item lands valid on the first write instead of bouncing back because a required field was empty.

Custom fields are where live discovery earns its place. A team that added a Risk tier field to its Feature process, or renamed the standard ones, sees those exact fields in the editor, because the list is read from the project the moment you pick the work-item type. You map a Disco Parrot field to your custom one the same way you map it to a standard one. The integration never asks you to reconcile your process against a fixed list it shipped, because it does not ship one.

Edit the mappings

The mappings live on the integration's own Mappings page, which you open from its detail page under Platform. Editing them reads your project's fields live, so you connect your own token first; the editor opens once you have. Each concept is a tab across the top, and the tab flags how many of that concept's required Azure DevOps fields are still uncovered, so you can see at a glance where work remains.

Editing one concept is a short loop:

1. Pick the concept tab, Initiative, Plan, or Test case, and set the Azure DevOps work-item type it maps to. You choose from the types read live from your project, or type one. Changing the type reloads that type's fields underneath.
2. Add a field row with Add field mapping, and choose its Source: a Platform field, filled from the record when the integration writes, or a Static value, the same on every write. A platform-field row pairs a Disco Parrot field with the Azure DevOps field it writes to; a static-value row writes a fixed value you type.
3. Pick the Azure DevOps field the row writes to. The list is the one discovered from your project, and each option shows its type and a Required badge so you can see what your process insists on before you map to it.
4. Edit or remove a row in place: change either side from its dropdown, switch a row's Source between a field and a static value without losing the Azure DevOps target, or remove the row with its delete control.
5. Save Mappings, or Cancel to discard. Saving is blocked while any field is both mapped and defaulted. A required Azure DevOps field left uncovered does not block the save, but it is flagged, because Azure DevOps will refuse the write until that field has either a mapping or a default.

A Required Azure DevOps fields panel sits above the rows and lists every required field with its status, mapped, defaulted, or still uncovered, and gives each uncovered one a one-click Add mapping or Add default that pre-fills the field so you only choose the source. For wider changes, a Bulk actions menu offers Auto-map matching fields (it pairs the obvious ones by name), Reset to last saved, and Clear all in this concept.

Work the same record from both sides

Once the connection is live and the mappings are set, an initiative in Disco Parrot and its Feature in Azure DevOps are two views of one piece of work, kept in step across the link. You describe and refine the work where it is most natural, and it lands as the matching ADO work item with your mappings applied. The engineer working from the Azure DevOps board sees the same item, and the link back to the Disco Parrot spec rides along with it.

The fields you mapped carry the meaning across, so a state change or an owner reads the same on both ends instead of drifting into two versions of the truth. The mapping is what makes that possible: because each side knows which of its fields answers to which of the other's, the record stays one record wearing two faces, not two records someone reconciles by hand.

On the Disco Parrot side, the link lives in the initiative's Spec-tab sidebar under External system links: the integration it belongs to, the Azure DevOps work-item ID as a link straight through to the item in ADO, the test cases tied to it, and when it last synced. The test cases listed there are the ones mapped to their own Azure DevOps Test Case work items, so the verification that proves the work rides next to the work rather than living somewhere a reader has to go hunt for it. A PM reading the initiative sees that the work is tracked in Azure DevOps and gets there in one click; the engineer on the board sees the link home to the spec. Neither has to ask the other what the current state is.

Test cases ride with the work

The reason test cases sit in the default mapping, next to initiatives and plans, is that the proof a piece of work is done belongs with the work, not in a separate tracker someone cross-references by hand. A test case in Disco Parrot maps to a Test Case work item in Azure DevOps, and the initiative's External system links list the test cases tied to it right alongside the work item itself. A PM reading the initiative sees what verifies it; an engineer on the board sees the same test cases attached to the Feature. The verification and the work are one record seen from two seats, the same way the work itself is.

What the agent reaches

Connecting your token does one more thing besides validating it: it readies the Azure DevOps connection the agent works through. Your token is what proves you can reach the project and what powers the live field discovery and mapping you do at setup. The connection it readies is the agent's path to your work items: during a run, the agent reaches Azure DevOps through it a call at a time, the way it reaches any MCP tool, and under the same approved-actions controls as every other tool the agent can use. It reads or writes a work item when the work in front of it calls for one, never with more reach than the access behind the connection carries in Azure DevOps.

Your access is yours

The reason the token sits at the user level, and not on the workspace, is that it is the cleanest answer to a question every team eventually faces: what happens to the connection when a person leaves. Here, the answer is nothing dramatic. Their ability to act in Azure DevOps was always their own access; it leaves with them, the workspace integration stays standing, and the next person connects with their own token. There is no shared service credential to rotate in a panic, and no moment where one departure quietly breaks the link for everyone.

It is also the right shape for attribution. When the integration creates or updates an Azure DevOps work item on your behalf, it does so as you, with your access, so the trail in Azure DevOps reads the way your team expects: your name on your work, governed by what you were already allowed to do. The agent acting through the integration is never more powerful than your token, which is never more powerful than you are in Azure DevOps.

Removing the integration is the workspace-level counterpart, and it is admin work. It tears down the workspace connection and its mappings, so nothing further crosses the link. Your Azure DevOps work items are untouched; what goes away is Disco Parrot's side of the connection, and re-wiring later is the same one-screen setup with each person reconnecting their own token.

More than one project

The setup screen points at one organization and one project, because that is the unit Azure DevOps governs work in. A workspace that spans several projects wires an integration for each, and the shape repeats: the same one screen, the concept and field mappings decided per project, the same personal token from each person who works through it. The Integrations list holds them side by side.

The mappings are not shared across projects, and that is the point. A team whose Payments project customized its work-item process differently from its Platform project maps each to the fields it actually has, rather than forcing one mapping to fit both. What carries across is the model, not the configuration: the admin wires each integration once, every person connects their own token to the ones they work in, and the audit trail keeps each integration's configuration and each person's authorization as their own events. The second project costs what the first did, and adding it widens nobody's reach in Azure DevOps.

Permissions

Wiring the integration for the workspace is admin work, held by integrations.manage: configuring the organization and project, setting the concept and field mappings, and removing the integration. Connecting your own token on top of it is yours, held by integrations.user-credential.manage and scoped to your own account, so an admin sets up the workspace integration once and each person connects their own Azure DevOps access without an admin in the middle.

The two actions land in the audit trail as two different kinds of event, because they answer two different questions. Wiring or changing the integration is recorded as a configuration change: who set the mappings, and when. Connecting your token is recorded as an authorization event against you. A reviewer asking "who can act in Azure DevOps through this workspace" reads the second; one asking "who changed how we map plans to backlog items" reads the first.

A connection, set up end to end

An admin on the Payments team wires the integration once. He opens Integrations under Platform, adds Azure DevOps, and gives it the organization URL, the project (Payments), and his own access token. The platform validates the token against the project and saves the workspace integration. He opens the mapping editor, leaves Initiative mapped to Feature and Plan to Product Backlog Item, and adds one default: every Feature the integration writes gets an Area Path of Payments\Platform, because that is where his team's work belongs on the board. He saves and is done.

Priya, a product manager on the same team, opens Integrations the next morning. The Azure DevOps row is live, but her own status reads "awaiting your PAT," because the workspace knowing about the project and Priya being able to act in it are two different facts. She connects her own token, it validates, and her status flips to connected. From then on, when she refines an initiative in Disco Parrot, it lands as a Feature in Azure DevOps under Payments\Platform, written under her access, with her name on the work.

Marcus picks up that Feature from the Azure DevOps board the way he picks up any other. The fields Priya set carry across, and the work item links back to the Disco Parrot spec, so when he wants the why behind the what, it is one click away. Neither of them ran a status meeting to stay in step. The record did it for them.

Why the integration works this way

The usual way a planning tool talks to a work tracker is to declare itself the system of record and treat the tracker as a place to dump rows. That works right up until the team that actually lives on the board notices their tool has been demoted to a mirror of someone else's, and they stop trusting it. Disco Parrot does the opposite: it treats Azure DevOps as a peer with the same shape of work, maps your concepts to its types rather than flattening them, and keeps your access personal so the connection reflects who is really doing what. The point is not to pull your team off the board. It is to let the planning and the board be the same work seen from two seats.

For a planner, the integration means the spec you refine in Disco Parrot and the Feature your engineers pull from in Azure DevOps are one item, not two you reconcile by hand. You write the work once, in the place that is richest for shaping it, and it is there on the board where the team takes it forward.

For an engineer, nothing forces you off the Azure DevOps board you already work from. The work shows up where you expect it, mapped to the fields your process actually uses, and the link carries you back to the full spec when you want the why behind the what.

For a lead, the integration means you stop running two status meetings off two systems. You decide how your concepts line up once, and from then on the initiative and its work item move together, so the read you give your stakeholders from Disco Parrot and the read your engineers act on in Azure DevOps are the same read, not two you spend Monday reconciling.

For the person who has to sign off on connecting an external system, the credential model is the answer: every token is personal, validated before it is stored, scoped to exactly what that person can already reach in Azure DevOps, and recorded as its own authorization event. The integration never holds a shared key that outlives the people who set it up, and it never grants reach that the person behind it did not already have.