hongyi-chen · Oct 6, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx
@@ -8,7 +8,7 @@ sidebar:
 ---
 import { VARS } from '@data/vars';
 
-Connect your factory to a repository on Bitbucket, Azure DevOps, self-managed GitLab, or another code forge without first-class factory support. You can create the factory with no connected repository, then clone the repository from its default runner.
+Connect your factory to a repository on Bitbucket, Azure DevOps Server, self-managed GitLab, or another code forge without first-class factory support. Hosted Azure DevOps Services repositories use the [first-class Azure DevOps integration](/factories/integrations/azure-devops/). For other code forges, create the factory with no connected repository, then clone the repository from its default runner.
 
 :::caution
 This setup gives factory agents repository access. It does not add provider-specific events or automations for the code forge.
@@ -19,7 +19,19 @@ This setup gives factory agents repository access. It does not add provider-spec
 * **Factory access** - Permission to create the factory, add Agent Secrets, and edit its default runner.
 * **Repository access** - An HTTPS clone URL and a token that can read the repository.
 
-For provider-specific token and clone formats, see [Bitbucket repository access](/platform/integrations/bitbucket/), [Azure DevOps repository access](/platform/integrations/azure-devops/), or [self-managed GitLab repository access](/platform/integrations/gitlab/#self-managed-gitlab-instances).
+For provider-specific token and clone formats, see [Bitbucket repository access](/platform/integrations/bitbucket/) or [self-managed GitLab repository access](/platform/integrations/gitlab/#self-managed-gitlab-instances).
+
+### Azure DevOps Server credentials
+
+Before you create the factory, generate a personal access token for your Azure DevOps Server repository:
+
+1. Sign in to your Azure DevOps Server instance at `https://SERVER/COLLECTION`.
+2. Click the user settings icon, then click **Personal access tokens**.
+3. Click **+ New Token**, then enter a name and choose an expiration date.
+4. Under "Scopes," choose **Custom defined**, then select **Code** > **Read**. Select **Code** > **Read & Write** instead if agents need to push commits.
+5. Click **Create**, then copy the token. Azure DevOps doesn't show it again.
+
+Store this token as the `CODE_FORGE_TOKEN` Agent Secret by following [Grant the clone credential](#grant-the-clone-credential).
 
 ## Create the factory without a repository
 
@@ -51,6 +63,17 @@ Runner setup commands prepare each agent workspace before factory work starts.
 
 Use your code forge's documented clone format. For example, Bitbucket Cloud requires the `x-bitbucket-api-token-auth` username, while other hosts use a different username or authorization header.
 
+For Azure DevOps Server, add this setup command:
+
+```bash
+if [ ! -d "REPO/.git" ]; then
+  git -c http.extraheader="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64 | tr -d '\n')" \
+    clone "https://SERVER/COLLECTION/PROJECT/_git/REPO" "REPO"
+fi
+```
+
+Replace `SERVER` with your Azure DevOps Server hostname and `COLLECTION`, `PROJECT`, and `REPO` with the repository path and local directory name.
+
 Setup commands run each time the runner prepares a workspace. Make the commands safe to run repeatedly.
 
 ## Test repository access

diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx
@@ -0,0 +1,151 @@
+---
+title: Connect Azure DevOps to your factory
+sidebar:
+  label: "Azure DevOps"
+description: >-
+  Connect Azure DevOps Services to a factory with dedicated identities,
+  repository access, and event-driven automations.
+---
+import { VARS } from '@data/vars';
+
+Connect Azure DevOps Services to a factory so agents can work in selected repositories, open pull requests, and start runs from work item and pull request events. Warp creates a dedicated Microsoft Entra identity for each factory's Git and pull request operations.
+
+{/* VERIFY: Confirm first-class Azure DevOps Services support is enabled in production before merging this documentation. */}
+
+:::note
+Warp Factories is in Early Access and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team.
+:::
+
+The first-class integration supports hosted Azure DevOps Services at `dev.azure.com`. It doesn't support Azure DevOps Server. To use a self-hosted Azure DevOps Server repository, [configure it as another code forge](/factories/code-forges/other-code-forges/). For standalone cloud agent environments, use the [Azure DevOps access token setup](/platform/integrations/azure-devops/).
+
+## How identities and access work
+
+Your personal Azure DevOps OAuth connection limits what appears during setup. The Azure DevOps Manager creates and manages each factory identity.
+
+| Identity | Purpose | Access |
+| --- | --- | --- |
+| Your connected Azure DevOps account | Lists resources during setup and supplies your identity for creator-based runs. | Limited to resources your Azure DevOps user can read. |
+| Azure DevOps Manager | Creates and maintains factory identities in one Microsoft Entra tenant and Azure DevOps organization. | Has Basic access and belongs to Project Collection Administrators. |
+| Factory identity | Authenticates the factory's Git and pull request operations after a run starts. | Has Basic access and permissions on the selected repositories. |
+
+Each factory identity consists of a separate Microsoft Entra application and service principal that Warp adds to Azure DevOps.
+
+## Requirements
+
+* **A Warp team with Warp Factories access** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/).
+* **An Azure DevOps Services organization** - Use an organization hosted at `dev.azure.com`, with the project and repositories the factory needs.
+* **A connected Azure DevOps user** - Connect a user who can read the organization, project, and repositories you want to select.
+* **An active connection for each automation creator** - The user who creates an Azure DevOps automation must keep their own Azure DevOps OAuth connection active with the required scopes.
+* **Microsoft Entra and Azure DevOps administrators** - Administrators with the roles listed below approve and add the Manager.
+
+The Microsoft Entra and Azure DevOps approvals can be completed by different people. A setup link lets each administrator complete their step without a Warp account.
+
+### Required administrator permissions
+
+| System | Administrator | What the administrator approves |
+| --- | --- | --- |
+| Microsoft Entra | Global Administrator or Privileged Role Administrator | The Manager's Microsoft Graph `Application.ReadWrite.OwnedBy` permission, limited to applications the Manager owns. |
+| Azure DevOps | Project Collection Administrator | Basic access and Project Collection Administrators membership. Warp doesn't retain the administrator's sign-in. |
+
+Reuse tenant approval for another Azure DevOps organization in the same Microsoft Entra tenant. Each organization requires Azure DevOps approval.
+
+:::caution
+The Manager and every factory identity use one Azure DevOps Basic seat each. Check available licenses before connecting an organization or adding factories.
+:::
+
+## Connect Azure DevOps
+
+Start from factory setup to connect your account, select repositories, and provision the runtime identity.
+
+1. Sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. Next to the factory list, click **+** to create a factory.
+2. In the code host step, find the Azure DevOps row and click **Connect**. Complete the Microsoft sign-in to connect your Azure DevOps user.
+3. Choose an Azure DevOps organization and project, then select the repositories the factory will use. Only resources your connected user can read appear.
+4. If the organization already has an active Azure DevOps Manager, continue setup. Otherwise, connect the Manager yourself or send the setup link to the required administrators.
+5. Complete the Manager approval in this order:
+   1. A Global Administrator or Privileged Role Administrator completes the Microsoft Entra approval.
+   2. A Project Collection Administrator completes the Azure DevOps approval.
+6. Continue factory setup. Warp creates the factory identity, adds Azure DevOps Basic access, and grants access to the selected repositories. Microsoft and Azure DevOps can take several minutes to apply these changes.
+
+When setup confirms that the identity is ready, the factory uses that identity for Git and pull request operations. You can retry identity provisioning from the factory's settings if setup is interrupted.
+
+## Configure Azure DevOps automations
+
+An Azure DevOps automation starts a factory run when a supported event matches its filters. Before starting a run, Warp checks the automation creator's Azure DevOps connection. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments.
+
+To configure an automation as code, ask the Warp Agent to update the factory definition or edit its `automations/` files directly. See [definitions as code](/factories/factory-as-code/).
+
+To add or change a trigger in the factory dashboard:
+
+1. In the factory dashboard, open **Automations**, then create an automation or edit an existing one.
+2. Add an Azure DevOps trigger, then choose an event and its filters.
+3. Click **Save**. Perform a matching action in Azure DevOps and confirm that a run starts in the factory dashboard.
+
+For general filter behavior, see [factory automations](/factories/automations/).
+
+### Supported events and filters
+
+| Azure DevOps event | Available filters |
+| --- | --- |
+| Work item created | Work item types, labels, assignees, and authors |
+| Work item assigned | Work item types, labels, assignees, and authors |
+| Work item labeled | Work item types, labels, assignees, and authors |
+| Mentioned in a work item | Mentioned users |
+| Pull request created | Repository and target branches |
+| Pull request merged | Repository and target branches |
+| Pull request closed | Repository and target branches |
+| Pull request updated | Repository and target branches |
+| Pull request commented | Repository and target branches |
+| Mentioned in a pull request | Repository and mentioned users |
+
+## Troubleshooting
+
+### An organization, project, or repository doesn't appear
+
+**Cause:** Your Azure DevOps user lacks access to the resource.
+
+**Solution:** Grant the user access, then refresh the connection.
+
+### Manager approval can't continue
+
+**Cause:** The Microsoft Entra approval is incomplete.
+
+**Solution:** Complete the Microsoft Entra step before the Azure DevOps step. Reopen the setup link if another administrator completed the first step.
+
+### Identity provisioning remains in progress
+
+**Cause:** Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate.
+
+**Solution:** Wait, then retry from the factory's settings if setup reports an error.
+
+### An event doesn't start a run
+
+**Cause:** The automation is disabled, a filter doesn't match, or its creator's Azure DevOps OAuth connection is missing, revoked, or under-scoped.
+
+**Solution:** Enable the automation, check every filter, and reconnect its creator's Azure DevOps account with the required scopes.
+
+### Factory identity doesn't appear in comment mention autocomplete
+
+**Cause:** Azure DevOps doesn't yet recognize the factory identity for comment autocomplete.
+
+**Workaround:** Make Azure DevOps recognize the factory identity by using it once in the organization:
+
+1. In the Azure DevOps organization and project connected to the factory, assign the factory identity to a work item and save the work item.
+2. Return to the comment, enter `@` followed by the factory identity's name, then select the identity from autocomplete.
+3. Confirm that Azure DevOps formats the selection as a mention. Plain text with the same name doesn't trigger the automation.
+
+### `The identity value 'X' for field 'Assigned To' is an unknown identity.`
+
+**Cause:** Azure DevOps can't resolve the factory identity for the current work item. This can happen when the work item is outside the organization or project configured for the factory.
+
+**Solution:**
+
+1. In the factory's settings, confirm its Azure DevOps organization and project.
+2. In Azure DevOps, open the work item from that organization and project, then assign the factory identity again.
+
+## Related pages
+
+* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item.
+* [Factory automations](/factories/automations/) - Configure triggers, filters, and routing.
+* [Azure DevOps access for standalone cloud agents](/platform/integrations/azure-devops/) - Configure a PAT, Warp-managed secret, and environment clone command.
+* [Other code forges](/factories/code-forges/other-code-forges/) - Connect repositories that don't have a first-class integration, including Azure DevOps Server.
+* [Infrastructure and security](/factories/infrastructure-and-security/) - Review how factories handle execution, credentials, and access.
diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx
@@ -8,45 +8,39 @@ description: >-
 ---
 import { VARS } from '@data/vars';
 
-Cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any {VARS.WARP_AUTOMATION_PLATFORM} trigger—Slack, Linear, schedules, or the CLI.
+Cloud agents work with any Git repository, including those hosted on Azure DevOps. For a standalone cloud agent environment, grant access with a personal access token and Warp-managed secrets. Once configured, the environment works with any {VARS.WARP_AUTOMATION_PLATFORM} trigger—Slack, Linear, schedules, or the CLI.
 
-This page explains how to generate an Azure DevOps personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime.
-
-:::note
 This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances.
-:::
+
+To connect hosted Azure DevOps Services to a factory with event-driven automations, use the [Azure DevOps factory integration](/factories/integrations/azure-devops/). For an Azure DevOps Server factory, use the [other code forges setup](/factories/code-forges/other-code-forges/).
 
 ---
 
 ## Prerequisites
 
-* A Warp account (<a href={VARS.WEB_APP_URL}>create an account at {VARS.WEB_APP_URL}</a>)
-* A repository hosted on Azure DevOps (cloud or self-hosted)
-* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated
+* **Warp account** - <a href={VARS.WEB_APP_URL}>Create an account in the {VARS.WEB_APP}</a>.
+* **Azure DevOps repository** - Use a repository hosted on Azure DevOps Services or Azure DevOps Server.
+* **{VARS.WARP_AGENT_CLI}** - [Install and authenticate the CLI](/reference/cli/).
 
 ---
 
-## Step 1: Generate a personal access token
+## Generate a personal access token
 
 1. Sign in to your Azure DevOps organization at `dev.azure.com/{your-org}`.
 2. Click the user settings icon (gear) in the top-right corner, then click **Personal access tokens**.
 3. Click **+ New Token**.
 4. Enter a descriptive name for the token (e.g. `warp-oz-agent`), choose the organization it applies to, and set an expiration date that matches your team's rotation policy.
-5. Under **Scopes**, select **Custom defined**, then select **Code** > **Read**.
+5. Under "Scopes," choose **Custom defined**, then select **Code** > **Read**.
 6. Click **Create**.
 7. Copy the token value immediately. Azure DevOps will not show it again.
 
-:::note
 **Code (Read)** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open pull requests, you will also need **Code (Read & Write)**.
-:::
 
-:::note
 For Azure DevOps Server (self-hosted), sign in at `https://{server}/{collection}` instead of `dev.azure.com`. The token creation steps are the same.
-:::
 
 ---
 
-## Step 2: Store the token as a Warp-managed secret
+## Store the token as a Warp-managed secret
 
 Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets.
 
@@ -60,9 +54,7 @@ oz secret create --team AZURE_DEVOPS_TOKEN
 
 The value is stored and encrypted, and cannot be retrieved after creation.
 
-:::note
 Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own Azure DevOps token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist.
-:::
 
 If you need to update a secret value, run:
 
@@ -72,7 +64,7 @@ oz secret update --team --value AZURE_DEVOPS_TOKEN
 
 ---
 
-## Step 3: Create an environment with a clone setup command
+## Create an environment with a clone setup command
 
 Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your Azure DevOps repo via a setup command instead.
 
@@ -82,7 +74,7 @@ Create an environment that uses your token to clone the repository at the start
 oz environment create \
   --name "my-azure-devops-env" \
   --docker-image <image> \
-  --setup-command 'git clone https://$AZURE_DEVOPS_TOKEN@dev.azure.com/your-org/your-project/_git/your-repo' \
+  --setup-command 'AUTH_HEADER=$(printf ":%s" "$AZURE_DEVOPS_TOKEN" | base64 | tr -d "\n") && git -c "http.extraheader=Authorization: Basic $AUTH_HEADER" clone https://dev.azure.com/your-org/your-project/_git/your-repo' \
   --setup-command 'cd your-repo && <install dependencies>'
 ```
 
@@ -102,15 +94,15 @@ Use single quotes around setup commands that reference secrets. Double quotes ca
 Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance.
 :::
 
-3. Note the environment ID returned. You will need it in the next step.
+3. Note the environment ID returned. You will need it to test the environment.
 
 ---
 
-## Step 4: Test your environment
+## Test the environment
 
 Before connecting to integrations, verify the environment works by running a one-off agent.
 
-1. Run the following command, replacing `<ENV_ID>` with the environment ID from Step 3:
+1. Run the following command, replacing `<ENV_ID>` with the environment ID from the previous section:
 
 ```bash
 oz agent run-cloud --environment <ENV_ID> --prompt "Your task here"
@@ -125,7 +117,4 @@ With your environment configured, you can connect it to any Warp trigger exactly
 * **Slack** — Tag **@warp** in a message to start an agent run against your Azure DevOps repo. See [Slack](/platform/integrations/slack/).
 * **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/).
 * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/).
-
-:::note
-Native support for opening Azure DevOps pull requests from agent-generated changes is planned as a future enhancement.
-:::
+* **Warp Factories** — Connect hosted Azure DevOps Services with dedicated identities and event triggers. See the [Azure DevOps factory integration](/factories/integrations/azure-devops/).