Skip to main content
Version: v2 (current)

Azure Boards Integration with PanDev Metrics

import IdealImage from "@theme/IdealImage"; import Head from "@docusaurus/Head";

TL;DR. This guide enables Azure Boards as a task tracker in PanDev Metrics in about 10 minutes. Azure Boards lives inside the same Azure DevOps organization as Azure Repos and Pipelines — you reuse the same Personal Access Token (with Work Items: Read), open Settings → Integrations → Azure DevOps, and confirm that Boards work items appear in your dashboards. Audience: admin.

:::tip Single integration screen Azure Boards is part of the broader Azure DevOps integration. If you already connected Azure Repos or Pipelines, Azure Boards is enabled by the same PAT — you just need the Work Items: Read scope on it. Jump to Step 3 if Azure DevOps is already connected. :::

Before you begin​

  • PanDev Metrics is up and running (Cloud workspace or on-prem instance)
  • Admin access to your PanDev Metrics tenant
  • An Azure DevOps user (service account preferred) with Project Administrator access on the Boards projects to analyse
  • For on-prem PanDev Metrics: outbound 443 to dev.azure.com or to your Azure DevOps Server host
  • For Azure DevOps to reach an on-prem PanDev Metrics deployment: the PanDev Metrics host must be reachable from Azure DevOps at the public webhook URL

Step 1 — Create or update the Azure DevOps PAT​

Boards uses the same PAT as Repos and Pipelines. Make sure these scopes are enabled:

ScopeAccessWhy
Work ItemsReadList, read, and webhook work items
CodeReadLink work items to commits and PRs (if Repos is also tracked)
Project and TeamReadList projects visible to the PAT

If you already issued a PAT for Azure DevOps, check whether Work Items: Read is enabled. If not, regenerate the PAT with the additional scope and update it in PanDev Metrics.

:::warning Save the PAT immediately Azure DevOps shows a PAT exactly once. Store it in a secrets manager. :::

Step 2 — Open the Azure DevOps integration screen​

Sign in to PanDev Metrics as a workspace admin and open Settings → Integrations → Azure DevOps. There is no separate Azure Boards card — Boards is part of the Azure DevOps integration.

If you have not yet connected Azure DevOps, fill in the Organization URL and Personal access token fields and select Check connection, then Activate — see the full guide on Azure DevOps integration.

Step 3 — Enable Boards sync in PanDev Metrics​

Once Azure DevOps is connected:

  1. Open Settings → Integrations → Azure DevOps → Advanced.
  2. Toggle Sync Azure Boards work items.
  3. Pick the Boards projects to sync (this can be a subset of the projects you sync for Repos).
  4. Save.

PanDev Metrics starts a one-time backfill of the last 90 days of work items, state transitions, and worklog entries.

Step 4 — Verify service hooks for Boards​

PanDev Metrics registers Azure DevOps service hooks for Boards automatically. To confirm, open Project settings → Service hooks on Azure DevOps. You should see hooks for Work item created, Work item updated, Work item commented on, and Work item deleted, all pointing at /v1/azure/webhook/boards on the PanDev Metrics host.

Recent deliveries should return HTTP 200 within seconds.

Verify​

Open Settings → Integrations → Azure DevOps in PanDev Metrics. You should see:

  • A green Connected badge
  • The count of selected Boards projects under Azure Boards
  • The timestamp of the Last sync (no older than 30 minutes once backfill completes)

Then open a dashboard with a task-tracker widget and confirm that:

  • Recent Boards work items appear next to commits
  • Item states match Azure Boards (New / Active / Resolved / Closed and your custom states)
  • Items are linked to commits and PRs via the standard #1234 mention in commit messages and PR titles

To force a fresh poll, select Sync now on the integration tile.

What gets synced​

PanDev Metrics ingests a focused slice of Azure Boards data.

SourceDirectionWhat is stored
Work item fieldsPull + webhookID, title, work item type (User Story / Bug / Task / Epic / etc.), state, area path, iteration path, assignee, tags, priority, story points
State transitionsWebhook /v1/azure/webhook/boardsFrom, to, timestamp, actor — used for cycle time and time-in-state
Iterations (Sprints)PullIteration id, name, start / end dates, area path
UsersPullAzure DevOps user id, display name, email — matched against PanDev Metrics employees

Attachments and comment bodies are not stored by default.

Troubleshooting​

Service hooks register but Boards events do not appear

The PAT lacks Work Items: Read. Re-create the PAT with that scope and update it in Settings → Integrations → Azure DevOps → Advanced → Update token. Boards events resume within minutes.

Backfill completes but state transitions show "Unknown"

The service account lacks View work items in this node permission on some area paths. Open Project settings → Permissions in Azure DevOps and grant the user (or its group) read access on the affected area paths, then Sync now.

Custom work item types are not synced

PanDev Metrics syncs every standard and custom work item type by default. If a custom type is missing, confirm it is enabled in the project's process customization and that the service user has read access on it.

Work items are not linked to commits / PRs

Azure DevOps links code to Boards by the #1234 mention in commit messages and PR descriptions. The commit author must be the same person as (or be linked to) an Azure DevOps user. If links are missing, ensure your team uses #<work-item-id> in commit messages and PRs.

Azure DevOps Server returns 404 on the Boards API

For Server, the Organization URL must include the collection: https://azuredevops.acme.example/DefaultCollection. Without the collection segment, the REST API returns 404. Update the URL in Settings → Integrations → Azure DevOps.

FAQ​

Do I need a separate token or screen for Azure Boards?​

No. Azure Boards is part of the Azure DevOps integration — one PAT and one configuration screen cover Repos, Pipelines, and Boards. Just make sure Work Items: Read is on the PAT.

What's the minimum PAT scope set for Boards-only use?​

Work Items: Read plus Project and Team: Read. If you only want Boards (not Repos or Pipelines), enable only those two scopes. PanDev Metrics still requires Project Administrator in Azure DevOps to register service hooks.

Does PanDev Metrics work with Azure DevOps Server?​

Yes. The same PAT-based flow works on Azure DevOps Server. The Organization URL must include the collection (for example https://azuredevops.acme.example/DefaultCollection). On-prem PanDev Metrics needs network reachability to the Server host on port 443.

How often is Boards data refreshed?​

Service hooks deliver work item events in real time — usually within seconds. PanDev Metrics also runs a reconciliation poll every 15 minutes to catch any missed deliveries.

Yes. Add #<work-item-id> (Azure DevOps's standard) to commit messages and PR titles. Azure DevOps creates the link inside its own UI, and PanDev Metrics inherits the same link relation.

Will PanDev Metrics write to Azure Boards?​

Only worklog entries when automatic worklog mode is enabled — PanDev pushes IDE-based time to the Completed Work field on the linked work item. Read-only mode performs no writes.

Can I sync only some Boards projects?​

Yes. In Settings → Integrations → Azure DevOps → Advanced, select only the Boards projects you want. The selection is independent from the Repos / Pipelines project list.

How long does the initial backfill take?​

PanDev Metrics backfills the last 90 days of work items when you enable Boards sync. For 5k items this typically takes 5-15 minutes; very large projects (50k+ items) can take an hour or more.

Next steps​