> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/issue-trackers/azure-boards.md).

# Azure Boards

{% hint style="warning" %}
The Azure Boards integration is currently in **alpha**. Reach out to us at **<hello@swarmia.com>** if you'd like to try it or have feedback.
{% endhint %}

Swarmia connects to Azure DevOps (Azure Boards) using a Personal Access Token (PAT). Once connected, Swarmia syncs your projects and work items so you can see them alongside your commits and pull requests.

{% hint style="info" %}
The Azure Boards integration currently syncs once every 24 hours and does not include sprints, work item hierarchy, or story points.
{% endhint %}

## Prerequisites

Before you start, check the following:

* **Account access** — a PAT only ever has the same access as the person who created it, so use an account that can see the organization and projects you want to sync.
* **PAT creation policy** — if your organization has *Restrict personal access token creation* enabled (Organization settings → Policies), your account must be on the allowlist, or you can't create the token.
* **Lifespan** — Azure DevOps caps a PAT at one year. A tenant admin may enforce a shorter maximum via *Enforce maximum personal access token lifespan*.

{% hint style="info" %}
**Recommended: use a service account**

Removing the user who created the PAT also invalidates the token (within \~1 hour in Azure DevOps Services). Use a shared service or bot account rather than a personal one so syncing survives staff changes.
{% endhint %}

## Step 1: Create the PAT in Azure DevOps

1. Go to [aex.dev.azure.com](https://aex.dev.azure.com/) and select the Azure DevOps organization you'd like to connect with Swarmia.
2. In the top-right corner, click the **User settings** icon and choose **Personal Access Tokens**. This opens the PAT list page.<br>

   <figure><img src="/files/dkq7HdqggSCu0WmdY26G" alt=""><figcaption></figcaption></figure>
3. Click **+ New token**. A popup appears for you to create the PAT.
4. Fill in the token name, choose the Azure DevOps organization you want to grant Swarmia access to, and set an expiration date.
5. Click **Show all scopes** to reveal the full list, then grant exactly these three read scopes:<br>

   * **Work Items (Read)**
   * **Project and Team (Read)**
   * **Identity (Read)**

   <figure><img src="/files/iqfEwWOUBfFicPiDYfH6" alt=""><figcaption></figcaption></figure>
6. Once created, copy the PAT and close the modal. Wait until the token name shows up in the list, then continue to the Swarmia settings page.<br>

   <figure><img src="/files/GrrJ9TMznWVY50Y1MOJ9" alt=""><figcaption></figcaption></figure>

## Step 2: Connect Swarmia with the PAT

1. Go to [Azure DevOps settings in Swarmia](https://app.swarmia.com/settings/issue-trackers), click **Connect**, then choose **Connect Azure DevOps**.<br>

   <figure><img src="/files/VVslcp2fKmIZRYYroHzF" alt=""><figcaption></figcaption></figure>
2. Fill in two things:

   <figure><img src="/files/o76LPpJUzpGopZVvif16" alt=""><figcaption></figcaption></figure>

   * **Azure DevOps organization** — for example, if your URL is `dev.azure.com/swarmia-development`, enter `swarmia-development`.
   * **PAT** — paste your Azure DevOps PAT into the second field.<br>
3. Click **Connect**.

<figure><img src="/files/ZdlFLIz9ziTvQn6dxvAt" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Azure DevOps now appears in your issue tracker settings and begins syncing the projects and all work items.
{% endhint %}

## Token expiry and rotation

{% hint style="warning" %}
When the PAT expires or is revoked, syncing stops immediately. Reconnect with a new token to resume.
{% endhint %}

Set a reminder to rotate the token before its expiry date to avoid a gap in syncing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.swarmia.com/settings/integrations/issue-trackers/azure-boards.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.