Platforms

Azure DevOps

Azure DevOps repositories, pull requests and work items in the same shapes as every other forge. The owner is organization/project.
IDazure-devops06 / 08dev.azure.com
Platform / azure-devops

Azure DevOps

Spoken by AzureDevOpsProvider. Same resources, same shapes, its own quirks kept inside.

Access

CreatecreateProvider("azure-devops")

Importimport { AzureDevOpsProvider } from"@agntn/forges/azure-devops"

EnvAZURE_DEVOPS_EXT_PAT

CLIaz devops login (PAT file)

Config~/.azure/azuredevops/personalAccessTokens

Header
Authorization: Basic
Anonymous
public projects only, and there aren't many
Threads
threads on a file, resolved as fixed
Code search
unsupported, explicit error
Templates
none

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.

ResourceEndpoint
Repositories and tagsGET /git/repositories, GET …, GET …/refs?filter=tags/
Pull requestsGET …/pullrequests, GET …/pullRequests/:id, POST …/pullrequests
Comments and timelineGET …/pullRequests/:id/threads, PATCH and DELETE …/threads/:id/comments/:id
Review threadsGET …/pullRequests/:id/threads, POST …/threads/:id/comments, PATCH …/threads/:id
Commits and checksGET …/commits with $top and $skip, GET …/commits/:sha, GET …/commits/:sha/statuses
Commit comparisonGET …/diffs/commits, GET …/commits
Repository contentsGET …/items, GET …/blobs/:id
Issues (work items)POST /wit/wiql, POST /wit/workitemsbatch, GET /wit/workitems/:id

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.