Azure DevOps

The Azure DevOps provider covers Azure Repos pull requests and Azure Boards work items, which it treats as issues. It also covers pull request statuses, branch policies, repository contents and incoming service hook deliveries. It works with Azure DevOps Services and Azure DevOps Server through REST API version 7.1 (AZURE_DEVOPS_API_VERSION).

Authentication

The provider accepts a personal access token or Basic credentials. It sends both as HTTP Basic auth, with an empty user name for a token. organization is required:

import { azureDevOps } from 'forges/azure-devops'

const forge = azureDevOps({
  organization: 'acme',
  auth: { type: 'token', token: process.env.AZURE_DEVOPS_TOKEN! },
}).create()

Without auth, the provider makes anonymous public reads.

Instance

baseUrl defaults to https://dev.azure.com, so the instance is dev.azure.com. For Azure DevOps Server, set baseUrl to the server root and organization to the collection:

azureDevOps({
  baseUrl: 'https://tfs.example.com/tfs',
  organization: 'DefaultCollection',
  auth,
})

Repository refs

A repository belongs to a project in an organization. RepoRef.owner is <organization>/<project>, and name is the repository name:

const repo = {
  forge: 'azure-devops',
  instance: 'dev.azure.com',
  owner: 'acme/Widgets',
  name: 'widgets',
} as const

Work items belong to a project, so their refs use a namespace ref: { owner: 'acme/Widgets', name: '', kind: 'namespace' }.

Work items as issues

threads.create({ kind: 'issue' }) creates a work item of type Issue. If your process template uses a different type, such as Product Backlog Item, set the issueType option. Work item tags are labels, and System.AssignedTo is the single assignee.

Merging

The provider doesn't read branch policies, so it can't tell which merge strategies are allowed. merge() requires method, and throws MergeMethodRequiredError without it. The fast_forward_only method is unavailable.

merge() completes the pull request at its current source commit, and approveAndMerge() votes to approve first. With whenChecksPass, merge() sets auto-complete on the pull request.

Votes as reviews

threads.reviews() returns one review for each reviewer who has voted, with the ID vote:<id>. A vote of 5 or 10 is approved, and a vote of -5 or -10 is changes_requested.

createReview() votes 10 for approve and -10 for request_changes. A body or inline comments reject with UnsupportedOperationError.

Checks

threads.checks() returns pull request statuses and branch policy evaluations in one list.

Webhooks

Azure DevOps service hooks don't sign deliveries. A service hook subscription can send Basic credentials, so set webhookSecret to username:password. The provider compares it with the Authorization header of each delivery. Without webhookSecret, no delivery verifies.

const forge = azureDevOps({
  organization: 'acme',
  webhookSecret: process.env.AZURE_DEVOPS_HOOK_CREDENTIALS,
}).create()

const events = await forge.webhooks.ingest({
  headers: request.headers,
  body: await request.text(),
})

You manage service hook subscriptions at the organization level, not on a repository, so the webhooks management methods are unavailable.

Recording fixtures

AZURE_DEVOPS_TOKEN=... \
FIXTURE_AZURE_DEVOPS_ORGANIZATION=acme \
FIXTURE_AZURE_DEVOPS_PROJECT=Widgets \
FIXTURE_AZURE_DEVOPS_REPO=widgets FIXTURE_AZURE_DEVOPS_PULL=1 \
pnpm record-fixtures azure-devops

To add a work item, set FIXTURE_AZURE_DEVOPS_ISSUE.

Capabilities

Generated by pnpm capability-matrix; do not edit by hand.