Connect Azure Boards: step-by-step guide
Files one work item per failing test, comments on it when the test fails again, and sets it to a done state when the test passes clean. The same token also publishes test results and queues pipelines. This guide takes you from nothing to a verified connection, and lists the errors you can meet with their cause and fix.
Last updated:
Keep your credentials private. Never paste a token, key, password or webhook URL into a chat. Type it only in Studio → Settings → Integrations, where it is saved in your workspace's .env file and shown as dots. The same goes for an AI assistant: it can walk you through this guide, but it never needs your token.
What you need
- An Azure DevOps Services organization: https://dev.azure.com/<organization> or https://<organization>.visualstudio.com (Azure DevOps Server on your own machines is not supported).
- The name of the project that will receive the work items.
- A personal access token (PAT) with Work Items → Read & write, and Build → Read & execute if you also use Run in CI.
- To know your project's process, because it decides the work item type: Basic has Issue, Epic and Task (no Bug); Agile, Scrum and CMMI have Bug.
Get the credentials
- Open dev.azure.com, then User settings → Personal access tokens → New Token.
- Pick your organization, set an expiry, and under Scopes choose Custom defined.
- Tick Work Items → Read & write (add Build → Read & execute for Run in CI), create the token and copy it now. It is shown once.
- Keep it in your clipboard. Do not paste it anywhere except the Studio (next step).
Connect it in the Studio
- In the Studio, open Settings → Integrations → Connect Azure DevOps.
- Paste any link from Azure DevOps (a board, a work item or the project page) and press Check connection. The Studio keeps the organization and the project.
- When it asks, enter the PAT and press Save & check. Pick the project in "Work items go to".
- If the check says the project has no work item type named Bug, set
AZURE_BOARDS_WORK_ITEM_TYPEto one of the types it lists (in a Basic project, Issue), andAZURE_BOARDS_DONE_STATEto a state that process has (Basic: Done). - Turn on
AZURE_BOARDS_ENABLED.
Check that it works
- Check connection shows "The token sees N projects" and "<project> takes <type> work items". The check only reads; it never files a work item.
- Open Settings → Integrations → Tickets and press Create test ticket. It files one work item tagged nexus-test with a screenshot attached.
- Open it in Azure Boards, confirm the tag and the attachment, and delete it when you are done.
Common errors
| What you see | Cause | Fix |
|---|---|---|
| "Azure DevOps refused the token" (HTTP 203 or 401) | The PAT is wrong, expired, revoked, copied incompletely, or was created in a different organization. | Create a new PAT in the same organization as AZURE_DEVOPS_ORG_URL with Work Items → Read & write, and save it again. |
| HTTP 403 | The PAT is valid but lacks a scope, or your user lacks permission in that project. | Edit the PAT's scopes (Work Items → Read & write; Build → Read & execute for Run in CI), or ask the project admin for access. |
| HTTP 404 | The organization or the project name does not exist, or the project was renamed. | Paste a link from the right project and choose it from the list. |
| VS402323 "Work item type Bug does not exist" | The project's process has no work item type with that name. A Basic project has Issue, Epic and Task, not Bug. | Set AZURE_BOARDS_WORK_ITEM_TYPE to a type the check lists (Basic: Issue) and AZURE_BOARDS_DONE_STATE to one of its states (Basic: Done), then Check connection again. |
| "<project> has no work item type named …" | The same cause as VS402323, caught by Check connection before anything is filed. | Set AZURE_BOARDS_WORK_ITEM_TYPE to one of the types listed in that message, or choose another project. |
| "That is not an Azure DevOps link" | The address is not on dev.azure.com/<organization> or <organization>.visualstudio.com, or it starts with http://. | Copy the address bar from Azure DevOps Services. Azure DevOps Server is not supported. |
| "could not reach Azure DevOps (…)" or "did not answer within 20 s" | This PC cannot reach Azure DevOps: a VPN or proxy, or no network. | Open dev.azure.com in a browser on the same PC, then retry the check. |
| A passing test does not set the done state | The process refuses AZURE_BOARDS_DONE_STATE for that type, so the item only gets the comment. | Set AZURE_BOARDS_DONE_STATE to a state of that type (Basic: Done; Agile bug: Resolved). |
| Everything checks out, but no work item appears | AZURE_BOARDS_ENABLED is false; or the verdict was FLAKY or an environment verdict; or it was a sandbox run; or the test already has an open work item (a repeat failure comments instead). | Turn on AZURE_BOARDS_ENABLED and use Create test ticket to prove the connection. |
Settings keys
| Key | What it does | Valid value | How to check it |
|---|---|---|---|
AZURE_BOARDS_ENABLED | Create Azure work items for failures | true or false | Turn on after Check connection passes, then run Create test ticket. |
AZURE_DEVOPS_ORG_URL | Azure DevOps organization address | https://dev.azure.com/<organization> or https://<organization>.visualstudio.com | Check connection shows the organization; a pasted link fills it. |
AZURE_DEVOPS_PROJECT | Azure DevOps project name | The project name, exactly as Azure DevOps shows it | Check connection lists the projects the token sees. |
AZURE_DEVOPS_PAT | Azure DevOps access token (secret, saved only on this computer) | One line, no quotes, no spaces | Check connection: "refused the token" means it is wrong, expired or from another organization. |
AZURE_BOARDS_WORK_ITEM_TYPE | Azure ticket type for failures | A type the project's process has: Bug (Agile, Scrum, CMMI) or Issue (Basic) | Check connection says "<project> takes <type> work items" or lists the types the project has. |
AZURE_BOARDS_DONE_STATE | Azure state when test passes | A state of that work item type: Resolved (Agile bug), Done (Basic issue) | A clean pass moves the item; if the process refuses the state it only gets a comment. |
AZURE_PIPELINE_ID | Azure pipeline to run in CI | The numeric id of an Azure pipeline (only for Run in CI) | nexus ci-remote --provider=azure queues that pipeline; needs Build → Read & execute. |
More: all integrations, the Settings guide, troubleshooting. Other guides: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
Still stuck? Write to [email protected] with the exact error line the Studio shows. Do not include a token.