> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-azure-devops-integration.md).

# How to set up the Azure DevOps integration

An Admin connects Azure DevOps once at the account level. After that, anyone in your workspace can search work items and link them to planning cards on any journey map.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Azure DevOps integration](#set-up-the-azure-devops-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Azure DevOps in planning cards](#use-azure-devops-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Azure DevOps integration

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* An Azure DevOps organization and project, with permission to create a personal access token.
  {% endhint %}

Azure DevOps uses a single authentication method: a personal access token, plus your organization and project names. The token carries your own Azure DevOps permissions, so it can only reach work items you can see.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FJf2veCfk8yM8aPMPjt6P%2Fconfigure-azure-devops.mp4?alt=media&token=1b4e543b-2d85-49bf-b483-f2afb9179053>" %}

{% stepper %}
{% step %}
**Open the Azure DevOps integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Azure DevOps**. The **Configure Azure DevOps** page opens with empty fields for your organization, project, and personal access token.

<figure><img src="/files/GIDic6tY0ojtehgLTNyK" alt="The Configure Azure DevOps page in Smaply. An Azure DevOps API Configuration form shows three empty required fields labelled Azure DevOps Organization, Azure DevOps Project, and Personal Access Token, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Azure DevOps, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a personal access token in Azure DevOps**

In a new tab, sign in to your organization at [dev.azure.com/{your-organization}](https://dev.azure.com). Open **User settings** (the gear icon, top right next to your profile avatar) and select **Personal access tokens**, then click **+ New Token**.

In the **Create a new personal access token** dialog, enter a **Name**, pick the **Organization** the token works against, and set an **Expiration** date. Under **Scopes**, choose **Custom defined** and select **Work Items**. **Read** is enough to import items into Smaply. Click **Create**.

<figure><img src="/files/ftHSZMRR6MTT9QkHWCND" alt="The Create a new personal access token dialog in Azure DevOps, with fields for Name, Organization, Expiration (UTC) set to a custom date, and a Scopes choice between Full access and Custom defined."><figcaption><p>Create a new personal access token</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Azure DevOps shows the token only once. Copy it and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Azure DevOps** page, type your organization name into **Azure DevOps Organization**, your project name into **Azure DevOps Project**, and paste the token into the **Personal Access Token** field. Use the organization name (the `{organization}` part of `dev.azure.com/{organization}`), not the full URL. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved details with a green confirmation. Azure DevOps is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Azure DevOps** page from **Account Settings > Integrations**. A connected integration shows your saved organization and project with a masked token, and a green **Connection setup** message confirming you're connected to Azure DevOps, alongside **Edit Configuration** and **Delete Configuration** actions.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Azure DevOps in planning cards

Once Azure DevOps is connected, anyone in your workspace can add a planning card to a journey map, search your work items, and link the one it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards.md).

***

#### Troubleshooting

The **Configure Azure DevOps** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The organization name, project name, or token is wrong, or they don't belong together. Reopen **Configure Azure DevOps**, click **Edit Configuration**, and check each value:

* **Azure DevOps Organization** is the organization name on its own (the `{organization}` segment of `dev.azure.com/{organization}`), not the full URL.
* **Azure DevOps Project** matches a project you can open in that organization.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Azure DevOps and re-enter all three values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Azure DevOps returns nothing for your search. Check that the search text matches a work item you can open in Azure DevOps, and that it lives in the project you connected. The connection runs with the token owner's permissions, so work items they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

Personal access tokens expire on the date set when they were created, and a working connection breaks silently once the token lapses. Tokens that were revoked in Azure DevOps, or that belonged to a user who lost access to the project, fail the same way.

Create a new token from **User settings > Personal access tokens** in Azure DevOps, then reopen **Configure Azure DevOps**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>You can't create a token or the Work Items scope is greyed out</strong> - Permission issue</summary>

Configuring the integration in Smaply needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

On the Azure DevOps side, an organization admin can restrict who creates tokens and which scopes they can select. If you can't create a token or can't pick the **Work Items** scope, ask your Azure DevOps admin to allow it for your account.

</details>

For questions about how the connection behaves across your account, such as disconnecting Azure DevOps or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


---

# 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://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-azure-devops-integration.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.