Connecting Azure DevOps
An Azure DevOps connection is an organization URL plus a token, shared across the projects you attach from it. Work items feed the board on their own; PR and commit intelligence is a separate, explicit opt-in per project.
Code-sync scope on an attached ADO project — explicit repos, not a pattern.
What it does, and where the data comes from
| Field | Value |
|---|---|
| Organization URL | https://dev.azure.com/your-org |
| Auth method | PAT (token only) or BASIC (username + token) |
| Access token | Scoped to Code (Read), Work Items (Read), and Project & Team (Read) |
| Project | Discovered live from the organization once the token tests successfully |
How to connect Azure DevOps
- Create a PAT under User settings → Personal access tokens with the read scopes above.
- Add source → Azure DevOps — set the organization URL, choose
PATorBASIC, paste the token, and test. - Pick the project from the discovered list.
- On the board's Source zone, turn on Feed work items to board, and separately, Use for code intelligence if you want PR/commit data.
What syncs
Work items sync per project whenever the project is attached — that part isn't opt-in. PR and commit intelligence is: useForIntelligence must be turned on for the board source, and the underlying project sync must have Pull requests and/or Commits switched on, scoped to either an explicit, named repo list or an explicit All repositories toggle.
Alongside name, status, owner and description, a work item's Due Date (Microsoft.VSTS.Scheduling.DueDate) is written onto the board row's Due date field on every sync. As with the other synced fields, editing it by hand takes that one field out of sync's control until you revert it — see Manual edits.
repo1, repo2) or flip the distinct All repositories switch. A newly attached project starts with PR sync, commit sync, and the all-repos switch all off; nothing gets pulled for intelligence until you turn each of them on deliberately. The repo-sync scope is shared — changing it on one board's source changes it for every board using that Azure DevOps project.Scoping a board to part of an Azure DevOps project
An ADO project is usually far larger than the team a board is about, and Azure DevOps has two independent scoping dimensions that are easy to confuse. They narrow different things, and picking the wrong one silently does nothing.
| Control | Where | Scopes | Empty means |
|---|---|---|---|
| Area paths | Board Content | Work items — the board rows and every issue-derived widget on Engineering Intelligence and Team Focus | All area paths |
| Repositories for code metrics | Code intelligence | Pull requests, commits and deployments | All repositories |
ado_work_items has no repository column at all, so picking two repos and expecting a narrowed Work in Progress count does nothing — the widget keeps counting the entire project. Area path is the work-item scope; repositories are the code scope. The Repositories picker now says so on its face: "Scopes pull requests, commits and deployments. Work items are scoped by area path, in Board Content."Area paths matter more than they look. Across one real install, all 25 attached ADO sources had no area path set — meaning every board's work items were project-wide. On one board that was the difference between a Work in Progress reading of 368 and a true 4.
Setting an area path
- Open the board's Sources panel and expand the Azure DevOps source.
- Under Board Content, use the Area paths picker. It lists the project's area paths with a work-item count against each, and has a filter box for large projects.
- Tick the ones this board is about. Matching is by prefix, so selecting
Atlas\Compliancealso admits everything beneath it.
Scoping code metrics to specific repositories
Under Code intelligence, Repositories for code metrics narrows which repositories the PR, commit and deployment widgets read. Leave it empty for all of them.
Before this existed, widgets read every repository ever ingested for the project. On one measured board, the project held 21 repositories and 2,513 pull requests, of which 58 were in the board's intended scope; the displayed median cycle time was dominated by out-of-scope repositories whose cycle time differed by roughly 10× (0.6 h in scope against 5.8 h out).
Under the hood
Both auth methods send HTTP Basic under the hood: PAT sends the token with an empty username; BASIC sends your entered username and the token as the password. The connection test hits /_apis/projects?$top=1, so a working test only confirms the token can list projects — not that it also has the Code and Work Items scopes PR/commit intelligence needs.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Connection test passes but no PRs/commits appear | PR/commit intelligence is opt-in and defaults off | Turn on Use for code intelligence and the project's PR/commit toggles |
| Only some repos show PR data | Repo scope is an explicit list, not a pattern | Add the missing repo names, or switch on All repositories |
| A widget counts the whole project despite picking repos | Repositories scope code, not work items | Set an Area path under Board Content |
| Cycle time looks wrong and far too slow | Out-of-scope repositories are in the median | Narrow Repositories for code metrics on this board's source |
| The area path list is empty | No work item has been synced for this project yet | Sync first — the list is built from your own data, with counts |
| Work items sync but 401 shows on the code side | Token lacks the Code (Read) scope even though Work Items (Read) works | Reissue the PAT with all three read scopes |
Related
- Mapping source statuses — ADO's
statevalues mapped onto board statuses. - When your data refreshes — scheduled and manual sync.
- When a connection breaks — health checks and reconnecting.
- Filters and date ranges — how source scope reaches an Intelligence widget.
- Team Focus — the view that reads ADO work items and transitions most heavily.
Last updated