Azure DevOps

Watari connects to Azure DevOps (Azure Repos) through Microsoft Entra ID. It gets read access to your repositories, so it can find where an issue lives in your code, and write access to open draft fixes as draft pull requests, nothing more. Everything Watari does on GitHub, it does on Azure DevOps: get your code ready to search, find the files and functions behind an issue, open draft fixes, watch build validation, and confirm production deploys before sending the customer update.

Why Microsoft Entra ID, not a personal access tokenCopy Anchor Link

Watari authenticates with your Azure DevOps organization through Microsoft Entra ID (the modern, tenant-backed OAuth flow), not a personal access token. An Entra connection is bound to your organization's tenant, uses short-lived access tokens that are refreshed automatically, and can be revoked in one place by an administrator, from Microsoft Entra → Enterprise applications or from your Azure DevOps organization's OAuth authorizations. Personal access tokens are user-bound, long-lived, harder to revoke cleanly, and carry broader scope than Watari needs.

Connecting Azure DevOpsCopy Anchor Link

Connecting more than one organizationCopy Anchor Link

Many teams keep their code in one Azure DevOps organization and log customer problems in another. One Watari workspace can connect both through the same Microsoft sign-in:

• When you first connect, tick every organization you need on the organization screen.
• To add one later, open Settings → Connected tools → Azure DevOps → Configure and click Add another organization. Organizations already connected appear ticked; tick the new one.
• To remove one, use Remove next to it in the same dialog. Watari stops picking up work items there, removes the connections it set up there (Azure calls them service hooks), and removes that organization's repositories from Watari (recoverable for 30 days). Your other organizations keep working. Disconnect Azure DevOps, at the foot of the same dialog, removes the whole Azure DevOps connection.

When you connect a repository, Watari asks which organization it is in. When you choose projects for picking up work items or for filing, projects from every connected organization are listed together, labelled with their organization. The account that connects needs the permissions described below in each organization it is used in.

An Azure DevOps organization can belong to only one Watari workspace.

What Watari can doCopy Anchor Link

Through Entra delegated access, Watari acts on the Azure DevOps REST API on your behalf, using only the operations it needs:

Watari never deletes branches, force-pushes, or changes organization settings. Draft fixes are opened against your default branch and always sit behind your own branch policies.

Getting your code readyCopy Anchor Link

After you connect a repository, Watari reads it and gets it ready to search. For a typical SaaS repository this takes a few minutes. Large monorepos take longer; progress is visible under Codebase in the dashboard, and the repository reads Ready when it is done.

Azure Repos often use master as the default branch rather than main. Watari resolves your repository's actual default branch automatically. There is nothing to configure.

Each push to the default branch is picked up automatically (Watari sets up a service hook for this when you connect), so Watari keeps searching your latest code without any manual action.

Filing work items in Azure BoardsCopy Anchor Link

Filing is optional. Open Settings → Connected tools → Azure DevOps → Configure and turn on File work items in Azure Boards, then choose the project (and, if you like, which area and sprint it lands in) and which issues to file: only the ones Watari found in your code (recommended), or every issue. Turn the switch off and Watari files nothing in Azure Boards, while finding issues in your code and drafting fixes keep working. The project you chose is kept, so turning filing back on restores it.

Watari files each issue as a work item type your project's process actually has: a bug as a Bug (or an Issue on the Basic process), and a feature request as a User Story, Product Backlog Item or Requirement (an Issue on Basic).

Picking up work items from Azure BoardsCopy Anchor Link

If your team logs customer problems as work items rather than in a support desk, Watari can read them the same way it reads a support ticket. This is off until you turn it on, because connecting Azure DevOps for code and pull requests is not the same as asking Watari to read your boards.

Before you startCopy Anchor Link

• Connect at least one repository first. It sets up the secure connection that work items arrive through.
• Check the permissions of the person who connected Azure DevOps. Watari subscribes to work item events in each project you choose under that person's account, so they need the Edit subscriptions and View subscriptions permissions in every one of those projects (project administrators have both by default), and they must be able to read their work items. Azure never delivers events for items the subscribing account cannot see. If they are missing, the settings dialog shows Azure's own error when you save, and nothing is picked up.
• Only an owner or admin of your Watari workspace can change these settings.
• Give the people who file work items a format to follow. A work item with a title and one line is hard to find in code. The free bug report template lists the nine fields that matter and copies the result as Markdown for the work item description.

Set it upCopy Anchor Link

1. Open Settings → Connected tools → Azure DevOps → Configure and turn on Pick up work items from Azure Boards. The pickup settings appear once it is on.
2. Choose the projects to read work items from: one or more, in any connected organization. They can include the project your code is in; Watari looks for each work item in every repository you connected either way, in every organization, and receives nothing from projects you leave unticked.
3. Choose how work items are handed to Watari. You can combine any of these:
   • Mention. Someone types @watariai in the work item's description or a comment. Works on any work item, new or old. Mentioning it again in a comment on a work item Watari already has, with where to look ("@watariai the export runs in reports/csv"), starts it again with that detail when Watari stopped without a draft fix or found the code and is waiting to draft, and Watari replies that it is trying again. A mention with nothing else in it gets a reply with where the work item stands and a link to it in Watari. On a new work item, mention @watariai in a comment rather than the description: Azure Boards opens its people picker when you type @ in a new work item's description, and the mention is dropped.
   • Assignment. Someone assigns the work item to an identity you list, such as a dedicated Watari user. On Azure DevOps a dedicated user can take a paid seat, which is why mentions are the no-cost option.
   • Every new work item. Watari picks up each work item when it is created in one of those projects. Existing work items are never picked up this way, so switching it on does not pull in your backlog.
   • Fields. Narrow automatic pickup to the work item types (Bug, Task, Feature, Issue, User Story, or any type your process uses), states, tags (any one matches) and an area path you choose. Leave a field empty and it does not narrow anything. With Every new work item on, the fields decide which new items are picked up; with it off, a work item is picked up when it comes to match every field you filled in, for example when someone adds a watari tag.
4. Save. Then create one test work item in one of those projects (or mention @watariai in a comment on an existing one) and watch it appear under Issues within a minute or two.
5. Open the dialog again to see the Recent work items list. It shows each work item Watari has received from those projects and what your saved settings did with it. Change a setting and the list shows what the new one would do with the same work items before you save it. The list starts empty: it fills with work items created or updated after pickup is on, and does not list the ones you already had.

If you disconnect Azure DevOps and later connect Watari to different Azure DevOps organizations, work item pickup is switched off and its project list is cleared, because those projects belonged to the previous organizations. Choose the projects again to turn it back on. Reconnecting to the same organizations changes nothing, and adding an organization to a live connection keeps everything you already set up.

What happens nextCopy Anchor Link

Watari works on each work item it picks up the same way as on a support ticket. Questions that are not code defects (a configuration change, a usage question, a how-to) get a suggested answer for your team instead of a draft fix. A work item counts toward your Mapped Issue allowance only if Watari finds it in your code. If you pick up every new work item on a trial, which includes a limited number of Mapped Issues, start with a narrower rule or with mentions so the allowance goes to the issues you care about most.

A work item Watari picked up is its own issue: Watari posts progress on it and does not file a second work item beside it, even when issue filing to Azure Boards is switched on. Work items Watari files for reports that came from somewhere else (a support desk, for example) are never picked up as new reports, so the two features can run in the same project.

Watari also comments on each work item it picks up, and keeps it to what someone needs to read: that it is looking for the cause, then "Your move · Ready for a fix" once it finds the code, "Your move · Review the fix" once it drafts one, "Your move · Needs an engineer" if it cannot find the code or stops without a fix (with a short summary of what it found), and "Your move · Watari asks" when it is missing one fact. The full list is in What Watari's comments say. Comments never list file paths or scores; those are in Watari, one click from the comment. When the draft fix opens in Azure Repos, Watari also links its pull request to the work item, so the pull request lists the work item under Work items and the work item shows the pull request under Development. Comments appear under the name of the person who connected Azure DevOps, with a "Posted by Watari" footer. If you have added Watari's service principal to your organization (see Watari as the author below), comments and links are made by Watari instead, the same identity that authors the pull request. On a project that is not private, comments carry where the work item stands and a link to Watari only, without pull request links or investigation notes. When the fix ships and your team approves the customer update (what went wrong and how it was fixed), Watari posts it on the work item too, so whoever filed it can pass it on. You can turn these comments off in the same dialog; the customer update then stays in Watari.

Reviewer routingCopy Anchor Link

Azure DevOps does not use a CODEOWNERS file. Watari suggests reviewers from the commit history of the files where it found the issue, and adds them as reviewers on the draft fix. The reviewers chosen for each issue are shown on the issue page. Suggesting owners for a whole repository, under Codebase → Who owns this code, works on GitHub repositories today and comes to Azure DevOps later.

If you enforce required reviewers through a branch policy, those take precedence, Watari's inferred reviewers are added alongside them, never in place of them.

Branch policiesCopy Anchor Link

Watari opens draft fixes against your repository's default branch. Azure DevOps runs build validation and required-reviewer policies only once a pull request leaves draft state, so Watari publishes the draft when the fix is ready, at which point your branch policies run exactly as they would for any pull request a person opened.

Watari does not bypass branch policies. If your policy requires build validation to pass or a minimum number of approvals, the pull request will not complete until your Azure Pipelines and human reviewers satisfy them.

Watari as the author (optional)Copy Anchor Link

By default, a draft fix is authored by the user who connected Azure DevOps, because Entra sign-in acts on that user's behalf. The same goes for Watari's pull request comments, the reviewers it adds, and the work items and comments it files. If you would prefer all of them to read Watari instead of a teammate, add Watari's service principal to your Azure DevOps organization once. Configure on the Azure DevOps card shows these steps under Show as Watari in Azure DevOps, and says done once Watari can see a private project in your organization (an organization with only public projects keeps showing them):

Once added, new draft fixes, pull request comments, added reviewers, filed work items, and the comments and links on work items are authored by Watari in projects the service principal can contribute to. In a project or area it cannot reach, Watari falls back to the connecting user, so nothing stops working. This mirrors how tools like Renovate, GitHub Copilot, and Devin operate on Azure DevOps, Azure has no way to auto-install an app identity into your organization, so this one-time step is what grants the bot identity.

Multi-repo supportCopy Anchor Link

If an issue is found in code across more than one connected Azure DevOps repository, Watari opens linked draft fixes in each repository and tracks them together. The customer update is held until every one of them merges and a successful production deploy is confirmed in every affected repository.

Watari can search and open draft fixes across GitHub and Azure DevOps repositories in the same workspace: an issue goes to whichever repositories its code actually lives in, regardless of provider.

Deploy confirmation and the customer updateCopy Anchor Link

Watari confirms a production deploy before it sends the customer update. For Azure DevOps, it waits for the stage of your YAML pipeline (in Azure Pipelines) that targets your production environment to complete successfully. Once the merge and the production stage are both confirmed, Watari writes the customer update, and once your team has approved it, it is delivered to where the report came in (unless you switched to manual publishing, in which case someone on your team clicks Publish).

DisconnectingCopy Anchor Link

Disconnecting Azure DevOps from Settings → Connected tools immediately revokes Watari's access, and Watari stops reading and drafting fixes in the connected repositories. Past issues, where they were found in your code, and customer updates remain in your Watari workspace for 30 days after disconnect, then are purged. You can reconnect at any time.

---

Next: Routing and notifications: Slack, Microsoft Teams, Linear, and Jira setup: configure team chat, Linear, Jira, and issue-tracker sync.