---
url: https://clusto.app/docs/azure-devops.md
description: >-
  The Azure DevOps view - every Git repository, active pull request, pipeline
  build and assigned work item (with sprint filtering) of an Azure DevOps
  account in one place, with vote, complete, re-run and a one-tap hand-off to an
  agent in your own checkout, PAT or az CLI sign-in on a host node, Azure DevOps
  Server support, notifications and polling limits.
---

# Azure DevOps

The **Azure DevOps** view shows every Git repository your Azure DevOps account
can reach, every active pull request, the latest pipeline builds and the work
items assigned to you, on desktop and on your phone. You can read a pull request
(description, policies, reviewers, discussion threads, changed files and diff),
vote on it, comment, reply to and resolve threads, complete it, set it to
complete automatically, abandon it and re-queue its failed checks. You can retry
or re-run a build, cancel a running one and read its log. You can comment on a
work item, move it to another state and assign it to yourself, and follow the
running sprints of your projects. The agent hand-off
is the part a browser tab cannot do: Clusto opens a chat in your local project's
checkout with the item as its brief. It never creates a worktree.

Open it from **Azure DevOps** in the left nav (route `/azure-devops`). The entry
is hidden in the Simple navigation profile (see [Appearance](/appearance)), and
it shows a badge with the number of unread pull requests waiting for your vote
plus unread work items assigned to you (see [Read and unread](#read-and-unread)).
It is free on every plan.

::: tip Early access
The Azure DevOps view ships behind the `azure_devops.view` release flag, which is
off by default. Turn it on in **Settings -> Labs** (the **Early access** switch,
or the flag itself). The flag is cluster-shared, so one change covers every device
connected to the cluster. See [Feature Flags](/feature-flags).
:::

## Set up

Everything that talks to Azure DevOps runs on one **host node** that holds your
credential, so the view works the same from a phone as from a desktop, and the
credential never leaves that node. Configure it once in **Settings -> Azure
DevOps**; the account list is shared across the cluster.

1. Open **Settings -> Azure DevOps** and press **Add Azure DevOps account**.
2. Fill in the fields:

| Field | Meaning |
|---|---|
| Name | A label shown in the app. |
| Host node | The node that polls Azure DevOps and holds the credential (see Security). |
| Server URL | `https://dev.azure.com` for Azure DevOps Services (the default). For Azure DevOps Server, the server URL, for example `https://ado.example.com/tfs`. |
| Organizations (Server: Collections) | The organizations to poll, separated by commas, spaces or new lines. On Services, leave it empty to poll every organization you belong to. Azure DevOps Server needs at least one collection. |
| Poll interval | Seconds between polls. Default 60, allowed 15 to 3600. |
| Default merge type | Preselected in the complete dialog: squash (default), merge (no fast forward), rebase and fast-forward, or semi-linear merge. |
| Delete the source branch when completing, by default | Preselected in the complete dialog. On by default. |
| Personal access token | Paste a PAT. It is saved to the host node only. |

3. Either paste a personal access token and press **Save**, or press **Use az CLI
   login** (see below). **Create token in Azure DevOps**, under the token field,
   opens the personal access token page of the first organization (typed, or
   found by the last poll; on Azure DevOps Server, of the server). Azure DevOps
   cannot prefill scopes, so pick the ones listed under Security.

Clusto asks Azure DevOps who the credential belongs to when you save it and shows
**authenticates as `<name>`**. That identity decides what "mine" means in the
view: the **Needs my vote** and **Mine** buckets, the **Mine** filter on
Pipelines, **Assign me**, and the notifications all key off it.

If you add more than one account, the view shows an account picker.

### Factory accounts

The [software factory](/factory) can open pull requests through an Azure DevOps
account whose **Purpose** is **Factory** (the Purpose field in the account
form, shown while the factory is on in Labs). Repositories are written
`organization/project/repository` and must belong to one of the account's
**Organizations**; a factory account with an empty list is refused, and so is
any repository outside it. The factory finds its pull request by source branch,
labels it with the risk tier, trims the description to Azure DevOps's 4000
character limit, reads PR builds with their failed task logs, retries them once
before a fix attempt, and completes the pull request with the account's default
merge type. Work items can be sent to the factory as issues, and active
comment threads reach the agent as review feedback.

### Security: where the credential lives

An Azure DevOps credential can write to every repository it covers, so whoever
can read it can vote, complete and push as you. So:

* **The host node must be a node your agents cannot read.** Never use the
  machine the agents run on. The credential is stored on the host node only. It
  is write-only: Clusto never sends it back to any client, never replicates it to
  other nodes and never logs it.
* **Grant the personal access token these scopes**, and nothing wider:

  | Scope | Access | Used for |
  |---|---|---|
  | Code | Read & write | Listing repositories and pull requests, votes, threads, completing, abandoning, reading file versions for the diff |
  | Build | Read & execute | Listing builds, reading logs, retrying, re-running and cancelling |
  | Work Items | Read & write | Listing assigned work items, comments, state changes, assigning yourself |
  | Project and Team | Read | Listing the projects of an organization |
  | User Profile | Read | Finding your organizations when the Organizations field is empty on Services |

  No Identity scope is needed: Clusto learns who you are from the organization's
  connection data, which every valid token can read. If you list your
  organizations by hand you can leave out User Profile.
* Set the token to expire. When Azure DevOps rejects it the account shows the
  error and the actions stay hidden until you paste a new one.
* Every action you take on a pull request, build or work item is written to the
  host node's audit log (`azure_devops_action`) with the account, target, id and
  action. The action kinds are:

  | Target | Kinds |
  |---|---|
  | Pull request | `vote`, `comment`, `reply`, `set_thread_status`, `complete`, `set_auto_complete`, `abandon`, `reactivate`, `mark_ready`, `requeue_checks` |
  | Build | `build_retry_failed`, `build_rerun`, `build_cancel` |
  | Work item | `work_item_comment`, `work_item_set_state`, `work_item_assign_me` |

  Each entry also records whether the action succeeded (`ok=true` or `ok=false`).

If the host node is offline the view shows the last data it has, marks it read
only, and hides the actions. No other node polls Azure DevOps, because only the
host has the credential.

### Use the az CLI login

Instead of pasting a PAT you can let the host node use an existing Azure CLI
login. This avoids a long-lived secret on the node.

1. On the host node, install the Azure CLI (`az`) and run
   `az login --allow-no-subscriptions` as the OS user that will own the session.
   The flag keeps tenants that hold no Azure subscription, which is common for
   an organization that only uses Azure DevOps; without it `az login` skips
   them.
2. In **Settings -> Azure DevOps**, pick that **OS user** (default: the node's
   default session user) and press **Use az CLI login**. Clusto saves the account
   first, then has the host check the login.
3. The host runs `az account get-access-token` for Azure DevOps as that user and
   keeps the short-lived token in memory only. It refreshes the token about five
   minutes before it expires, so nothing needs renewing by hand.

An organization belongs to one Microsoft Entra tenant, and a token from another
tenant sees none of it. When the login's default tenant reaches no organization,
the host tries every other tenant the login holds and keeps the first one that
does, so the default subscription `az login` picked does not matter. A tenant
that demands multi-factor sign-in (`AADSTS50076`) is skipped until you run
`az login --tenant <tenant id>` for it. One account uses one tenant; add a
second account for organizations in another tenant.

If `az` is missing, the user is not logged in or the login has expired, the
account shows the error from the CLI. Run `az login --allow-no-subscriptions`
again on the host. On a Windows host whose daemon runs as a service, the CLI
starts in that user's home directory. An az CLI
login is meant for Azure DevOps Services; use a PAT for Azure DevOps Server. The scopes
above do not apply: the token carries whatever access your Microsoft Entra
account has in each organization.

**Remove credential** deletes the PAT or az CLI setting from the host node.
Removing the account deletes its credential too. Nothing in Azure DevOps changes
either way.

### Azure DevOps Server

Enter your server URL in **Server URL** and the collection name or names in
**Collections**. Use a personal access token with the same scopes as above.
Clusto talks to it through the same REST routes as on Services, using
`api-version` 7.1, so the Server release must offer that API version.
Organization discovery is a Services feature, so a Server account
always lists its collections by hand.

## Read and unread

Pull requests and work items carry a read state, so you can see what changed
since you last looked. Unread rows show a dot and a bold title.

* **Opening** a pull request or work item marks it read. While it stays open it
  stays read, even if it changes underneath you.
* An item turns **unread again** when something changes:
  * Pull request: a new push, a retitle, the draft state toggled, or a reviewer
    added or changing a vote. Build status changes do not count. New comments
    are not detected yet, because the snapshot does not carry them.
  * Work item: any change that moves its Changed date, which covers fields,
    state and comments.
* The **nav badge** counts unread pull requests waiting on your vote plus unread
  work items assigned to you. Reading them clears the badge; it comes back when
  one changes or a new one arrives. The **Pull requests** and **Work items** tabs
  each show their share as an "N new" badge next to the total, so you can see
  where the nav badge comes from.
* **Unread** on the Pull requests and Work items lists shows only unread items.
  The item you open stays listed after opening it reads it.
* **Mark all read** on the Pull requests list and on the Work items list (your
  own items, not **Whole sprint**) marks every listed item read, respecting the
  current filters.
* **Mark unread** in the detail pane header puts the open item back to unread.
* The F1 palette has **Azure DevOps: mark the listed pull requests read**,
  **Azure DevOps: mark the listed work items read**, **Mark !N unread** and
  **Mark work item #N unread**.

Read state is per device. It is stored locally and not synced between devices,
so each device keeps its own. The first time an account loads on a device,
everything already there counts as read, except pull requests waiting on your
vote, so the badge does not jump.

## Overview

The **Overview** tab is the first tab and the one the view opens on. It is an
at-a-glance dashboard of widgets. Every widget shows its first 5 items and has a
**View all** button that opens the matching tab with the right filter already
applied.

| Widget | Shows | Default |
|---|---|---|
| Needs my vote | Active pull requests waiting for your vote. | On |
| Failing pipelines | The latest finished build of each pipeline and branch that failed. Pull request validation builds are left out, because they show on their pull requests. | On |
| Sprint taskboard | The work items of the running sprint as a taskboard (below). Full width. | On |
| My work items | Open work items assigned to you. | On |
| My pull requests | Active pull requests you opened. | On |
| Running pipelines | Builds that are queued or running. | Off |
| Repositories | The repositories you can see. | Off |

Press **Customize** to choose which widgets show, reorder them and set each one
to half or full width (the width applies on wide screens; on a narrow window and
on a phone the widgets stack). The layout is a synced preference: it is saved
with your account settings and follows you to your other devices (see
[Cloud Sync](/cloud-sync)). The palette has **Azure DevOps: customize the
overview** for the same dialog.

### Sprint taskboard

The taskboard is modelled on the taskboard Azure DevOps shows for a sprint,
grouped by person:

* There is one lane per assignee. Your lane comes first and is open. The other
  lanes are collapsed to a summary such as "1 not started (8), 1 in progress
  (30)", which counts the items per state group with the total remaining hours
  in brackets.
* There is one column per state, ordered by the state's workflow category
  (proposed, in progress, resolved, completed), so the columns follow the
  process of the work item type.
* A card shows the number, title, priority, parent (a link that opens the
  parent), remaining work and tags. The left edge of the card has the color of
  the work item type.
* A **Sprint** filter appears when several sprints are running. A **Work item
  type** filter starts on **Task**, the usual taskboard view; pick another type
  or all types to widen it.
* On a phone the columns stack, one state under the other.

To draw the board the host node also reads each work item's parent (the parent
title is looked up) and its remaining work. It reads the work item types of a
project, with their state categories and colors, once an hour for projects that
have sprint items. Both need only the Work Items read access the Work items tab
already requires.

## Pull requests

The **Pull requests** tab lists the active pull requests. On desktop it is a list beside the
detail pane (drag the divider to resize); on a phone a selected pull request
replaces the list and **Back** returns to it.

Pull request, build and work item filters, unread-only toggles, group-by, repository search and the taskboard sprint and type are remembered on this device and reset when you switch account.

The bucket chips above the list show a count each:

| Bucket | Shows |
|---|---|
| Needs my vote | Active pull requests where you are a reviewer in person, have not voted and are not the author. |
| Mine | Pull requests you wrote. |
| All active | Every active pull request in the visible repositories. |

The personal buckets need the credential's identity. Until the host has a
credential, the view falls back to **All active**.

Narrow the list with the search box (title, repository, author), the
organization, project or repository picker, the drafts picker (**With drafts**,
**Hide drafts**, **Drafts only**) and the **Failing** toggle, which keeps only
pull requests whose build failed. Each row shows the repository and pull request
number, author, how recently it changed, a build chip, a **Draft** badge and the
decisive vote.

### Pull request detail

Open a pull request to see:

* **Actions** - the toolbar described below.
* **Description** - the body, rendered as safe Markdown.
* **Policies** - every branch policy evaluation with its state (approved, queued,
  running, rejected, broken, not applicable), required policies marked apart from
  **Optional** ones, and a link to the build behind a build policy.
* **Reviewers** - each reviewer's vote, with **Required** and **Group** marks.
* **Linked work items** - the work items attached to the pull request; tap one
  to open it in the Work items tab.
* **Discussion** - the comment threads with their status, file and line.
* **Files** - the changed files with a per-file diff. Azure DevOps lists
  changes without patches, so the host reads both versions of each file and
  computes the diff itself. Large pull requests are cut to size caps (300 files
  listed, 100 diffed, 512 KiB per file side) and say so.

The header shows the state, the decisive vote, a **Conflict** badge when the
branch cannot merge cleanly and **Auto-complete on** when it is set.

### Actions

The action bar appears when the host is online and has a credential. Every
action asks for confirmation or a message first where it matters.

| Action | What it does |
|---|---|
| Vote | Sets your vote: approved, approved with suggestions, waiting for author or rejected. **Reset vote** clears it. The button shows your current vote. |
| Complete | Opens the complete dialog: pick the merge type, whether to delete the source branch and whether to complete the linked work items, then merge. A rejected completion (policies not met, conflicts, branch protected) shows the reason and nothing changes. |
| Set auto-complete | Completes the pull request by itself once every policy passes, with the merge type and delete-branch choice you pick. **Cancel auto-complete** turns it off. |
| Comment | Starts a new discussion thread (Markdown, up to 64 KiB). |
| Publish draft | Takes a draft out of draft state. Only shown on drafts. |
| Re-queue checks | Re-queues the failed or expired build policies. Only shown when a policy failed. |
| Abandon | Abandons an active pull request after a confirmation. |
| Reactivate | Reopens an abandoned pull request. |

On any discussion thread, **Reply** posts into the thread, **Resolve** marks it
fixed and a resolved thread offers **Reactivate**. Clusto sends the source commit
it just read when completing, so a push that lands while the dialog is open makes
Azure DevOps refuse instead of merging unreviewed code.

## Pipelines

The **Pipelines** tab lists the latest builds (up to 50 per project, 300 in
total) of the projects that hold a visible repository, newest first. A row shows
the state, pipeline name, build number, branch, repository, who requested it, how
recently, and a chip for the pull request the build belongs to.

Filters: search (pipeline, branch, number), the organization or project picker,
**Failing** (finished builds that failed) and **Mine** (builds you requested;
needs the credential's identity).

Open a build to see its jobs, failed ones first, and the tasks inside each job.
Each job and task has a **Log** button that shows the tail of its log (the last
64 KiB; open Azure DevOps for the rest). The action bar offers:

| Action | What it does |
|---|---|
| Retry failed jobs | Re-runs only the failed jobs. Shown on a finished build with a failure. |
| Run again | Queues a new build of the same pipeline and branch. Shown on a finished build. |
| Cancel | Cancels a queued or running build after a confirmation. |
| Fix with agent | Hands a failed build to an agent (below). |
| Pull request !n | Jumps to the pull request the build belongs to. |

Retry, run again and cancel need Build execute access, and are hidden while the
host is offline or has no credential.

## Work items

The **Work items** tab lists the work items assigned to you that are not Closed,
Done, Removed or Resolved (up to 200 per organization). A row shows the type,
number, title, state, project and, when the item sits in a sprint, a sprint badge
(the last segment of its iteration path). Narrow the list with the search box
(title, state, tag, number), the organization or project picker, a work item type
picker, a state picker and the sprint picker below. **Unread** shows only unread
items (see [Read and unread](#read-and-unread)).

The **Group** picker splits the list into sections with a count each: **Group by
state** in board order (New, Active, and on to Done or Closed), **Group by type**
alphabetically, or **No grouping**.

### Sprints

The **Sprint** picker narrows the list by iteration:

| Choice | Shows |
|---|---|
| Every sprint | No sprint filter. |
| Current sprint | Items in every sprint that is running today in the covered projects. |
| A specific sprint | One sprint. Running sprints are listed first and marked **(current)**, followed by the other sprints the listed items sit in. |

When the list is narrowed to sprints, a summary line appears for each running
sprint with its name, project, date range, days left and "N of M done".

The **Whole sprint** toggle changes what the list holds. Instead of only the open
items assigned to you, it lists every work item of the running sprints, whoever
it is assigned to and in any state except Removed. It starts grouped by state,
and each row shows its assignee. Switch it off to return to your own open items.

The F1 palette has **Azure DevOps: show the whole sprint**, **Azure DevOps: show
my work items** and **Azure DevOps: only work items of the current sprint**.

The host node reads the iterations of each covered project (the projects of the
visible repositories plus the projects of your assigned items) once an hour and
decides which sprints run today from their start and finish dates. The finish day
counts as part of the sprint, and days are taken in UTC. It then reads the work
items of those sprints per organization, at most once a minute and up to 200 per
organization. A project without Boards, or one the credential cannot read, simply
has no sprints. Sprints need Work Items read access, which the tab already
requires.

Open a work item to read its description, details, linked pull requests and
comments. The action bar offers:

| Action | What it does |
|---|---|
| Implement with agent | Starts a chat in your project's checkout to do the work (below). |
| Brainstorm with agent | Same hand-off, but the agent analyses the work item and proposes a plan without changing code. |
| Comment | Posts a comment on the work item (Markdown, up to 64 KiB). |
| Assign me | Assigns the work item to your sign-in name. Hidden when it is already yours. |
| State | A picker of the states the work item type allows; choosing one moves the item. |

## Repositories

The **Repositories** tab lists every Git repository the credential can see, with
a search box. Pinned repositories come first, then the most recently active
(Azure DevOps lists no push time, so activity is when the repository's latest
build was queued). A row shows the project, default branch, the number of active
pull requests, the default branch's build state, and **Empty** and **Disabled**
marks.

* **Pin** keeps a repository at the top and polls it at the fast interval.
* **Hide** removes it from the view and stops polling it. Hiding also unpins.
  Unhide it under **Settings -> Azure DevOps -> Hidden repositories**.
* Tapping the **active pull request** count jumps to the Pull requests tab
  filtered to that repository.
* **Linked projects** - each node reports which of its Clusto projects have a
  remote matching the repository. Clusto recognises the HTTPS, SSH
  (`ssh.dev.azure.com`) and legacy `visualstudio.com` remote forms. Those
  projects appear as chips on the row (and in the agent dialog); tap one to open
  the project in the Files view.

## Agent hand-off

Pick a local project in the dialog. The ones that check out the repository (or,
for a work item, a repository of the same Azure DevOps project) are listed first.
The dialog remembers the project you last started from for each repository (and
each Azure DevOps project, for work items) and preselects it next time, synced
with your other preferences. Nothing is ever pushed.

| Button | Where | What the agent gets |
|---|---|---|
| Review with agent | Every active pull request | The pull request title, link, author, branches, size and the start of the description, with the instruction to fetch `origin` and diff the source branch against the target branch without switching the checkout's branch. |
| Fix failing build | A pull request with a failed policy or build, and a failed build | The failing build and the log tail of each failed job, with the instruction to switch to the failing branch (the pull request's source branch for a validation build), reproduce the failure locally and make the smallest fix, left uncommitted. |
| Implement with agent | A work item | The work item fields, description and comments, with the instruction to check the current branch first, ask before switching or creating one, read the code and make the change with tests, left uncommitted. |
| Brainstorm with agent | A work item | The same brief, asking for analysis and a plan. |

Clusto runs no git command for the hand-off and creates no worktree or branch.
The chat works in the project's own checkout, so the agent does any fetch or
branch switch itself, as the brief tells it. A fix switches branches only when
the checkout has no uncommitted changes; otherwise the agent stops and asks.

Clusto starts a chat on the project's node with the checkout attached, using the agent
and model of your last chat, and sends the brief as the first message. Change the
default agent in **Settings -> Chats**.

## Notifications

The host node records four alert kinds in the durable notification log (see
[Background Notifications](/background-notifications)):

| Kind | Title | When |
|---|---|---|
| `azure_devops_review_requested` | Review requested | You newly appear as a reviewer in person and have not voted. |
| `azure_devops_build_failed` | Build failed on your pull request | The validation build of a pull request you wrote fails (once per source commit). |
| `azure_devops_pull_update` | Your pull request was approved / completed / abandoned | A pull request you wrote is approved, completed or abandoned. |
| `azure_devops_work_item_assigned` | `<Type>` assigned to you | A work item newly appears in your assigned list. |

Each kind has its own switch under **Settings -> Notifications -> Azure DevOps**
and is per device: a device mutes a kind by sending `<kind>=off` on its
`/notifications` poll, like the GitHub kinds. The body reads
`<org/project/repo> !<id>: <title>` for pull requests and
`<project> #<id>: <title>` for work items, and tapping the alert opens that item.

The first poll of an account only records the current state, so turning the view
on does not flood you with alerts for items that already exist. The cursor is
kept on the host, so a restart neither repeats nor drops alerts.

## Polling and throttling

The host node polls Azure DevOps every 60 seconds by default (your poll interval)
and keeps polling when no client is connected. In detail:

* The repository list is reread every 10 minutes.
* Active pull requests are read on every poll with one request per organization.
  An organization that refuses the organization-wide route is read project by
  project instead: active projects on every poll, quiet ones every 10 minutes.
* Builds are read per project that holds a visible repository: on every poll for
  projects with a pinned repository, an active pull request or a running build,
  every 10 minutes for the rest. Pull request checks and the default branch state
  come from these builds, so they cost no extra requests.
* Assigned work items are read on every poll.
* Sprint iterations are read once an hour per covered project, and the work
  items of the running sprints at most once a minute per organization. Work item
  types, with their state categories and colors, are read once an hour for
  projects that have sprint items.
* Details (threads, policies, changed files, logs) are read only when you open
  an item.
* While a build on one of your pull requests is running, polling speeds up to
  **15 seconds**.
* Azure DevOps throttles by usage. Clusto honours the `Retry-After` and
  `X-RateLimit-Remaining` headers, and when it is throttled it slows to one poll
  every 5 minutes until the limit clears. The last data stays on screen.
* When Azure DevOps rejects the credential (`401`, or its sign-in page) on
  every organization, for example a revoked or expired PAT, the view shows the
  rejection and stops regular polling. The host retries after 2 minutes, then
  doubles the wait up to once every 30 minutes, and logs the rejection once.
  Saving a PAT or the az CLI login in **Settings -> Azure DevOps**, or the
  refresh button, tries again at once. A PAT that one organization in the list
  refuses while another answers is reported for that organization and does not
  slow polling.
* The same back-off applies when the az CLI on the host has no usable login
  (never signed in, signed out, or an expired refresh token). The view says to
  sign in again with `az login --allow-no-subscriptions` as the OS user the
  account runs az as, on the host node, then refresh. Other az failures, such
  as a network error, keep the normal poll interval.
* An account reads at most 50 organizations.

### Multiple organizations and projects

* One account polls every organization in its list, and each one separately:
  if an organization or one project cannot be read, the others keep updating,
  the failed one keeps its last data, and **Settings -> Azure DevOps** names
  the organization or project that failed.
* Your identity is looked up in each organization, so **Needs my vote** and
  **Mine** work even where an organization belongs to another Microsoft Entra
  tenant or a Microsoft account.
* With more than one organization, rows and detail pages show the organization
  and project, so projects and repositories with the same name stay apart. The
  scope picker filters by organization, project or repository, and
  **Repositories** is grouped by organization and project.
* An organization added later starts quietly: what is already open there does
  not trigger notifications, only what changes afterwards.
* Linked Clusto projects are found from any Azure DevOps remote: HTTPS, SSH
  (`ssh.dev.azure.com` and `vs-ssh.visualstudio.com`), `*.visualstudio.com`
  and Azure DevOps Server collection URLs.
* For organizations that need different credentials, add one account per
  credential.

The view header shows who you are signed in as, when it last synced and **Fast
polling** while the 15 second interval is on. The refresh button polls
immediately.

## F1 command palette

When the flag is on, the palette has **Open Azure DevOps**, **Go to Azure DevOps
pipelines**, **Go to Azure DevOps work items**, **Refresh Azure DevOps** and
**Azure DevOps settings: accounts, PAT or az CLI, host node**. Inside the view it
adds the tabs, **Azure DevOps: customize the overview**, the pull request buckets, the failing toggles for pull requests
and builds, **Only my builds** and, on the Work items tab, **Azure DevOps: show
the whole sprint**, **Azure DevOps: show my work items** and **Azure DevOps: only
work items of the current sprint**. With a pull request open it adds **Open !n in
Azure DevOps**, **Comment on !n**, the vote choices, **Complete !n**, **Set
auto-complete**, **Review !n with an agent**, **Fix the failing build of !n with
an agent**, **Re-queue the checks of !n**, **Abandon !n**, **Publish draft** and
**Reactivate**. With a build open it adds **Open build in Azure DevOps**,
**Cancel build**, **Retry failed jobs**, **Run again** and **Fix build with an
agent**. With a work item open it adds **Open work item in Azure DevOps**,
**Comment on work item**, **Implement** and **Brainstorm with an agent**,
**Assign work item to me** and **Move work item to `<state>`**.

## Ask the Assistant

The [Clusto Assistant](/assistant) has a read-only `clusto_azure_devops` tool. It
lists the active pull requests across your accounts (repository, number, title,
author, draft, build status, each reviewer's vote and whether one waits on your
vote), your assigned work items, the number of recent failed builds and sync
errors, optionally filtered by repository or account. Pull request and work item
titles are written by other people, so the Assistant treats them as data. To act
on one it points you at this view.

## Troubleshooting

| Symptom | Cause and fix |
|---|---|
| **No credential** badge on the account | The host node has no PAT or az CLI login for it. Paste a PAT or press **Use az CLI login**. |
| "Azure DevOps rejected the credential (expired, revoked or missing a scope)" | The PAT expired, was revoked, or lacks a scope from the table above. Create a new PAT with the listed scopes and paste it. Azure DevOps answers a missing scope the same way as a bad token. |
| az CLI login fails or stops working | `az` is not installed, `az login` was never run for that OS user on the host, or the login expired. Run `az login` as that user on the host, then press **Use az CLI login** again. |
| The list is empty | The Organizations field names an organization you cannot reach, the account is empty on Services and User Profile read is missing so discovery found nothing, or every repository is hidden. Check **Settings -> Azure DevOps**, including **Hidden repositories**. |
| An organization is missing | On Services, discovery needs User Profile (read). Without it, list the organizations by hand. If your organization blocks personal access tokens, use the az CLI login instead. |
| **Needs my vote** and **Mine** are empty | The identity is unknown until a credential is set; the view falls back to **All active**. Make sure the credential belongs to you. |
| Complete is refused | A policy is not met, the branch has conflicts or a required reviewer has not approved. The reason from Azure DevOps is shown and nothing changes. Use **Set auto-complete** to merge once policies pass. |
| Actions are hidden and the view says read only | The host node is offline. The last data stays visible. Bring the host back online. |
| Data looks stale and the account shows a sync error about throttling | Azure DevOps throttled the account; Clusto polls every 5 minutes until it clears. Raise the poll interval or hide repositories you do not need. |
| The agent dialog lists no project | No Clusto project on any node has a remote that matches the repository. Clone it into a project, or pick any project whose `origin` is the same repository. |
| The agent reports that `git fetch` failed or hung | The project's node could not fetch from `origin` without asking for credentials. Open a terminal on that node as the project's user, run `git fetch` in the project once and complete the sign-in so the credential is stored, then ask the agent to retry. |
| The agent stops and asks before switching branches | The checkout has uncommitted changes. Commit or stash them, or tell the agent how to proceed. |
| A diff is missing for a file | The pull request is over the size caps, or the file is binary. Open it in Azure DevOps. |

## Relation to the GitHub view

The [GitHub](/github) view is the same idea for GitHub. They are separate
features with separate flags, accounts and credentials, and share the agent
hand-off dialog and the careful polling approach (the GitHub hand-off checks
items out in a worktree; the Azure DevOps one uses the project's own checkout): the credential
never leaves its host node, and requests are throttled and cached. A project can
link to a GitHub or an Azure DevOps repository, and the two views show only the
projects that match their own host.