---
title: "Azure DevOps"
description: "Azure DevOps repositories, pull requests and work items in the same shapes as every other forge. The owner is organization/project."
canonical_url: "https://forges.agntn.dev/platforms/azure-devops"
---
# Azure DevOps

> Azure DevOps repositories, pull requests and work items in the same shapes as every other forge. The owner is organization/project.

<platform-facts platform="azure-devops">



</platform-facts>

## Address an Azure DevOps project

```ts
import { createProvider } from "@agntn/forges";

const azure = await createProvider("azure-devops", { token: process.env.AZURE_DEVOPS_EXT_PAT });

const wiki = { owner: "dnceng-public/public", repo: "dotnet-public-wiki" };
const pull = await azure.pullRequests.get({ ...wiki, number: 5 });
const home = await azure.repos.readContents(wiki, { path: "Home.md" });
```

A repository lives in a project inside an organization. Set `owner` to `organization/project`. The repository's `fullName` includes all three parts: `dnceng-public/public/dotnet-public-wiki`.

Each owner part must be one path segment. Empty parts, `..` and a third segment get a 400 before any request.

A bare project also works when forges knows the organization. Set `baseURL` to `https://dev.azure.com/acme` or `https://acme.visualstudio.com`. The MCP server and extensions also accept `FORGES_AZURE_DEVOPS_BASE_URL`. Otherwise, the credential chain can find the default organization.

Without an organization, a bare project gets a 400 before any request. The error names those three ways to supply it.

MCP, Pi and OMP tools also accept `repo` as `organization/project/name`. Other platforms still reject two slashes in `repo`.

This provider supports Azure DevOps Services, including the old `visualstudio.com` hosts. It refuses Azure DevOps Server URLs, such as `https://tfs.example.com/tfs`, with a 400.

### Where does the token come from?

The chain checks an explicit `{ token }` first. Then it checks `AZURE_DEVOPS_EXT_PAT`, which the `az devops` extension also reads.

Finally, it checks the PAT file saved by `az devops login`. That's `~/.azure/azuredevops/personalAccessTokens` on Linux. The keyring isn't checked.

The organization comes from `baseURL` first. Next comes `AZURE_DEVOPS_EXT__DEFAULTS_ORGANIZATION`, then `[defaults] organization` in the `az devops` config.

The PAT goes as Basic auth with an empty username. Pass `{ token: "" }` to read public projects anonymously. Public projects are rare, but `dnceng-public/public` is one.

## What it reads

Endpoints are relative to `https://dev.azure.com/:organization/:project/_apis`. In this table, `…` means `/git/repositories/:repo`.

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      Endpoint
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Repositories and tags
    </td>
    
    <td>
      <code>
        GET /git/repositories
      </code>
      
      , <code>
        GET …
      </code>
      
      , <code>
        GET …/refs?filter=tags/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pull requests
    </td>
    
    <td>
      <code>
        GET …/pullrequests
      </code>
      
      , <code>
        GET …/pullRequests/:id
      </code>
      
      , <code>
        POST …/pullrequests
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Comments and timeline
    </td>
    
    <td>
      <code>
        GET …/pullRequests/:id/threads
      </code>
      
      , <code>
        PATCH
      </code>
      
       and <code>
        DELETE …/threads/:id/comments/:id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Review threads
    </td>
    
    <td>
      <code>
        GET …/pullRequests/:id/threads
      </code>
      
      , <code>
        POST …/threads/:id/comments
      </code>
      
      , <code>
        PATCH …/threads/:id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Commits and checks
    </td>
    
    <td>
      <code>
        GET …/commits
      </code>
      
       with <code>
        $top
      </code>
      
       and <code>
        $skip
      </code>
      
      , <code>
        GET …/commits/:sha
      </code>
      
      , <code>
        GET …/commits/:sha/statuses
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Commit comparison
    </td>
    
    <td>
      <code>
        GET …/diffs/commits
      </code>
      
      , <code>
        GET …/commits
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Repository contents
    </td>
    
    <td>
      <code>
        GET …/items
      </code>
      
      , <code>
        GET …/blobs/:id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Issues (work items)
    </td>
    
    <td>
      <code>
        POST /wit/wiql
      </code>
      
      , <code>
        POST /wit/workitemsbatch
      </code>
      
      , <code>
        GET /wit/workitems/:id
      </code>
    </td>
  </tr>
</tbody>
</table>

## What comes back

- Issues are project work items. Their numbers span the project, not each repository.
- Pull requests include conversation comments, events and checks. Checks combine commit statuses and policy evaluations when you have a token.
- Conversation comment IDs look like `12/1`. Comment numbers restart at 1 in each thread.
- Review threads have a file path. Conversation threads stay in `pullRequests.listComments`.
- A review thread is resolved unless its status is `active` or `pending`. `isOutdated` is always false.
- Resolving sets `fixed`, matching the web UI's Resolve button. Unresolving sets `active`. Resolving an already resolved thread changes nothing.
- A thread reply answers its first comment.
- Commit pages have no total. forges asks for one extra row to find the next page. Filters for `since`, `until`, `path` and `ref` work.
- Comparisons return changed files and up to 1000 commits, oldest first. `filesComplete` is `true` once Azure DevOps says `allChangesIncluded`.
- Contents resolve the ref to a commit first. Directory listings are one level deep, with `size: null`.
- File size comes from the blob before its bytes. Files over 1 MiB get a 413 without downloading their contents.
- Tags are peeled refs under `tags/`.

## Gotchas

Why does `v1.0` resolve to nothing?

- A bare tag name is read as a branch. Use `refs/tags/v1.0` instead. A 40-hex SHA is read as a commit.
- Anonymous issue lists get a 501. Azure DevOps only runs work item queries for someone logged in.
- A missing work item and an unreadable one both return 404. That answer doesn't tell you which case you hit.
- A bad token on a private organization would normally bounce to Microsoft's login page. forges sends `X-TFS-FedAuthRedirect: Suppress`, so it gets an `AuthenticationError` with 401 instead.
- `issues.create` makes a work item of type `Issue`. A Scrum project has no such type, so Azure DevOps refuses it.
- The docs explorer at forges.agntn.dev doesn't run Azure DevOps. It needs a token, and public projects are rare.

## What isn't there

Releases aren't available because Azure DevOps has none. Pipelines don't map to `ciRuns.list` or `ciJobs` yet. Read commit or pull request checks instead.

User lookup and authenticated user lookup aren't wired here. Neither are code search, templates, reactions, issue fields or sub issues.

Some gaps are ours, not Azure DevOps'. Posting a new conversation comment, editing an issue or pull request, merging, reviews and patches aren't wired up yet. Editing and deleting a comment work.

Each returns a `ForgesError` with a 501 and a sentence. When the provider knows upfront, it returns that error before any request.

Work item numbers count across the whole project, so issue 7 might live next to a repository it has never met.

## Where it lives

The provider lives in `src/providers/azure-devops.ts`. It uses the `forges/azure-devops` adapter and tokens from `@agntn/credentials/azure-devops`.


## Sitemap

See the full [sitemap](https://forges.agntn.dev/sitemap.md) for all pages.
