--- title: "Azure DevOps" description: "Use Azure Repos pull requests and Azure Boards work items on Azure DevOps Services and Server." canonical_url: "https://forges.link/providers/azure-devops" --- # Azure DevOps > Use Azure Repos pull requests and Azure Boards work items on Azure DevOps Services and Server. The Azure DevOps provider works with Azure Repos pull requests and with 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 supports both Azure DevOps Services and Azure DevOps Server, and talks to them through REST API version 7.1, which is exported as `AZURE_DEVOPS_API_VERSION`.
Detail Value
Import forges/azure-devops
Factories azureDevOps() , azureDevOpsLite()
Auth token , basic , anonymous
Work item comments and pull request policies use preview APIs of Azure DevOps, which can change, so the capabilities built on them are `'experimental'`. To learn what that means, see [Capabilities](https://forges.link/concepts/capabilities). ## Authentication The provider accepts a personal access token or Basic credentials. It sends both as HTTP Basic authentication, using an empty user name for a token. You also have to pass your `organization`: ```ts import { azureDevOps } from 'forges/azure-devops' const forge = azureDevOps({ organization: 'acme', auth: { type: 'token', token: process.env.AZURE_DEVOPS_TOKEN! }, }).create() ``` If you leave out `auth`, the provider makes anonymous reads of public data. Azure DevOps sends requests for pull request statuses, policy evaluations and work item queries without credentials to its sign-in page, so an anonymous provider reads pull requests without `checks`, and reports `threads.checks`, `search.threads` and listing work items as unsupported. ## Instance The `baseUrl` defaults to `https://dev.azure.com`, which makes `dev.azure.com` the instance. To use Azure DevOps Server, set `baseUrl` to the root of the server and `organization` to the collection: ```ts azureDevOps({ baseUrl: 'https://tfs.example.com/tfs', organization: 'DefaultCollection', auth, }) ``` ## Repository refs A repository belongs to a project, and a project belongs to an organization. For this reason, `RepoRef.owner` is `/`, and `name` is the name of the repository: ```ts const repo = { forge: 'azure-devops', instance: 'dev.azure.com', owner: 'acme/Widgets', name: 'widgets', } as const ``` Work items belong to a project and not to a repository, so their refs use a namespace ref: `{ owner: 'acme/Widgets', name: '', kind: 'namespace' }`. `repos.byOwner()` takes the same namespace ref and lists the repositories of the project. Azure DevOps doesn't sort them, so if you pass `sort`, you get a `sort_unsupported` warning. ## Work items as issues `threads.create({ kind: 'issue' })` creates a work item of the type `Issue`. If your process template uses a different type, such as `Product Backlog Item`, set the `issueType` option. The tags of a work item are its labels, and `System.AssignedTo` is its single assignee. ## Merging The provider doesn't read branch policies, so it can't tell which merge strategies are allowed. For this reason, `merge()` requires a `method` and throws `MergeMethodRequiredError` without it. The `fast_forward_only` method isn't available. `merge()` completes the pull request at its current source commit, and `approveAndMerge()` votes to approve it first. If you pass `whenChecksPass`, `merge()` sets auto-complete on the pull request instead of merging right away. Azure DevOps usually completes a pull request in the background, so `merge()` resolves with `status: 'queued'` and no `sha` until the response reports the pull request as completed. Read the pull request later to see the merge commit. ## Votes as reviews Azure DevOps has votes instead of reviews, so the provider presents votes as reviews. `threads.reviews()` returns one review for each reviewer who has voted, with the ID `vote:`. 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`. If you pass a body or inline comments, it rejects with `UnsupportedOperationError`. ## Checks `threads.checks()` returns the statuses of a pull request and the evaluations of its branch policies in one list. ## Webhooks Azure DevOps service hooks don't sign their deliveries. A service hook subscription can send Basic credentials, though, so set `webhookSecret` to `username:password`. The provider compares it with the `Authorization` header of each delivery. If you don't set `webhookSecret`, no delivery verifies. ```ts 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 level of the organization and not on a repository, so the management methods of `webhooks` aren't available. ## Organisation teams Azure DevOps teams belong to a project rather than to the organization, so the organisation ref is a project namespace: `owner: 'organization/project'`. `orgs.teams()` reads the project's teams with `GET /{organization}/_apis/projects/{project}/teams`, and `orgs.teamMembers()` reads a team's members with `GET /{organization}/_apis/projects/{project}/teams/{team}/members`, addressing the team by `ref.id` when it is set and by its name otherwise. Both need a token with the `vso.project` scope, so `can('orgs.teams')` is `false` without a credential. ```ts const project = { forge: 'azure-devops', instance: 'dev.azure.com', owner: 'acme/Widgets', name: '', kind: 'namespace' } as const for await (const team of provider.orgs.teams(project)) { for await (const member of provider.orgs.teamMembers(team.ref)) { console.log(team.name, member.login) } } ``` ## Capabilities
Capability Support Without credentials
experimental ❌ ❌
sources.poll ❌ ❌
sources.webhook ✅ ✅
sources.subscribe ❌ ❌
repos.get ✅ ✅
users.get ❌ ❌
users.me ❌ ❌
users.sponsorable ❌ ❌
users.events ❌ ❌
repos.list ✅ ❌
repos.byOwner ✅ ✅
repos.labels ❌ ❌
repos.createLabel ❌ ❌
repos.milestones ❌ ❌
repos.collaborators ❌ ❌
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ❌ ❌
repos.permissionFor ❌ ❌
repos.addCollaborator ❌ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ❌ ❌
repos.events ❌ ❌
orgs.teams ✅ ❌
orgs.teamMembers ✅ ❌
threads.get issue, PR issue (unverified), PR
threads.list issue, PR PR
threads.getMany ✅ ✅
threads.events issue, PR issue (unverified), PR
comments.list issue (experimental), PR issue (unverified), PR
comments.get issue (experimental), PR issue (unverified), PR
comments.edit issue (experimental), PR ❌
comments.delete issue (experimental), PR ❌
reactions.list ❌ ❌
notifications.list ❌ ❌
notifications.markRead ❌ ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead ❌ ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount ❌ ❌
writes.comment issue (experimental), PR ❌
writes.upsertComment issue (emulated), PR (emulated) ❌
writes.close issue, PR ❌
writes.reopen issue, PR ❌
writes.create issue, PR ❌
writes.update issue, PR ❌
writes.setLabels issue, PR ❌
writes.addLabels ❌ ❌
writes.removeLabels ❌ ❌
writes.setMilestone ❌ ❌
writes.react ❌ ❌
writes.setAssignees issue ❌
writes.requestReview PR ❌
writes.merge ✅ ❌
writes.approveAndMerge ✅ ❌
writes.transfer ❌ ❌
writes.markDuplicate ❌ ❌
subscriptions.get ❌ ❌
subscriptions.set ❌ ❌
installations ❌ ❌
checks.thread PR (experimental) ❌
checks.list ✅ ✅
checks.get ❌ ❌
checks.report ✅ ❌
checks.rerun ❌ ❌
ci.runs ❌ ❌
ci.run ❌ ❌
ci.jobs ❌ ❌
ci.job ❌ ❌
ci.log ❌ ❌
contents.file ✅ ✅
contents.tree ✅ ✅
contents.branches ✅ ✅
contents.tags ✅ ✅
contents.resolveRef ✅ ✅
contents.commits ✅ ✅
contents.commit ✅ ✅
contents.compare ✅ ✅
contents.commitFiles ✅ ❌
contents.threadFiles ❌ ❌
contents.threadCommits ✅ ✅
reviews.list emulated emulated
reviews.get emulated unverified
reviews.create emulated ❌
reviews.submit ❌ ❌
reviews.approve emulated ❌
reviews.reply ❌ ❌
reviews.resolveThread ✅ ❌
releases.list ❌ ❌
releases.get ❌ ❌
releases.latest ❌ ❌
releases.getByTag ❌ ❌
releases.downloadAsset ❌ ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.list ❌ ❌
webhooks.create ❌ ❌
webhooks.update ❌ ❌
webhooks.delete ❌ ❌
webhooks.rotateSecret ❌ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ✅ ❌
search.repos ❌ ❌
search.commits ❌ ❌
search.code ❌ ❌
securityAlerts ❌ ❌
eventKinds native native
authKinds token , basic , anonymous token , basic , anonymous
limits unknown unknown
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.