> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps

> Connect Gradial to Azure DevOps to automatically ingest work items and sync results back to your boards.

**What you can do:**

* Ingest Azure DevOps work items into Gradial with their fields, comments and attachments
* Trigger Gradial execution when work items match your route criteria
* Write results — previews, links, status — back to the originating work item
* Target work items precisely, using structured filters or your own WIQL query

<Note>
  Gradial syncs Azure DevOps on a schedule. New and updated work items are picked up on the next sync cycle rather than instantly.
</Note>

***

## Why route web work through Azure DevOps

Marketing content requests often arrive in Azure DevOps because that is where the engineering organization already works — a shared board, an existing intake form, a sprint everyone can see. The request lands as a work item, joins a backlog of genuine engineering work, and then waits, because "update the pricing page headline" and "fix the checkout race condition" are competing for the same team's attention.

That's the wrong queue for the work, but the right place for the request. Connecting Azure DevOps keeps intake and reporting exactly where they are, and moves execution out of the engineering backlog.

***

## Prerequisites

### Create a dedicated Gradial service user

Create a service account in Azure DevOps for Gradial rather than using a person's credentials. This keeps the audit trail legible — every comment and update Gradial writes back is clearly attributable — and means the connection survives people changing roles.

The service user needs:

* **Access to each project** Gradial will read work items from
* **Permission to read work items** in those projects
* **Permission to add comments and attachments**, and to edit the fields you want Gradial to update on completion

Grant only the projects Gradial should see. Project membership is the outer boundary on what any route can reach.

***

## Connect Azure DevOps to Gradial

Go to **Settings → Integrations**, find **Azure DevOps** under Ticketing & work management, and select **Connect**. The wizard covers **Connection**, **Routing**, and **Route Summary**.

### Step 1 — Create a personal access token

1. Sign in to Azure DevOps **as the service user**
2. Open **User settings → Personal access tokens**
3. Select **New Token**
4. Scope it to the organization Gradial will work in, set an expiry, and grant **Work Items (Read, write & manage)**
5. Copy the token — Azure DevOps shows it only once

<Warning>
  Personal access tokens expire. Note the expiry date when you create the token and set a reminder, because an expired token stops ingestion silently — routes simply return nothing new.
</Warning>

### Step 2 — Configure the connection

1. Enter an **Integration Name** to identify this connection
2. Enter your **Organization URL** — `https://dev.azure.com/{your-organization}`
3. Paste the service user's **personal access token**
4. Select **Validate Connection**
5. Once validated, continue to routing

<Note>
  Once saved, credentials are stored securely and cannot be viewed again. To rotate the token, update the integration with the new value.
</Note>

### Step 3 — Configure routing

On the **Routing** step, add a route for each set of work items Gradial should ingest. Routes can be toggled on and off independently.

| Field                    | Required | Description                                                                                                      |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| **Route Name**           | Required | A name to identify this route                                                                                    |
| **Description**          | Optional | Notes on what the route is for                                                                                   |
| **Project**              | Required | The Azure DevOps project to read from                                                                            |
| **Work item types**      | Optional | Limit to specific types — for example User Story, Task, Bug, Feature, Epic, Issue                                |
| **Area path**            | Optional | Restrict to an area path, which is usually the cleanest way to separate marketing requests from engineering work |
| **Iteration path**       | Optional | Restrict to a sprint or release                                                                                  |
| **State**                | Optional | Only ingest items in given states — for example New, or Approved                                                 |
| **Assigned to**          | Optional | Only ingest items assigned to a given user, commonly the Gradial service user itself                             |
| **Tags**                 | Optional | Only ingest items carrying given tags                                                                            |
| **Custom field filters** | Optional | Filter on any other field, including your organization's custom fields                                           |

**Gradial destination:**

| Field           | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| **Workspace**   | The Gradial workspace where ingested work items appear as Tasks |
| **Environment** | The Gradial environment to execute in                           |

<Tip>
  The most reliable intake pattern is **assignment**: have requesters assign the work item to the Gradial service user, and route on `Assigned to`. It makes intake an explicit act rather than a filter that might match more than anyone intended — and it gives requesters an obvious way to opt a single item out.
</Tip>

#### Advanced: routing with WIQL

Where structured filters can't express the selection you need, a route can carry a raw **WIQL** query instead. This is worth reaching for when your intake depends on a combination of custom fields, or on relationships between work items.

```sql theme={null}
SELECT [System.Id]
FROM WorkItems
WHERE [System.TeamProject] = 'Marketing'
  AND [System.WorkItemType] = 'Task'
  AND [System.AreaPath] UNDER 'Marketing\Web Requests'
  AND [System.State] = 'Approved'
  AND [System.Tags] CONTAINS 'gradial'
```

Test the query in Azure DevOps first and confirm the result set is what you expect. A WIQL route ingests everything the query returns.

Select **Next** to review the **Route Summary**, and confirm each route pulls in what you expect before finishing.

For ingestion modes and best practices, see [Routing Tickets →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)

***

## How work item execution works

1. A work item matching a route's criteria is discovered on the next scheduled sync
2. Gradial ingests it as a Task, including its title, description, field values, comments and attachments
3. Gradial executes the requested work
4. Results — previews, links and status — are written back to the originating work item as the service user
5. Gradial keeps watching the work item for changes that should trigger follow-up work

***

## Troubleshooting

| Issue                                    | Likely cause                                                                     | Fix                                                                                                             |
| ---------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| No work items ingested                   | The token expired, or the route's filters match nothing                          | Re-validate the connection, then run the route's filters as a query in Azure DevOps to confirm the result set   |
| Some work items ingested, others skipped | The service user lacks access to that project or area path                       | Check project membership and area-path permissions for the service user                                         |
| Results not written back                 | The service user cannot comment or edit fields on that project                   | Grant comment and edit permission, then re-run the Task                                                         |
| Attachments missing                      | The attachment is on a linked item rather than the ingested one                  | Attach source material to the work item the route targets                                                       |
| Far more items ingested than expected    | A route filter is broader than intended — commonly an area path with descendants | Narrow the filter, or switch to assignment-based routing                                                        |
| Connection rejected on save              | The organization URL is wrong, or the token lacks Work Items scope               | Confirm the URL is `https://dev.azure.com/{organization}` and regenerate with Work Items (Read, write & manage) |

***

## Who this is for

| Role                        | What this unlocks                                                                        |
| :-------------------------- | :--------------------------------------------------------------------------------------- |
| **Marketing Ops**           | Content requests leaving the engineering backlog without changing where people file them |
| **Web Producer**            | Requests arriving with their context — fields, comments, attachments — already attached  |
| **Engineering Manager**     | Marketing content work off your team's board                                             |
| **Requester / Stakeholder** | Filing in the tool you already use, and getting the result back on the same work item    |
| **Program Manager**         | Status visible in Azure DevOps, so existing reporting keeps working                      |

***

## Availability

**Access:** Must be enabled for your organization. Contact your Gradial team to get access.