> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spurtest.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Spur is an AI-powered QA engineer that lets teams create and run automated end-to-end tests for web and mobile apps using natural language.
> When answering questions about Spur, cite the relevant page from docs.spurtest.com.
# Azure DevOps Work Items
> Connect Azure DevOps to file work items from test results, set project and field defaults, and read work items in Spur AI.
## Overview
Connect Azure DevOps to turn test results into work items. Spur fills in the failure reason, the steps to reproduce, and a link back to the run, then keeps the work item linked to the test.
Once connected, you can:
* File a work item from any test result, or while working through a test plan run.
* Have Spur file one for you automatically every time a test finishes.
* Reference a work item in Spur AI, so it can read the ticket before writing tests.
Only an admin can connect or configure Azure DevOps. Once it is set up, anyone on your team can file work items. See [User Roles](/additional-resources/user-roles).
## Before you start
You need:
* An Azure DevOps organization on `dev.azure.com`.
* A personal access token. Spur files every work item as the person who created the token, so pick an account your team is happy to see as the author.
* That person added to the **Project Administrators** group on each project you want Spur to file into.
## Grant project access
Add the person who will create the token to the **Project Administrators** group on every project Spur files into. That membership carries the **Create tag definition** permission. Without it, you can still pick tags that already exist, but adding a new tag makes Azure DevOps reject the whole work item.
Go to the project you want Spur to file into, then click **Project settings** in the bottom left corner of the page.
Click **Permissions** in the Project settings menu, then click the **Project Administrators** group in the list.
Open the **Members** tab, click **Add**, and add them. Repeat this for every project Spur files into.
## Create a personal access token
In Azure DevOps, open your user settings and create a token for the organization you want to connect. Set an expiration date — Azure DevOps allows a maximum of one year, and your organization can set a policy capping it lower. Then choose **Custom defined**, click **Show all scopes**, and grant these three:
| Scope | Access | Why Spur needs it |
| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| Work Items | Read & write | Creates work items from test results, and reads linked work items so their status stays current in Spur. |
| Project and Team | Read | Lists your projects and work item types, so the filing form matches your organization. |
| Graph | Read | Looks up assignable users, so you can pick an assignee. |
Grant nothing beyond these three. Spur writes to Azure DevOps only when a work item is filed — it never changes your process templates, work item types, or field definitions.
Every personal access token expires, and Azure DevOps caps the lifetime at one year — so this integration needs a new token at least annually. When the token expires, filing stops until an admin pastes a replacement. Set a reminder ahead of the date you chose.
## Connect Azure DevOps
Click the user profile button in the top right from any page, then click **Integrations**. Find the **Azure DevOps** card and click **Connect**.
In **Organization**, enter your organization name or its full `dev.azure.com` URL — for example `spurtestorg` or `https://dev.azure.com/spurtestorg`.
Paste the personal access token into **Personal access token**, then click **Connect**. Spur checks the token against your organization before saving it, so a token with the wrong scopes fails here rather than the first time someone files a work item.
Once you have entered your organization, the dialog also shows a **Create a token in Azure DevOps** link that opens the token page for it.
## Set your defaults
Once connected, click **Settings** on the Azure DevOps card to choose what every new work item starts with.
### Default project and work item type
Pick the **Default project** your team files bugs into, then the **Default work item type** to file — `Issue` and `Bug` are the common choices. Both start at **No default**, which means whoever files a work item picks them each time.
Pick the project first. The work item types on offer come from that project, and so do the field defaults below.
### Field defaults
**Field defaults** are the values every new work item starts with. Whoever files the work item can change them before submitting it.
Which fields appear here comes from your Azure DevOps process, so your list will not match the screenshot above. A star marks a field that Azure DevOps requires before it will accept a work item. You can leave a starred field blank — Spur asks for it in the filing form instead.
### Automatic filing
Turn on **Automatic filing** to have Spur create a work item every time a test finishes, without anyone opening the filing form. Choose **When a test fails**, **When a test passes**, or both.
Spur files one work item per test result, and does not file a second one if that result is processed again.
Automatic filing has no one to prompt for a missing value, so every starred field needs a default. When one is missing, the settings dialog lists the field by name — for example, `Automatic filing will skip work items until you set a default for: State.` Until you fill that field in, Spur files nothing automatically.
Each work item links back to its test result through a shareable link, so anyone with that link can view the run without signing in to Spur. See [Shareable Links](/analysing-tests/shareable-links).
Click **Save Changes** to apply your settings.
## File a work item from a test result
On a test result, click **Share**, then click **Azure DevOps** under **Create a Ticket**.
Spur writes the title and the description from the test result:
* **Title** — the name of the test.
* **Description** — a link back to the run, the failure reason, the step the test failed on, the steps to reproduce, and the suite, test, run time, and test type.
Edit either one before filing.
Under **Details**, pick the **Project** and **Work item type**, then set the **Assignee**. Every field your process requires appears here too, marked with a star and pre-filled with the default you saved. Anything your process treats as optional is grouped under **Optional Fields**.
Where Azure DevOps has a description for a field, Spur shows it underneath — so **State**, for example, explains what each value means in your process.
Click **Create Work Item**. Spur files it, links it to the test, and shows you the new work item ID.
With more than one issue tracker connected, the form header carries **Switch to Jira** and **Switch to Linear** buttons. Switching keeps the title and description you have already edited.
## File a work item from Test Plan Review
You can file work items without leaving [Test Plan Review](/analysing-tests/test-plan-review). Mark a result as a bug, then choose **Create Azure DevOps Work Item**. Spur opens the filing form described above, filled in from that result.
To cover several failures with one work item, select those results first. Spur files a single work item and links it to every test you selected.
## Read work items in Spur AI
With Azure DevOps connected, [Spur AI](/analysing-tests/spur-ai-chat) can read your work items. Paste a work item URL, or give it the ID — "write tests for work item 412" is enough, and you do not have to say which tracker it lives in.
Spur AI reads the title, description, state, assignee, priority, tags, parent and child work items, comments, and any images in the description. Use it to write tests from a work item, or to check whether a test you already have still covers what the work item asks for.
## View and sync linked work items
A work item you have filed appears in the test's share panel with its ID and current state. Click **Sync** to pull the latest title, state, and assignee from Azure DevOps — useful once the work item has been reassigned, triaged, or closed.
## Troubleshooting
### Replace a token, or move to another organization
Open **Settings** on the Azure DevOps card, paste a new token into **Personal access token**, and click **Save Changes**. Your default project, work item type, and field defaults are kept.
To connect a different organization, change **Organization** and paste a token for that organization in the same save. Your saved defaults are cleared, because projects and fields do not carry from one organization to another.
### Error messages
| What you see | What to do |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Azure DevOps rejected the PAT | The token has expired, was revoked, or belongs to a different organization. Paste a replacement and save. |
| The PAT cannot access any Azure DevOps projects | The token is missing the **Project and Team: Read** scope, or the person who created it has no access to any project in the organization. |
| The PAT cannot access any Azure DevOps work item types | The person who created the token cannot read the project you picked. Check their project membership. |
| Azure DevOps denied this request, mentioning `TF401289` | The person who created the token is missing the **Create tag definition** permission. Add them to **Project Administrators**, or use only tags that already exist. |
| Azure DevOps could not find the selected organization, project, or work item type | The project or work item type was renamed or deleted in Azure DevOps. Pick a current one in the settings dialog and save. |
| Azure DevOps rate limit reached | Azure DevOps is throttling your organization. Wait a moment, then try again. |
| This process requires unsupported fields | Your process requires a field of a type Spur cannot fill. [Contact the Spur team](/additional-resources/contact-us) with the field name. |
| Automatic filing will skip work items until you set a default | A required field has no default. Set one under **Field defaults**, or turn automatic filing off. |
| Created the work item, but Spur could not link it | The work item exists in Azure DevOps and only the link to the test failed. Click **Retry Link** — Spur links the work item it already created rather than filing a duplicate. |