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
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.
| Resource | Endpoint |
|---|---|
| Repositories and tags | GET /git/repositories, GET …, GET …/refs?filter=tags/ |
| Pull requests | GET …/pullrequests, GET …/pullRequests/:id, POST …/pullrequests |
| Comments and timeline | GET …/pullRequests/:id/threads, PATCH and DELETE …/threads/:id/comments/:id |
| Review threads | GET …/pullRequests/:id/threads, POST …/threads/:id/comments, PATCH …/threads/:id |
| Commits and checks | GET …/commits with $top and $skip, GET …/commits/:sha, GET …/commits/:sha/statuses |
| Commit comparison | GET …/diffs/commits, GET …/commits |
| Repository contents | GET …/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
activeorpending.isOutdatedis always false. - Resolving sets
fixed, matching the web UI's Resolve button. Unresolving setsactive. 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,pathandrefwork. - Comparisons return changed files and up to 1000 commits, oldest first.
filesCompleteistrueonce Azure DevOps saysallChangesIncluded. - 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.0instead. 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 anAuthenticationErrorwith 401 instead. issues.createmakes a work item of typeIssue. 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.