docs: Update Azure DevOps integration

[warp-agent-staging]

What this feature does

Hosted Azure DevOps Services lets a factory access selected repositories, use a dedicated factory identity, and start runs from Azure DevOps events. Each automation also requires its creator's active, correctly scoped Azure DevOps OAuth connection. Azure DevOps Server remains outside first-class support. The implementation shipped in v0.2026.09.30.08.29.stable_01 (2026-09-30), but production enablement remains a merge dependency.

Summary

Adds a first-class Azure DevOps Services factory guide while retaining the existing personal-access-token workflow for standalone cloud agents.

Changes

• Adds the first-class factory guide under factories/integrations/ and lists it with the other factory code forges.
• Retains the standalone cloud-agent PAT, Warp-managed secret, and environment workflow at the existing platform URL.
• Restores Azure DevOps Server PAT creation and authenticated factory clone guidance on the custom code-forge page.
• Explains personal setup access and creator-based identity, the Azure DevOps Manager, per-factory service principals, the automation creator's OAuth requirement, Basic-seat impact, and required Entra and Azure DevOps administrator roles.
• Lists the supported work item and pull request triggers and their filters without exposing the dormant push event.
• Adds troubleshooting for work item mention autocomplete and organization or project mismatches when assigning a factory identity.
• Updates the integrations overview and cross-links the factory, standalone cloud-agent, and Azure DevOps Server paths.

Content design plan

Audience and JTBD: A workspace or factory administrator connecting hosted Azure DevOps Services who needs to coordinate repository selection and administrator approvals, then understand the roles of their personal connection, the Azure DevOps Manager, the factory identity, and the automation creator's connection. Standalone cloud-agent users still need the existing PAT-based environment workflow.

Problem: The existing platform page serves standalone cloud agents and says native Azure DevOps support is unavailable. Replacing it would remove that workflow, while leaving the factory content there would make it undiscoverable from the Factories sidebar.

Goals:

• Make the Azure DevOps Services-only support boundary clear.
• Let the reader identify the required Microsoft Entra and Azure DevOps administrators and complete setup.
• Explain which service principals Warp creates, what access they receive, how creator-based identity works, which creator connection dispatch requires, and which Azure DevOps events can trigger automations.
• Preserve the standalone cloud-agent and Azure DevOps Server credential paths.

Purpose and value: The factory page becomes the canonical setup and permissions guide for the first-class integration, while the platform page remains the canonical standalone cloud-agent workflow.

Content type: Feature documentation combining the identity model, trigger reference, setup procedure, and troubleshooting.

Skill and template: draft_feature_doc / .agents/templates/feature-doc.md

High-impact scenarios:

• Covers: hosted Azure DevOps Services, split Entra and Azure DevOps administrator approvals, delegated setup links, per-factory identities, creator-based identity, the automation creator OAuth requirement, supported automation events, identity-picker limitations, assignment scope errors, Basic-seat impact, and links to standalone and Server setup.
• Excludes: first-class Azure DevOps Server support and the dormant push trigger.

Unverified claims

• Confirm first-class Azure DevOps Services support is enabled in production before merging this documentation.
  Location: factories/integrations/azure-devops.mdx, introduction. Verify prod.yaml enables all five current first-class Azure DevOps flags and the production client exposes the flow.

Documentation risk

Risk: engineering-review-required
Rationale: Adds first-class factory setup, permissions, identity, availability, automation credential binding, trigger behavior, and identity troubleshooting while retaining standalone cloud-agent setup.
Source files consulted: warp-server@c14eb26eaa0a1dc482db5ed7265a2ca8e10f83ff: logic/azuredevops.go; logic/azuredevops_automation.go; logic/azure_devops_manager_application.go; logic/azure_devops_manager_setup.go; logic/azure_devops_factory_identity.go; logic/azuredevops_factory_scope_test.go; logic/codeforge/azuredevops/identities.go; logic/ai/ambient_agents/{git_credentials.go, azure_devops_executor_credentials.go, automation_dispatch.go, automation_dispatch_azure_devops_test.go}; logic/ai/ambient_agents/automations/{provider_azure_devops.go, provider_azure_devops_test.go}; logic/factorysource/defaults/azure_devops_automation.go; config/prod.yaml; client/packages/factory/.env.production; client/packages/factory/src/pages/FactoryAutomations/azure-devops.ts; client/packages/factory/src/pages/FactorySetup/steps/AzureDevOpsManagerCard.tsx
Technical claims verified: warp-server@85056cb3d3fa795c48d73660812d73fce78987d9: logic/azure_devops_manager_setup.go uses but does not store the administrator's delegated token; logic/codeforge/azuredevops/manager_clients.go grants the Manager Basic access and Project Collection Administrators membership; logic/codeforge/azuredevops/factory_identity_clients.go grants each factory identity Basic access.
Product evidence consulted: originating Slack follow-up; Microsoft Learn @mention identity search, identity picker filtering and MRU APIs, Azure DevOps Server PAT creation, and Azure Repos authentication
Engineering review status: pending
Docs override: none

Merge dependency

Do not merge until the first-class Azure DevOps environment, factory identity, executor, automation, and setup-delegation features are enabled in production and the inline VERIFY marker is removed.

Validation

• 84-character PAT Basic-auth reproduction — passed; GNU base64 wrapped the raw value onto 2 lines, while both corrected command forms produced a single 116-character value that decoded to :PAT and ran with git -c ... --version.
• Repeat-safe Azure DevOps Server clone reproduction — passed; running the guarded setup command twice produced one valid checkout at the expected commit without a second clone failure.
• python3 .agents/skills/style_lint/style_lint.py --changed — passed; 4 files scanned, 0 errors, and 5 advisory unrecognized-term warnings for exact UI labels.
• npm run build — passed; 391 Markdown pages generated and 393 HTML files indexed by Pagefind.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — passed; 4,323 internal links checked, 0 broken.
• Compression contract — passed for the factory feature page, standalone cloud-agent procedure, and custom code-forge procedure.
• python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --changed --require-provenance — passed; 4 files scanned, 0 issues.
• python3 .agents/skills/create_pr/check_pr_body.py /tmp/azure-devops-docs-pr-body-current.md --require-lead-section "## What this feature does" — passed.
• python3 .agents/skills/doc_quality_policy/check_pr_contract.py — passed; 1 VERIFY marker accounted across 4 changed documentation files.
• git diff origin/main...HEAD --check — passed.
• trunk check / trunk fmt — unavailable because Trunk isn't installed in this environment.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 6, 2026 12:32am UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

[captainsafia]

Some feedback here. Let's remove internal implementation details from this doc and make it more user facing.

Let's also add a note that clarifies that the fact that we provision a service account in ADO with Basic user access means the SA uses a license seat on the user's ADO org.

[warp-agent-staging]

Your GitHub account is not connected to Warp. Connect it here.

[warp-for-oss]

@captainsafia

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR replaces the legacy personal-access-token workaround on the Azure DevOps integration page with hosted Azure DevOps Services factory setup, identity, automation, and troubleshooting documentation, and updates the integrations overview to distinguish Azure DevOps from Bitbucket.

Concerns

• No blocking issues found in the annotated diff.
• spec_context.md reports no approved or repository spec context for this PR, so there is no implementation spec drift to flag.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/integrations/azure-devops.mdx:2 — [IMPORTANT] The rewrite replaces the standalone cloud agent Azure DevOps guide with a factory-only page. src/sidebar.ts lines 426-428 has no Azure DevOps entry under Factories > Code forges, so factory readers can't find it. Non-factory cloud agent users lose the only documented setup path. Requested change: publish the factory content at src/content/docs/factories/integrations/azure-devops.mdx and add it to the Factories Code forges sidebar group. Keep a trimmed standalone cloud agent page and cross-link the two, as GitLab does. If removal is intentional, say so in the PR body and add a pointer for cloud agent users, and update the platform/integrations/index.mdx bullets to match.
• src/content/docs/platform/integrations/azure-devops.mdx:27-37 — [IMPORTANT] The page is 1,625 words against the 1,500-word feature-doc budget, and the PR body's justification ('unchanged in this correction') doesn't apply to mostly new content. The factory identity, Manager permissions, and Basic-seat impact are each stated several times (lines 24, 29, 31-35, 37, 52-55, 59). Requested change: run the deletion-only 'Cut again' pass, fold the identities table into one place, delete line 37 and the bullets at lines 23-25 that restate the table, keep the Basic-seat caution once, and target 1,500 words or fewer, or add a PR-body justification for the overage.
• src/content/docs/platform/integrations/azure-devops.mdx:55 — [SUGGESTION] 'Warp uses the administrator's sign-in for this approval and doesn't retain it' is a security and data-handling claim, as are the Project Collection Administrators membership and Basic-seat claims on lines 34 and 59, and none is covered by the single VERIFY marker. Requested change: have the engineering reviewer confirm these against the cited logic/azure_devops_manager_setup.go and logic/azure_devops_manager_application.go sources and record the confirmation in the PR body, or remove any unsupported claim.
• src/content/docs/platform/integrations/azure-devops.mdx:88 — [SUGGESTION] 'confirm that a work item starts in the factory dashboard' is ambiguous because 'work item' also means the Azure DevOps ticket, and a matching event starts a run. Requested change: write 'confirm that a run starts in the factory dashboard' or distinguish factory work items from Azure DevOps work items.
• src/content/docs/platform/integrations/azure-devops.mdx:109-123 — [SUGGESTION] Troubleshooting mixes a bulleted symptom list (lines 111-114) with H3 symptom headings and Cause/Workaround labels, and line 123 hedges with 'may now appear'. Requested change: convert the bullets into H3 symptom headings with a short cause and fix, and state the expected autocomplete result plainly with the plain-text-mention check as a separate sentence.
• src/content/docs/factories/code-forges/other-code-forges.mdx:24-42 — [SUGGESTION] The Azure DevOps Server PAT steps and clone command sit under Prerequisites, but the command is only used in the clone section from line 64 onward, and --config-env needs Git 2.31 or later, which the page doesn't state. Requested change: keep only PAT creation under prerequisites, move the clone command and placeholder explanation into the clone section next to the Bitbucket example at line 72, and add the Git version requirement or confirm the runner image's Git version in the PR body.
• src/content/docs/factories/code-forges/other-code-forges.mdx:34 — [NIT] 'Store this token as CODE_FORGE_TOKEN in [Grant the clone credential]' reads as if the token is stored inside a section. Requested change: apply the suggestion block to say 'Store this token as the CODE_FORGE_TOKEN Agent Secret by following Grant the clone credential.'

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/code-forges/other-code-forges.mdx:69 and src/content/docs/platform/integrations/azure-devops.mdx:78 — [SUGGESTION] The quoted text | base64 wraps output at 76 columns, so a PAT longer than about 57 bytes (legacy 84-character tokens) produces a multi-line Authorization header and the clone fails. Requested change: pipe through tr -d '\n' (for example | base64 | tr -d '\n') in both commands.
• src/content/docs/platform/integrations/azure-devops.mdx:78 — [SUGGESTION] The clone command changed from a token embedded in the URL to an http.extraheader Basic auth header, but the PR's Changes list and Documentation risk rationale never mention it. Requested change: list this command change in the PR body and rationale so the engineering reviewer verifies it explicitly against the cited Azure Repos authentication source.
• src/content/docs/factories/integrations/azure-devops.mdx:29 — [SUGGESTION] The quoted text 'a dedicated service account identity' conflicts with 'Microsoft Entra application and service principal' used at line 37 and in the identity table. Requested change: pick one term for the factory identity and use it consistently.
• src/content/docs/factories/integrations/azure-devops.mdx:106 — [SUGGESTION] The Troubleshooting section mixes four bullet entries with symptom-keyed H3 headings. Requested change: convert the bullet entries to H3 headings keyed on the symptom so all entries follow the troubleshooting convention.
• src/content/docs/factories/integrations/azure-devops.mdx:115 — [SUGGESTION] The quoted sentence 'Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata' is internal implementation detail the reader can't act on. Requested change: delete the sentence and keep the cause and workaround.
• src/content/docs/factories/integrations/azure-devops.mdx:66 — [SUGGESTION] Step 2 says 'In the code host step, find the Azure DevOps row and click Connect', but the sibling GitHub page uses the label 'Connect your code host' and exact option labels. Requested change: verify the step and button labels against AzureDevOpsManagerCard.tsx and the production UI, then quote them exactly.
• src/content/docs/factories/integrations/azure-devops.mdx:21 — [NIT] The 'What the Azure DevOps integration does' bullet list restates the intro paragraph and the identity table. Requested change: delete the list or fold any unique fact into the intro.
• src/content/docs/platform/integrations/azure-devops.mdx:13 — [NIT] A stray double blank line follows the intro paragraph, left over from the removed :::note wrapper. Requested change: remove one blank line.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/azure-devops.mdx:21 — [SUGGESTION] The page is ~1,529 words, just over the ~1,500-word guideline, and the "What the Azure DevOps integration does" list restates the intro and the identity table. Requested change: run a deletion-only pass and remove or merge lines 21-25 into the intro, so the page drops comfortably under 1,500 words.
• src/content/docs/factories/integrations/azure-devops.mdx:25 — [SUGGESTION] The Trigger bullet ("Start factory runs from Azure DevOps events such as pull requests, work item updates, and mentions...") duplicates the "Supported events and filters" table. Requested change: delete the bullet or the whole list and rely on the table.
• src/content/docs/factories/integrations/azure-devops.mdx:29 — [SUGGESTION] "dedicated service account identity" introduces a third name alongside "factory identity" and "Microsoft Entra application and service principal" (lines 24 and 37). Requested change: use "factory identity" here, defining it once as an Entra application and service principal.
• src/content/docs/factories/integrations/azure-devops.mdx:59 — [SUGGESTION] "The Manager and each factory identity can each consume one Azure DevOps Basic seat" is ambiguous about whether seat use always happens, and it is a licensing claim the cited source files should confirm. Requested change: state plainly that each consumes one Basic seat (or name the exception), and confirm the wording against the cited server code during engineering review.
• src/content/docs/factories/integrations/azure-devops.mdx:120 — [SUGGESTION] "The identity may now appear in autocomplete" hedges the outcome of the workaround. Requested change: state the expected result directly (for example, "The identity appears in autocomplete") if verified, or say what to do when it still doesn't appear.
• src/content/docs/platform/integrations/azure-devops.mdx:12 — [NIT] Removing the callout left two consecutive blank lines before the Services/Server sentence. Requested change: delete the extra blank line so there is a single blank line between lines 11 and 14.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/azure-devops.mdx:29 — [SUGGESTION] The Manager-created identity is called a "service account identity" here but a "Microsoft Entra identity and service principal" elsewhere on the page. Requested change: pick one reader-facing term and introduce the Entra detail once.
• src/content/docs/factories/integrations/azure-devops.mdx:34 — [SUGGESTION] The Manager row's "Owns only the Entra applications it creates" and the factory identity row's "Service Hooks access" describe Warp internals, which a reviewer asked to remove. Requested change: keep the permissions administrators must approve (Basic access, Project Collection Administrators membership, the Graph permission) and trim the rest.
• src/content/docs/factories/integrations/azure-devops.mdx:59 — [NIT] "can each consume one Azure DevOps Basic seat" hedges a fact the reviewer asked to state plainly. Requested change: state that the Manager and each factory identity each use one Basic seat in the organization, then keep the license-check sentence.
• src/content/docs/factories/integrations/azure-devops.mdx:134 — [SUGGESTION] The troubleshooting cause for mention autocomplete explains the identity picker and mention metadata internally. Requested change: shorten it to what the reader sees (for example, Azure DevOps hides the factory identity from @-mention autocomplete until it has been used) and keep the workaround steps.
• src/content/docs/factories/code-forges/other-code-forges.mdx:69 — [SUGGESTION] The Azure DevOps Server setup command is a bare git clone that fails when the directory exists, but the page says setup commands run each time the runner prepares a workspace and must be safe to run repeatedly. Requested change: make the command idempotent (clone only when REPO doesn't exist, or fetch and reset when it does) or explain how the runner handles an existing checkout.

Verdict

Approve with nits

[hongyi-chen]

small note to self that this should no longer be request access after tomorrow, should probably take you directly to platform.warp.dev or warp.dev/factories

[warp-agent-staging]

Leaving this open for production enablement. The public Factories page still says closed Early Access, and the request-access URL is live, so the link should change only when the PR's VERIFY gate is cleared.

Responding as Docs Factory (V2): Open session · View in factory

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/azure-devops.mdx:23 — [SUGGESTION] The 'What the Azure DevOps integration does' list restates the opening paragraph and later sections, which breaks the 'Say it once' rule. Requested change: delete the section, or fold the one new fact (each factory gets its own Microsoft Entra identity) into the opening paragraph.
• src/content/docs/factories/integrations/azure-devops.mdx:138 — [SUGGESTION] 'Add the factory identity to Azure DevOps's recently used identity cache' names an internal mechanism the reader can't act on, and 'Azure DevOps's' reads awkwardly. Requested change: reword the lead-in to 'Make Azure DevOps recognize the factory identity by using it once in the organization:' and keep the numbered steps.
• src/content/docs/platform/integrations/azure-devops.mdx:14 — [SUGGESTION] The sentence 'This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances' conflicts with the removed Server sign-in note and a clone command that only covers dev.azure.com. Requested change: scope the sentence to Azure DevOps Services and link Server readers to the other-code-forges page.
• src/content/docs/platform/integrations/azure-devops.mdx:13 — [NIT] Removing the meta-opener left two consecutive blank lines after the intro paragraph. Requested change: keep a single blank line so markdownlint passes.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/azure-devops.mdx:100 — [SUGGESTION] The sentence "Azure DevOps push events aren't currently available as automation triggers." documents a dormant trigger, which the PR description says the page deliberately doesn't expose, and it goes stale when the trigger ships. Requested change: remove the sentence, or confirm the push trigger should be mentioned.
• src/content/docs/factories/integrations/azure-devops.mdx:130 — [SUGGESTION] The cause "Azure DevOps hides the factory identity from @-mention autocomplete until the identity has been used in the organization" is stated as fact, but the cited Microsoft Learn pages cover identity picker behavior only generally. Requested change: confirm it against observed product behavior and cite the evidence under Source files consulted, or soften the cause and list it under ## Unverified claims with a VERIFY marker.
• src/content/docs/platform/integrations/azure-devops.mdx:33 — [NIT] The modified step reads "Under "Scopes," select Custom defined" while other-code-forges.mdx in this PR says "choose Custom defined" for the same control. Requested change: use "choose" for the option choice, as in 5. Under "Scopes," choose **Custom defined**, then select **Code** > **Read**.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/azure-devops.mdx:15 — [SUGGESTION] The Early Access :::note is not carried by the sibling GitHub, GitLab, and Jira factory integration pages. Requested change: drop the note or link to the factories overview so the integration pages stay consistent.
• src/content/docs/factories/integrations/azure-devops.mdx:60 — [NIT] "Next to the factory list, click +" does not name the control the way sibling pages do. Requested change: use "Click + next to Factories to create a factory."
• src/content/docs/factories/integrations/azure-devops.mdx:73 — [SUGGESTION] The default automations are mention-based and troubleshooting covers mention autocomplete, but the page never explains how to mention the factory (@ plus the factory identity name in a work item or pull request comment). Requested change: add a short section or sentence describing how to mention the factory so readers can test the default automation.
• src/content/docs/factories/integrations/azure-devops.mdx:116 — [SUGGESTION] The several-minutes propagation delay is stated in the connect procedure and again in this troubleshooting entry, and "An event doesn't start a run" repeats the creator-connection requirement already stated in Requirements and the automations section. Requested change: state each caveat once (fold the delay into the procedure step) and shorten the troubleshooting entries to a link back.
• src/content/docs/platform/integrations/azure-devops.mdx:15 — [SUGGESTION] The page still says Azure DevOps Server users should replace dev.azure.com with their server hostname in the clone command, but the Server clone URL this PR documents in other-code-forges.mdx is https://SERVER/COLLECTION/PROJECT/_git/REPO. Requested change: update the placeholder instruction so dev.azure.com/your-org becomes SERVER/COLLECTION, or point Server readers to the other-code-forges command.

Verdict

Approve with nits