Azure DevOps Integration

Connect Azure DevOps Boards to sync work items between Zero0 and your Azure DevOps organisation.

What's Supported​

• Azure Boards only. Zero0 syncs work items: their titles, descriptions, comments, tags, links and attachments. Azure Repos and Azure Pipelines are not used; connect your code with GitHub, GitLab or Bitbucket.
• Azure DevOps Services only, the cloud service at https://dev.azure.com/<your-org>. Azure DevOps Server (on-premises, formerly TFS) is not supported.
• One organisation per Zero0 account, and one Zero0 account per organisation.
• One issue tracker per account. A Zero0 account uses Jira or Azure DevOps, never both. If Jira is connected, disconnect it before you connect Azure DevOps.
• Zero0 owns status. Zero0 keeps its own status for every story, and workflows start only from Zero0. Azure DevOps is updated only when a story moves to In Progress or Validation, once, on a best-effort basis (see Action Mapping). Changing a work item's state in Azure DevOps doesn't change the story's status in Zero0 and doesn't start a workflow.

Zero0 reads these work item types from your backlogs:

Azure DevOps	Zero0
Epic	Initiative
Feature	Epic
User Story, Product Backlog Item, Requirement, Issue (Basic process)	Story
Bug	Story, or Subtask when the team tracks bugs with tasks
Task	Subtask

Types that are hidden, or on no backlog level (for example the Agile process's Issue, or CMMI's Risk and Change Request), are not imported.

Connecting with the Zero0 App​

Connect Azure DevOps as the Zero0 app. Your Microsoft Entra admin approves the Zero0 app in your tenant, and your Azure DevOps admin adds it to the organisation, the same way you add a user. No one signs in on Zero0' behalf, which gives you two things:

• Changes show as Zero0, not as a person. Work items Zero0 creates or edits, its comments and its tags show the Zero0 app as the author.
• Access is not tied to anyone's account. A person leaving, changing role or resetting a password doesn't break the connection. You decide what the app can reach, and you can remove it at any time (Revoking access).

Before You Start​

Your organisation must be connected to Microsoft Entra ID. Check this in Azure DevOps under Organization settings → Microsoft Entra. An organisation that signs in only with personal Microsoft accounts can't use the Zero0 app, because it has no Entra tenant to approve the app in.

Two roles are needed. One person may hold both.

Who	Needed for
An Entra admin who can grant tenant-wide admin consent (for example a Global Administrator or a Cloud Application Administrator)	Step 1: approving the Zero0 app in your tenant
An Azure DevOps organisation admin (a member of Project Collection Administrators)	Steps 3 and 4: adding the app to the organisation and allowing it to manage its service hooks

A Zero0 admin runs the steps from Settings → Integrations → Azure DevOps, and can hand step 1 to the Entra admin and steps 3 and 4 to the Azure DevOps admin.

Cost. The Zero0 app needs the Basic access level in your organisation. Azure DevOps counts it as a user, so it takes a paid Basic seat, unless one of the organisation's 5 free Basic seats is still unused. Stakeholder access isn't enough: a Stakeholder can't create new tags or delete work items, and Zero0 does both, so setup doesn't let you finish with Stakeholder access.

The Five Steps​

Go to Settings → Integrations → Azure DevOps and click Connect as the Zero0 app. The panel walks you through the steps below, in this order. In the panel, steps 3 and 4 are the checklist under Set up Zero0 in Azure DevOps, and step 5 ends with Finish connecting.

Step 1: Approve Zero0 (Admin Consent)​

1. Click Approve Zero0 in Microsoft Entra. Zero0 sends you to Microsoft's admin consent page, where the Entra admin must sign in. If you aren't the Entra admin, click Get a link for an Entra admin and send them the link. It works for 10 minutes, and they open it in a browser where they are signed in to Zero0 as an admin of your Zero0 account.
2. Microsoft's page names the Zero0 app and asks you to accept, for your whole organisation, the permissions it requests on Azure DevOps. Accepting adds the Zero0 app to your tenant as an enterprise application (a service principal). Consent alone gives the app access to no organisation and no project. Azure DevOps lets it in only after step 3.
3. The tenant sign-in. Right after you accept, Microsoft asks you to sign in to the same tenant once more. This tells Zero0 which tenant approved the app. Sign in with an account that is a member of that tenant, not a guest invited from another tenant. This sign-in also lets Zero0 list the Azure DevOps organisations you belong to, once, for step 2. Zero0 doesn't keep that access, and it reads no mail.
4. Back in Zero0. Microsoft sends you back to the Azure DevOps settings page, and Zero0 confirms the approval as the page loads. Finish this in the same browser within 5 minutes, signed in to Zero0 as an admin of your Zero0 account. The panel shows Zero0 was approved in your Microsoft Entra tenant.

Step 2: Choose the Organisation​

The Organisation dropdown lists the Azure DevOps organisations that the person who signed in at step 1 belongs to, in the tenant that approved Zero0. Choose yours and click Continue. If there is only one, it is already selected.

If your organisation isn't listed, choose Type another name and enter the organisation's name: the part after dev.azure.com/, for example contoso for https://dev.azure.com/contoso. This happens when the person who signed in isn't a member of the organisation, or when Zero0 couldn't read the whole list.

Zero0 checks that the organisation exists, that it belongs to the tenant that approved Zero0, and that it isn't already connected to another Zero0 account. Zero0 tracks the organisation by its id, not its name, so renaming it later doesn't change which Zero0 account it belongs to. To pick another organisation later in the setup, click Change.

Step 3: Add Zero0 to the Organisation​

The Azure DevOps organisation admin does this in Azure DevOps:

1. Go to https://dev.azure.com/<your-org> → Organization settings → Users → Add users
2. Search for the Zero0 app by its name. It's the enterprise application created in step 1, and the panel shows its name
3. Set Access level to Basic. Don't use Stakeholder (cost)
4. Under Add to projects, choose every project Zero0 should work in, with the default Contributors group
5. Click Add

Zero0 can only see and change work items in the projects you add it to here.

Step 4: Allow Zero0 to Manage Its Service Hooks​

Azure DevOps tells Zero0 about work item changes through service hooks. The app needs the organisation's service hooks permission to create its own. An organisation admin grants it once, with one Azure CLI command:

1. Install the Azure CLI, or use the Bash shell of Azure Cloud Shell, which has it already

2. Add the Azure DevOps extension:

   az extension add --name azure-devops
   

3. Sign in as the Azure DevOps organisation admin:

   az login
   

   If your tenant has no Azure subscriptions, use az login --allow-no-subscriptions.

4. Once step 3 is done, the panel shows the exact command for your organisation under Allow Zero0 to manage service hooks. Click Copy and run it. It has this form:

   az devops security permission update --org https://dev.azure.com/<your-org> --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --token PublisherSecurity --allow-bit 7 --subject '<descriptor>'
   

   Copy it from Zero0 rather than typing it: <descriptor> is the Zero0 app's own identity in your organisation, which only the panel shows. The command is quoted for Bash or zsh (Azure Cloud Shell's Bash works); in PowerShell or cmd the quoting can break.

The command allows View, Edit and Delete on service hook subscriptions, and changes nothing else. It grants no access to repositories, pipelines, board settings or other organisation settings.

Step 5: Check Again, Then Finish​

1. Click Check again. Zero0 checks, as the app and live each time you click, that:

   • Add Zero0 to the organisation - the app was added to the organisation (step 3) with Basic access or higher
   • Allow Zero0 to manage service hooks - the app has View, Edit and Delete on service hook subscriptions (step 4)
   • Projects - which projects the app can see

   Each item shows ✅ Done, ❌ Not done or Couldn't verify, with what to do next. Until the app is added, the other items can't be checked yet.

2. Optionally choose the projects Zero0 should work in, up to 50. Leave the choice empty and Zero0 works in every project it was added to (see Projects).

3. Click Finish connecting. It turns on once Zero0 is added with Basic access and allowed to manage service hooks. If Zero0 couldn't read the app's access level, that item shows Couldn't verify and doesn't block you, but make sure in Organization settings → Users that the app has Basic.

Zero0 runs the checks once more, stores the connection, creates its service hooks and starts importing your work items. The card then shows Connected to <your-org> as the Zero0 app, and which name your changes show under in Azure DevOps.

What Zero0 Can Access​

• In your Entra tenant: the Zero0 enterprise application, created by your admin consent. Zero0 uses it only to get Azure DevOps access for your tenant.
• In your Azure DevOps organisation: what you give it in step 3, a Basic access level and membership in the projects you added it to. With these, Zero0 reads, creates, updates and deletes work items, including their comments, tags, links and attachments, in those projects only. A project limit set in Zero0 narrows this further; it never widens it.
• The service hooks permission from step 4, which covers service hook subscriptions only.

Zero0 is not an organisation admin, and it can't reach projects you didn't add it to.

Switching from a User Connection​

Next to the Zero0 app, the card offers Sign in with your account: Zero0 then acts as you, every change shows under your name, and the connection stops working if your sign-in expires or you lose access. The Zero0 app is recommended.

If your account is already connected as a user, click Switch to the Zero0 app and follow the same steps. The user connection keeps working until you click Finish connecting. From then on:

• Zero0 acts as the app. Changes made before the switch keep their original author in Azure DevOps.
• Zero0 recreates its service hooks as the app, one set per project, and then removes the ones the user connection created, using the previous user's sign-in once. If that sign-in no longer works (for example the person left), the old hooks stay and Azure DevOps sends some updates twice. The Service hooks section then says so: click Remove the previous user's service hooks and sign in to Microsoft as the person who originally connected, or as another account that may manage the organisation's service hooks, or contact Zero0 support. You can't remove these hooks from Azure DevOps' own pages.

Projects​

Once connected, the Projects section shows where Zero0 works:

• Zero0 works in all projects of <your-org> - every project the app was added to in Azure DevOps. Click Limit to specific projects to choose some of them.
• Zero0 works only in these projects of <your-org> - the list you chose. Click Edit to change it, or Remove limit to work in every project again.

The limit only narrows what the app can reach. To give Zero0 a new project, add the app to it in Azure DevOps (Organization settings → Users, or the project's own settings), then include it in the limit if you use one.

When you change the limit, the service hooks follow at once: new projects get theirs and projects that left the limit lose them. A project you add the app to later gets its service hooks within the hour, or at once with Re-register hooks.

Status and Action Mapping​

These sections appear on Settings → Integrations → Azure DevOps once an organisation is connected.

Status Mapping​

Open Workflows and Statuses to see, for each project (with its process) and work item type, every Azure DevOps state, its State Category and the Zero0 Status it maps to.

Zero0 fills these mappings in for you the first time it meets a project, from each state's category in Azure DevOps, not its name:

State category	Zero0 status
Proposed	To Do
In Progress	In Progress
Resolved	In Progress
Completed	Done
Removed	Done (counted as cancelled, never as completed work)

If one state name has different categories on different work item types in a customised process, it maps to In Progress.

To change a mapping, use the Status mappings table under the projects. Mappings are account-wide: one per state name, for every project and work item type. Zero0 only adds mappings for states it hasn't seen; it never changes one that exists, so your edits are kept.

Issue Type Mappings works the same way for work item types: Zero0 adds each backlog type with the level from What's Supported, and you can change it. A type's level is account-wide, so the first project Zero0 meets, or your edit, decides it for every project.

Action Mapping​

Open Actions Mapping to choose the status each Zero0 action applies:

Action	What it sets
Approve	The status applied when a story is approved
Cancel	The status applied when a ticket is cancelled
In Progress (Azure DevOps mirror)	The state a work item moves to when Zero0 moves its story to In Progress
Validation (Azure DevOps mirror)	The state a work item moves to when Zero0 moves its story to Validation

Because Zero0 owns status, these two mirror moves are the only status changes Zero0 makes in Azure DevOps. Each is one best-effort attempt. When you haven't chosen a state, Zero0 looks for a state named exactly In Progress or Validation in the work item's type; for In Progress, it otherwise uses the type's first state in the In Progress category. If no state fits, the work item stays where it is, and the story shows a note so you can set the mapping. Done is never mirrored to Azure DevOps.

Custom Fields​

Open Field Mappings to see which Azure DevOps field each Zero0 field reads. Azure DevOps fields are named by their reference name in brackets, for example [System.Title] or [Microsoft.VSTS.Scheduling.StoryPoints]. Zero0 maps these by default:

Zero0 field	Azure DevOps field
Summary	Title
Status	State
Assignee	Assigned To
Priority	Priority
Team	Area Path
Sprint	Iteration
Due date (initiatives and epics)	Target Date
Story points	The work item type's own field: Story Points (Agile), Effort (Scrum) or Size (CMMI)
Description	The work item's description (Repro Steps on a bug that has it)

To change one, edit its Azure DevOps Field with another reference name in brackets. The sprint must be one iteration field, [System.IterationId], with nothing after it.

To bring in a field of your own, click + Add custom field, enter a Field ID and a Display Name, choose its type, then map it to the Azure DevOps field. Fields your inherited process adds have reference names that start with Custom., for example [Custom.RiskLevel].

A custom field of type Long text can also be edited in Zero0, and the change is written to the mapped Azure DevOps field. A field mapped to a calculated value, or to no Azure DevOps field, can't be written back.

Service Hooks​

Azure DevOps tells Zero0 about work item changes through service hooks. Zero0 creates and keeps its own, per project: one for each event (work item created, updated, deleted, restored and commented) in every project Zero0 works in. There is no webhook for you to set up.

The first set is created in the background after Finish connecting, one Azure DevOps call per project and event, so the list fills in over the next few minutes, longer for many projects.

Azure DevOps stops sending updates to a service hook after a failed delivery, and only Zero0 turns it back on. Zero0 checks its hooks when you connect, when you click Re-register hooks, and once an hour, and fixes what is missing or turned off.

Open Service hooks to see each event with its status in Azure DevOps (Not registered when it's missing), and the health line:

Hooks last checked: 5m ago — Healthy

Health	What it means
Healthy	The last check was less than 3 hours ago, it succeeded, and every hook was in place
Failing	The last check failed, or Azure DevOps refused to create or turn on at least one hook. Updates from the affected projects may not reach Zero0
Not checked recently	No check in the last 3 hours, so a hook Azure DevOps turned off may still be off
Not known yet	No check has been recorded yet, for example right after you connect

When the health is Failing or Not checked recently, the line says why, and admins also see a banner on the board that links to this section. Click Re-register hooks to run the check now. It runs in the background and can take a few minutes for many projects; the line updates when it's done. If it keeps failing, see Service hook health.

Webhook Logs lists recent deliveries, from Azure DevOps' own delivery history.

Troubleshooting​

The Setup Checks​

What the panel shows	What it means	Fix
Add Zero0 to the organisation: ❌ Not done, the app isn't added	The Zero0 app isn't a user of the organisation yet. Until it is, the other items can't be checked and no command is shown.	Do step 3, then click Check again. Make sure you added the Zero0 enterprise application, in the organisation you chose in step 2.
Add Zero0 to the organisation: ❌ Not done, Zero0 "needs Basic"	The app has Stakeholder access (or none). It can't create new tags or delete work items. Finish connecting stays off.	In Organization settings → Users, change the app's access level to Basic, then Check again.
Add Zero0 to the organisation: Couldn't verify the access level	Zero0 couldn't read the app's access level. This doesn't block finishing.	Confirm in Organization settings → Users that the app has Basic.
Allow Zero0 to manage service hooks: ❌ Not done	The app doesn't have all three of View, Edit and Delete on service hook subscriptions.	Run the command from step 4 as an organisation admin, then Check again.
Projects: ❌ Not done	Zero0 can't read any project of the organisation.	Add the app to the projects Zero0 should work in (step 3), then Check again.
Any item: Couldn't verify, "Azure DevOps didn't answer this check"	Azure DevOps couldn't be reached, failed, or gave an answer Zero0 couldn't read.	Wait a moment and click Check again. If it keeps failing, contact Zero0 support with the item and the reason shown.

If Finish connecting says Zero0 must be added with Basic access and allowed to manage its service hooks, something changed since the last check, for example the access level. Click Check again and fix what fails.

Refusals​

Message	Where	What to do
Zero0 wasn't approved: the admin declined, or the Microsoft sign-in didn't complete.	Step 1	Start step 1 again, as an Entra admin who can grant admin consent, and accept.
The approval expired or was replaced by a newer one. Start the approval again.	Steps 1 and 2	The approval link expired or was already used, a newer one replaced it, or it wasn't confirmed in Zero0 within 5 minutes. Start step 1 again from Zero0 and finish it in one go, in the same browser.
The Microsoft Entra tenants don't match.	Step 1	The tenant sign-in used a guest account, or an account of another tenant. Start step 1 again and sign in with an account that is a member of your tenant.
The Microsoft Entra tenants don't match.	Step 2	The organisation belongs to another Entra tenant than the one that approved Zero0. Check the tenant under Organization settings → Microsoft Entra, then run step 1 in that tenant, or choose an organisation of the approved tenant.
That Azure DevOps organisation wasn't found.	Step 2	Enter just the part after dev.azure.com/, not the full URL or a project name. Check that the organisation is connected to Microsoft Entra ID (Before you start).
That Azure DevOps organisation is already connected to another Zero0 account.	Steps 2 and 5	An organisation can be connected to one Zero0 account only. Disconnect Azure DevOps in the other Zero0 account first, or contact Zero0 support if you don't know which account holds it.

Two more messages you may see:

• Microsoft Entra ID refused the Azure DevOps sign-in; an admin must reconnect - Microsoft won't give Zero0 access for your tenant, for example because the Zero0 enterprise application was deleted or its consent revoked. Do step 1 again.
• Jira is connected to this account - disconnect Jira in Zero0 first.

Service Hook Health​

Health	What to do
Healthy	Nothing.
Failing	Click Re-register hooks. If it keeps failing, check the app's service hooks permission, then contact Zero0 support. If the section says the previous user's service hooks are still active, see Switching from a user connection.
Not checked recently	Click Re-register hooks. If it doesn't return to Healthy within a few hours, contact Zero0 support.
Not known yet	Wait for the first check, or click Re-register hooks. If it stays this way, contact Zero0 support.

Duplicate Service Hooks After the Zero0 Address Changed​

Zero0 recognises its service hooks by the Zero0 address they send updates to. If that address changes, for example a new hostname for a Zero0 appliance, Zero0 creates a new set and leaves the old ones in Azure DevOps. Delete the old ones yourself: in each project open Project settings → Service hooks and remove the subscriptions whose URL is the old Zero0 address.

Revoking Access​

Do all three to remove Zero0 completely:

1. Disconnect in Zero0 - see Disconnecting
2. Remove the app from the organisation - in Azure DevOps, Organization settings → Users, select the Zero0 app and remove it. This frees its Basic seat and ends its access to every project at once
3. Delete the enterprise application in Entra - in the Microsoft Entra admin center, Enterprise applications, open the Zero0 app, then Properties → Delete. This removes the consent from step 1

Disconnect in Zero0 first, while the app still has access, so it can delete its service hooks. If you remove the app first, its service hooks stay in Azure DevOps and you delete them yourself under Project settings → Service hooks. They can't deliver to Zero0 anymore either way.

Disconnecting​

Click Disconnect on the Azure DevOps card and confirm. Zero0 deletes its service hooks in your organisation, forgets the connection and releases the organisation, so another Zero0 account could connect it later. Syncing and status updates stop until you connect again.

Disconnecting doesn't remove the Zero0 app from your organisation or your Entra tenant; see Revoking access.