From f7c77fbd0afd3983949e1e854027936df6f777da Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:47:07 +0000 Subject: [PATCH 01/15] docs: update Azure DevOps integration Co-Authored-By: Oz --- .../platform/integrations/azure-devops.mdx | 166 ++++++++---------- .../docs/platform/integrations/index.mdx | 3 +- 2 files changed, 80 insertions(+), 89 deletions(-) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 777101633..ccb72e7ad 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -1,131 +1,121 @@ --- -title: Azure DevOps integration +title: Connecting Azure DevOps to a factory sidebar: label: "Azure DevOps" description: >- - Connect cloud agents to Azure DevOps repos using personal access tokens - and Warp-managed secrets. + Connect Azure DevOps Services to a factory with dedicated identities, + repository access, and event-driven automations. --- 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. +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 identity for each factory instead of using a team member's credentials at runtime. -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. +{/* VERIFY: Confirm first-class Azure DevOps Services support is enabled in production before merging this documentation. */} :::note -This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances. +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. ::: ---- - -## Prerequisites - -* A Warp account (create an account at {VARS.WEB_APP_URL}) -* A repository hosted on Azure DevOps (cloud or self-hosted) -* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated +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/) with your own credentials and setup commands. ---- +## What the Azure DevOps integration does -## Step 1: Generate a personal access token +* **Repository access** - Select repositories from one Azure DevOps organization and project for the factory. +* **Dedicated runtime identity** - Give each factory its own Microsoft Entra application and service principal for Git and pull request operations. +* **Trigger** - Start factory runs from supported Azure DevOps work item and pull request events. +* **Scoped administration** - Approve one Warp-managed Azure DevOps Manager for an organization, then use it to provision identities for multiple factories. -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**. -6. Click **Create**. -7. Copy the token value immediately. Azure DevOps will not show it again. +## How identities and access work -:::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)**. -::: +The integration separates setup access from runtime access. The Manager is a Warp-managed, multitenant Microsoft Entra application. Approval creates its service principal in your tenant and adds it to the Azure DevOps organization. -:::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. -::: +| Identity | Purpose | Access | +| --- | --- | --- | +| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. | 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. | Owns only the Entra applications it creates. In Azure DevOps, it has Basic access and belongs to Project Collection Administrators. | +| Factory identity | Authenticates a factory's Git, pull request, work item, and automation operations. | Has Basic access, project visibility, Service Hooks access, work item 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. Warp configures workload identity federation, so the factory doesn't need a stored client secret. -## Step 2: Store the token as a Warp-managed secret +## Requirements -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. +* **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. +* **A Microsoft Entra administrator** - A Global Administrator or Privileged Role Administrator approves the Azure DevOps Manager. +* **An Azure DevOps administrator** - A Project Collection Administrator adds the Manager to the organization. -1. Run the following command: +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. -```bash -oz secret create --team AZURE_DEVOPS_TOKEN -``` +### Required administrator permissions -2. When prompted, paste the token. +| System | Administrator | What the administrator approves | +| --- | --- | --- | +| Microsoft Entra | Global Administrator or Privileged Role Administrator | The Azure DevOps Manager and its Microsoft Graph `Application.ReadWrite.OwnedBy` permission. This permission lets the Manager create applications and manage only applications it owns. | +| Azure DevOps | Project Collection Administrator | Basic access for the Manager and membership in the organization's Project Collection Administrators group. Warp uses the administrator's sign-in for this approval and doesn't retain it. | -The value is stored and encrypted, and cannot be retrieved after creation. +Tenant approval can be reused when you connect another Azure DevOps organization in the same Microsoft Entra tenant. Azure DevOps approval is required for each organization. -:::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. +:::caution +The Manager and each factory identity can each consume one Azure DevOps Basic seat. Check available licenses before connecting an organization or adding factories. ::: -If you need to update a secret value, run: - -```bash -oz secret update --team --value AZURE_DEVOPS_TOKEN -``` +## Connect Azure DevOps ---- - -## Step 3: 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. +Start from factory setup to connect your account, select repositories, and provision the runtime identity. -1. Run the following command: +1. Sign in to the {VARS.FACTORY_WEB_APP}. 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. -```bash -oz environment create \ - --name "my-azure-devops-env" \ - --docker-image \ - --setup-command 'git clone https://$AZURE_DEVOPS_TOKEN@dev.azure.com/your-org/your-project/_git/your-repo' \ - --setup-command 'cd your-repo && ' -``` - -:::caution -Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$AZURE_DEVOPS_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. -::: +When setup confirms that the identity is ready, the factory uses that identity for Azure DevOps operations. You can retry identity provisioning from the factory's settings if setup is interrupted. -2. Replace the following placeholders: - * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) - * `your-org` with your Azure DevOps organization name - * `your-project` with your Azure DevOps project name - * `your-repo` with your repository name - * For Azure DevOps Server (self-hosted), replace `dev.azure.com` with your server's hostname. - * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. +Workspace admins can also manage organization-level Managers in the Azure DevOps Managers section of the Admin Panel. Any active workspace member can complete or delegate Manager setup while creating a factory. -:::caution -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. -::: +## Configure Azure DevOps automations -3. Note the environment ID returned. You will need it in the next step. +An Azure DevOps automation starts a factory run when a supported event matches its filters. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. ---- +To add or change a trigger: -## Step 4: Test your environment +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 work item starts in the factory dashboard. -Before connecting to integrations, verify the environment works by running a one-off agent. +For general filter behavior, see [factory automations](/factories/automations/). -1. Run the following command, replacing `` with the environment ID from Step 3: +### Supported events and filters -```bash -oz agent run-cloud --environment --prompt "Your task here" -``` +| 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 | ---- +Azure DevOps push events aren't currently available as automation triggers. -## Next steps +## Troubleshooting -With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: +* **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. +* **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. +* **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. +* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. -* **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/). +## Related pages -:::note -Native support for opening Azure DevOps pull requests from agent-generated changes is planned as a future enhancement. -::: +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item. +* [Factory automations](/factories/automations/) - Configure triggers, filters, and routing. +* [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/index.mdx b/src/content/docs/platform/integrations/index.mdx index bd981d9e3..de684e873 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -36,6 +36,7 @@ Use the setup walkthrough below for a quick look at how environments connect to * [GitHub](/platform/integrations/github/) - Mention `@warp-agent` on issues, pull requests, and review comments to start agents that reply in the thread. * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events. * [GitLab](/platform/integrations/gitlab/) - Connect GitLab.com repos natively, or self-managed instances with tokens and Warp-managed secrets. -* [Bitbucket](/platform/integrations/bitbucket/) and [Azure DevOps](/platform/integrations/azure-devops/) - Connect repositories with tokens and Warp-managed secrets. +* [Azure DevOps](/platform/integrations/azure-devops/) - Connect hosted Azure DevOps Services repositories to a factory with dedicated identities and event-driven automations. +* [Bitbucket](/platform/integrations/bitbucket/) - Connect repositories with tokens and Warp-managed secrets. * [AWS, GCP, and other cloud providers](/platform/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor and review integration-triggered runs across your team by source, status, or creator. From bf39300f9f7f56a77602841efaa867f636e90cf0 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:58:51 +0000 Subject: [PATCH 02/15] docs: clarify Azure DevOps automation credentials Co-Authored-By: Oz --- .../docs/platform/integrations/azure-devops.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index ccb72e7ad..f036ed393 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -8,7 +8,7 @@ description: >- --- 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 identity for each factory instead of using a team member's credentials at runtime. +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 identity for each factory's Git and pull request operations. Automation dispatch separately requires the automation creator's active Azure DevOps connection. {/* VERIFY: Confirm first-class Azure DevOps Services support is enabled in production before merging this documentation. */} @@ -31,9 +31,9 @@ The integration separates setup access from runtime access. The Manager is a War | Identity | Purpose | Access | | --- | --- | --- | -| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. | Limited to resources your Azure DevOps user can read. | +| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. If you create an Azure DevOps automation, Warp also binds your connection when an event dispatches a run. | Limited to resources your Azure DevOps user can read. An automation requires its creator's active, correctly scoped connection; another user's connection can't replace it. | | Azure DevOps Manager | Creates and maintains factory identities in one Microsoft Entra tenant and Azure DevOps organization. | Owns only the Entra applications it creates. In Azure DevOps, it has Basic access and belongs to Project Collection Administrators. | -| Factory identity | Authenticates a factory's Git, pull request, work item, and automation operations. | Has Basic access, project visibility, Service Hooks access, work item access, and permissions on the selected repositories. | +| Factory identity | Authenticates the factory's Git and pull request operations after a run starts. | Has Basic access, project visibility, Service Hooks access, work item 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. Warp configures workload identity federation, so the factory doesn't need a stored client secret. @@ -42,6 +42,7 @@ Each factory identity consists of a separate Microsoft Entra application and ser * **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 Warp user who creates an Azure DevOps automation must keep their own Azure DevOps OAuth connection active and correctly scoped. Another user's connection can't be substituted when an event dispatches the automation. * **A Microsoft Entra administrator** - A Global Administrator or Privileged Role Administrator approves the Azure DevOps Manager. * **An Azure DevOps administrator** - A Project Collection Administrator adds the Manager to the organization. @@ -73,13 +74,13 @@ Start from factory setup to connect your account, select repositories, and provi 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 Azure DevOps operations. You can retry identity provisioning from the factory's settings if setup is interrupted. +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. Azure DevOps automations still require the automation creator's personal connection. Workspace admins can also manage organization-level Managers in the Azure DevOps Managers section of the Admin Panel. Any active workspace member can complete or delegate Manager setup while creating a factory. ## Configure Azure DevOps automations -An Azure DevOps automation starts a factory run when a supported event matches its filters. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. +An Azure DevOps automation starts a factory run when a supported event matches its filters. Before creating the run, Warp verifies and binds the automation creator's active Azure DevOps OAuth connection. A missing, revoked, under-scoped, or differently owned connection stops dispatch. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. To add or change a trigger: @@ -111,7 +112,7 @@ Azure DevOps push events aren't currently available as automation triggers. * **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. * **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. * **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. -* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. +* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must also have an active Azure DevOps OAuth connection with the required scopes; another user's connection can't replace it. ## Related pages From 127d9475c81393ea3016b48dbdc74e45315f9ba0 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 14:25:14 +0000 Subject: [PATCH 03/15] docs: add Azure DevOps identity troubleshooting Co-Authored-By: Oz --- .../platform/integrations/azure-devops.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index f036ed393..b87b14d7a 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -114,6 +114,24 @@ Azure DevOps push events aren't currently available as automation triggers. * **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. * **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must also have an active Azure DevOps OAuth connection with the required scopes; another user's connection can't replace it. +### Factory identity doesn't appear in comment mention autocomplete + +**Cause:** The Azure DevOps identity picker for work item comments filters service-principal identities from its normal search results. This is an Azure DevOps platform limitation that Warp can't change. Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata. + +**Solution:** Add the factory identity to Azure DevOps's recently used identity cache: + +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 and enter `@` followed by the factory identity's name. The identity may now appear in autocomplete. If you enter the name without autocomplete, confirm that Azure DevOps formats it as a mention instead of plain text. + +### `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. From cfb0f0717f3295bc72c9049ccb4ebc74de2380ee Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 17:55:24 +0000 Subject: [PATCH 04/15] docs: address Azure DevOps review feedback --- .../platform/integrations/azure-devops.mdx | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index b87b14d7a..6a9f3024f 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -8,7 +8,7 @@ description: >- --- 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 identity for each factory's Git and pull request operations. Automation dispatch separately requires the automation creator's active Azure DevOps connection. +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 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. */} @@ -20,29 +20,27 @@ The first-class integration supports hosted Azure DevOps Services at `dev.azure. ## What the Azure DevOps integration does -* **Repository access** - Select repositories from one Azure DevOps organization and project for the factory. -* **Dedicated runtime identity** - Give each factory its own Microsoft Entra application and service principal for Git and pull request operations. -* **Trigger** - Start factory runs from supported Azure DevOps work item and pull request events. -* **Scoped administration** - Approve one Warp-managed Azure DevOps Manager for an organization, then use it to provision identities for multiple factories. +* **Repository access** - Give factories access to selected Azure DevOps repositories from the factory UI. +* **Factory identity** - Give each factory its own native Microsoft Entra identity and service principal for Azure DevOps operations and Git attribution. +* **Trigger** - Start factory runs from Azure DevOps events such as pull requests, work item updates, and mentions of the factory identity. ## How identities and access work -The integration separates setup access from runtime access. The Manager is a Warp-managed, multitenant Microsoft Entra application. Approval creates its service principal in your tenant and adds it to the Azure DevOps organization. +Your personal Azure DevOps OAuth connection lets Warp list the organizations, projects, and repositories you can select during setup. When a run uses the creator's credentials, the connection also supplies the creator's Azure DevOps identity. The Azure DevOps Manager is a Warp-managed service account that creates and manages a dedicated service account identity for each factory. | Identity | Purpose | Access | | --- | --- | --- | -| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. If you create an Azure DevOps automation, Warp also binds your connection when an event dispatches a run. | Limited to resources your Azure DevOps user can read. An automation requires its creator's active, correctly scoped connection; another user's connection can't replace it. | +| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. It also supplies your identity when a run uses the creator's credentials. | 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. | Owns only the Entra applications it creates. In Azure DevOps, it 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, project visibility, Service Hooks access, work item 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. Warp configures workload identity federation, so the factory doesn't need a stored client secret. +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 Warp user who creates an Azure DevOps automation must keep their own Azure DevOps OAuth connection active and correctly scoped. Another user's connection can't be substituted when an event dispatches the automation. * **A Microsoft Entra administrator** - A Global Administrator or Privileged Role Administrator approves the Azure DevOps Manager. * **An Azure DevOps administrator** - A Project Collection Administrator adds the Manager to the organization. @@ -74,13 +72,13 @@ Start from factory setup to connect your account, select repositories, and provi 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. Azure DevOps automations still require the automation creator's personal connection. +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. Workspace admins can also manage organization-level Managers in the Azure DevOps Managers section of the Admin Panel. Any active workspace member can complete or delegate Manager setup while creating a factory. ## Configure Azure DevOps automations -An Azure DevOps automation starts a factory run when a supported event matches its filters. Before creating the run, Warp verifies and binds the automation creator's active Azure DevOps OAuth connection. A missing, revoked, under-scoped, or differently owned connection stops dispatch. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. +An Azure DevOps automation starts a factory run when a supported event matches its filters. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. To add or change a trigger: @@ -112,13 +110,13 @@ Azure DevOps push events aren't currently available as automation triggers. * **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. * **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. * **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. -* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must also have an active Azure DevOps OAuth connection with the required scopes; another user's connection can't replace it. +* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. ### Factory identity doesn't appear in comment mention autocomplete **Cause:** The Azure DevOps identity picker for work item comments filters service-principal identities from its normal search results. This is an Azure DevOps platform limitation that Warp can't change. Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata. -**Solution:** Add the factory identity to Azure DevOps's recently used identity cache: +**Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: 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 and enter `@` followed by the factory identity's name. The identity may now appear in autocomplete. If you enter the name without autocomplete, confirm that Azure DevOps formats it as a mention instead of plain text. From a551a6b1d3428eebb891fe06058cfb3464ad3a6d Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:05:29 +0000 Subject: [PATCH 05/15] docs: restore Azure DevOps automation prerequisite --- src/content/docs/platform/integrations/azure-devops.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 6a9f3024f..2615fcf67 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -41,6 +41,7 @@ Each factory identity consists of a separate Microsoft Entra application and ser * **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. * **A Microsoft Entra administrator** - A Global Administrator or Privileged Role Administrator approves the Azure DevOps Manager. * **An Azure DevOps administrator** - A Project Collection Administrator adds the Manager to the organization. @@ -78,7 +79,7 @@ Workspace admins can also manage organization-level Managers in the Azure DevOps ## Configure Azure DevOps automations -An Azure DevOps automation starts a factory run when a supported event matches its filters. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments. +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 add or change a trigger: @@ -110,7 +111,7 @@ Azure DevOps push events aren't currently available as automation triggers. * **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. * **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. * **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. -* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. +* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must have an active Azure DevOps OAuth connection with the required scopes. Reconnect that user's account if the connection is missing, revoked, under-scoped, or belongs to another user. ### Factory identity doesn't appear in comment mention autocomplete From 3726b8df5c70ffc33e9778ac267f792c908e64cf Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:23:20 +0000 Subject: [PATCH 06/15] docs: restore Azure DevOps Server setup guidance Co-Authored-By: Oz --- .../code-forges/other-code-forges.mdx | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx index 1f0d203b1..5112a2282 100644 --- 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](/platform/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,27 @@ 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 `CODE_FORGE_TOKEN` in [Grant the clone credential](#grant-the-clone-credential). When you add the runner setup command, use this Azure DevOps Server clone format: + +```bash +AZURE_DEVOPS_AUTH_HEADER="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64)" \ + git --config-env=http.extraheader=AZURE_DEVOPS_AUTH_HEADER clone \ + "https://SERVER/COLLECTION/PROJECT/_git/REPO" +``` + +Replace `SERVER` with your Azure DevOps Server hostname and `COLLECTION`, `PROJECT`, and `REPO` with the repository path. ## Create the factory without a repository From e01c3fc28ae82a89214f8375b3588d2b560239cb Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:35:55 +0000 Subject: [PATCH 07/15] docs: split Azure DevOps factory and cloud agent setup Co-Authored-By: Oz --- .../code-forges/other-code-forges.mdx | 21 +-- .../factories/integrations/azure-devops.mdx | 137 ++++++++++++++ .../platform/integrations/azure-devops.mdx | 169 ++++++++---------- .../docs/platform/integrations/index.mdx | 2 +- src/sidebar.ts | 1 + 5 files changed, 226 insertions(+), 104 deletions(-) create mode 100644 src/content/docs/factories/integrations/azure-devops.mdx diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx index 5112a2282..bb2d382dd 100644 --- 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 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](/platform/integrations/azure-devops/). For other code forges, 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. @@ -31,15 +31,7 @@ Before you create the factory, generate a personal access token for your Azure D 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 `CODE_FORGE_TOKEN` in [Grant the clone credential](#grant-the-clone-credential). When you add the runner setup command, use this Azure DevOps Server clone format: - -```bash -AZURE_DEVOPS_AUTH_HEADER="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64)" \ - git --config-env=http.extraheader=AZURE_DEVOPS_AUTH_HEADER clone \ - "https://SERVER/COLLECTION/PROJECT/_git/REPO" -``` - -Replace `SERVER` with your Azure DevOps Server hostname and `COLLECTION`, `PROJECT`, and `REPO` with the repository path. +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 @@ -71,6 +63,15 @@ 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 +git -c http.extraheader="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64)" \ + clone "https://SERVER/COLLECTION/PROJECT/_git/REPO" +``` + +Replace `SERVER` with your Azure DevOps Server hostname and `COLLECTION`, `PROJECT`, and `REPO` with the repository path. + 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 new file mode 100644 index 000000000..c9500ce5e --- /dev/null +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -0,0 +1,137 @@ +--- +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 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/). + +## What the Azure DevOps integration does + +* **Repository access** - Give factories access to selected Azure DevOps repositories from the factory UI. +* **Factory identity** - Give each factory its own native Microsoft Entra identity and service principal for Azure DevOps operations and Git attribution. +* **Trigger** - Start factory runs from Azure DevOps events such as pull requests, work item updates, and mentions of the factory identity. + +## How identities and access work + +Your personal Azure DevOps OAuth connection limits what appears during setup. The Azure DevOps Manager creates and manages a dedicated service account identity for each factory. + +| 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. | Owns only the Entra applications it creates. In Azure DevOps, it 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, project visibility, Service Hooks access, work item 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 each factory identity can each consume one Azure DevOps Basic seat. 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 {VARS.FACTORY_WEB_APP}. 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 add or change a trigger: + +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 | + +Azure DevOps push events aren't currently available as automation triggers. + +## Troubleshooting + +* **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. +* **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. +* **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. +* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must have an active Azure DevOps OAuth connection with the required scopes. Reconnect that user's account if the connection is missing, revoked, under-scoped, or belongs to another user. + +### Factory identity doesn't appear in comment mention autocomplete + +**Cause:** The Azure DevOps identity picker for work item comments filters service-principal identities from its normal search results. This is an Azure DevOps platform limitation that Warp can't change. Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata. + +**Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: + +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 and enter `@` followed by the factory identity's name. The identity may now appear in autocomplete. If you enter the name without autocomplete, confirm that Azure DevOps formats it as a mention instead of plain text. + +### `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 index 2615fcf67..27b05ebaa 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -1,139 +1,122 @@ --- -title: Connecting Azure DevOps to a factory +title: Azure DevOps integration sidebar: label: "Azure DevOps" description: >- - Connect Azure DevOps Services to a factory with dedicated identities, - repository access, and event-driven automations. + Connect cloud agents to Azure DevOps repos using personal access tokens + and Warp-managed secrets. --- 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 identity for each factory's Git and pull request operations. +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. -{/* VERIFY: Confirm first-class Azure DevOps Services support is enabled in production before merging this documentation. */} +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 -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/) with your own credentials and setup commands. +This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances. -## What the Azure DevOps integration does +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/). -* **Repository access** - Give factories access to selected Azure DevOps repositories from the factory UI. -* **Factory identity** - Give each factory its own native Microsoft Entra identity and service principal for Azure DevOps operations and Git attribution. -* **Trigger** - Start factory runs from Azure DevOps events such as pull requests, work item updates, and mentions of the factory identity. - -## How identities and access work +--- -Your personal Azure DevOps OAuth connection lets Warp list the organizations, projects, and repositories you can select during setup. When a run uses the creator's credentials, the connection also supplies the creator's Azure DevOps identity. The Azure DevOps Manager is a Warp-managed service account that creates and manages a dedicated service account identity for each factory. +## Prerequisites -| Identity | Purpose | Access | -| --- | --- | --- | -| Your connected Azure DevOps account | Lists the organizations, projects, and repositories you can choose during setup. It also supplies your identity when a run uses the creator's credentials. | 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. | Owns only the Entra applications it creates. In Azure DevOps, it 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, project visibility, Service Hooks access, work item access, and permissions on the selected repositories. | +* **Warp account** - Create an account in the {VARS.WEB_APP}. +* **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/). -Each factory identity consists of a separate Microsoft Entra application and service principal that Warp adds to Azure DevOps. +--- -## Requirements +## Step 1: Generate a personal access token -* **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. -* **A Microsoft Entra administrator** - A Global Administrator or Privileged Role Administrator approves the Azure DevOps Manager. -* **An Azure DevOps administrator** - A Project Collection Administrator adds the Manager to the organization. +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**. +6. Click **Create**. +7. Copy the token value immediately. Azure DevOps will not show it again. -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. +**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)**. -### Required administrator permissions +For Azure DevOps Server (self-hosted), sign in at `https://{server}/{collection}` instead of `dev.azure.com`. The token creation steps are the same. -| System | Administrator | What the administrator approves | -| --- | --- | --- | -| Microsoft Entra | Global Administrator or Privileged Role Administrator | The Azure DevOps Manager and its Microsoft Graph `Application.ReadWrite.OwnedBy` permission. This permission lets the Manager create applications and manage only applications it owns. | -| Azure DevOps | Project Collection Administrator | Basic access for the Manager and membership in the organization's Project Collection Administrators group. Warp uses the administrator's sign-in for this approval and doesn't retain it. | +--- -Tenant approval can be reused when you connect another Azure DevOps organization in the same Microsoft Entra tenant. Azure DevOps approval is required for each organization. +## Step 2: Store the token as a Warp-managed secret -:::caution -The Manager and each factory identity can each consume one Azure DevOps Basic seat. Check available licenses before connecting an organization or adding factories. -::: +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. -## Connect Azure DevOps +1. Run the following command: -Start from factory setup to connect your account, select repositories, and provision the runtime identity. +```bash +oz secret create --team AZURE_DEVOPS_TOKEN +``` -1. Sign in to the {VARS.FACTORY_WEB_APP}. 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. +2. When prompted, paste the token. -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. +The value is stored and encrypted, and cannot be retrieved after creation. -Workspace admins can also manage organization-level Managers in the Azure DevOps Managers section of the Admin Panel. Any active workspace member can complete or delegate Manager setup while creating a factory. +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. -## Configure Azure DevOps automations +If you need to update a secret value, run: -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. +```bash +oz secret update --team --value AZURE_DEVOPS_TOKEN +``` -To add or change a trigger: +--- -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 work item starts in the factory dashboard. +## Step 3: Create an environment with a clone setup command -For general filter behavior, see [factory automations](/factories/automations/). +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. -### Supported events and filters +1. Run the following command: -| 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 | +```bash +oz environment create \ + --name "my-azure-devops-env" \ + --docker-image \ + --setup-command 'AUTH_HEADER=$(printf ":%s" "$AZURE_DEVOPS_TOKEN" | base64) && 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 && ' +``` -Azure DevOps push events aren't currently available as automation triggers. +:::caution +Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$AZURE_DEVOPS_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. +::: -## Troubleshooting +2. Replace the following placeholders: + * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) + * `your-org` with your Azure DevOps organization name + * `your-project` with your Azure DevOps project name + * `your-repo` with your repository name + * For Azure DevOps Server (self-hosted), replace `dev.azure.com` with your server's hostname. + * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. -* **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. -* **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. -* **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. -* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must have an active Azure DevOps OAuth connection with the required scopes. Reconnect that user's account if the connection is missing, revoked, under-scoped, or belongs to another user. +:::caution +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. +::: -### Factory identity doesn't appear in comment mention autocomplete +3. Note the environment ID returned. You will need it in the next step. -**Cause:** The Azure DevOps identity picker for work item comments filters service-principal identities from its normal search results. This is an Azure DevOps platform limitation that Warp can't change. Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata. +--- -**Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: +## Step 4: Test your environment -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 and enter `@` followed by the factory identity's name. The identity may now appear in autocomplete. If you enter the name without autocomplete, confirm that Azure DevOps formats it as a mention instead of plain text. +Before connecting to integrations, verify the environment works by running a one-off agent. -### `The identity value 'X' for field 'Assigned To' is an unknown identity.` +1. Run the following command, replacing `` with the environment ID from Step 3: -**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. +```bash +oz agent run-cloud --environment --prompt "Your task here" +``` -**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. +## Next steps -## Related pages +With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: -* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item. -* [Factory automations](/factories/automations/) - Configure triggers, filters, and routing. -* [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. +* **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/). +* **Warp Factories** — Connect hosted Azure DevOps Services with dedicated identities and event triggers. See the [Azure DevOps factory integration](/factories/integrations/azure-devops/). diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index de684e873..cc3555c9c 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -36,7 +36,7 @@ Use the setup walkthrough below for a quick look at how environments connect to * [GitHub](/platform/integrations/github/) - Mention `@warp-agent` on issues, pull requests, and review comments to start agents that reply in the thread. * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events. * [GitLab](/platform/integrations/gitlab/) - Connect GitLab.com repos natively, or self-managed instances with tokens and Warp-managed secrets. -* [Azure DevOps](/platform/integrations/azure-devops/) - Connect hosted Azure DevOps Services repositories to a factory with dedicated identities and event-driven automations. +* [Azure DevOps](/platform/integrations/azure-devops/) - Connect standalone cloud agents with personal access tokens and Warp-managed secrets. * [Bitbucket](/platform/integrations/bitbucket/) - Connect repositories with tokens and Warp-managed secrets. * [AWS, GCP, and other cloud providers](/platform/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor and review integration-triggered runs across your team by source, status, or creator. diff --git a/src/sidebar.ts b/src/sidebar.ts index f621edc47..311648ee9 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -425,6 +425,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // separately from the services that route work into a factory. { slug: 'factories/integrations/github', label: 'GitHub' }, { slug: 'factories/integrations/gitlab', label: 'GitLab' }, + { slug: 'factories/integrations/azure-devops', label: 'Azure DevOps' }, { slug: 'factories/code-forges/other-code-forges', label: 'Other code forges' }, ], }, From acfc670c71775f08521f2d68fc50568b7de10a93 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:36:28 +0000 Subject: [PATCH 08/15] docs: align standalone Azure DevOps setup style Co-Authored-By: Oz --- .../docs/platform/integrations/azure-devops.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 27b05ebaa..b879d0c8f 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -10,7 +10,6 @@ import { VARS } from '@data/vars'; 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. This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances. @@ -26,13 +25,13 @@ To connect hosted Azure DevOps Services to a factory with event-driven automatio --- -## 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," select **Custom defined**, then select **Code** > **Read**. 6. Click **Create**. 7. Copy the token value immediately. Azure DevOps will not show it again. @@ -42,7 +41,7 @@ For Azure DevOps Server (self-hosted), sign in at `https://{server}/{collection} --- -## 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. @@ -66,7 +65,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. @@ -96,15 +95,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 `` with the environment ID from Step 3: +1. Run the following command, replacing `` with the environment ID from the previous section: ```bash oz agent run-cloud --environment --prompt "Your task here" From 259d895cbe4e2337f49c36c7555cfbdb06f245e8 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:48:38 +0000 Subject: [PATCH 09/15] docs: prevent wrapped Azure DevOps auth headers Co-Authored-By: Oz --- src/content/docs/factories/code-forges/other-code-forges.mdx | 2 +- src/content/docs/platform/integrations/azure-devops.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx index bb2d382dd..b30215afb 100644 --- a/src/content/docs/factories/code-forges/other-code-forges.mdx +++ b/src/content/docs/factories/code-forges/other-code-forges.mdx @@ -66,7 +66,7 @@ Use your code forge's documented clone format. For example, Bitbucket Cloud requ For Azure DevOps Server, add this setup command: ```bash -git -c http.extraheader="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64)" \ +git -c http.extraheader="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64 | tr -d '\n')" \ clone "https://SERVER/COLLECTION/PROJECT/_git/REPO" ``` diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index b879d0c8f..73fb3f49a 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -75,7 +75,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 \ - --setup-command 'AUTH_HEADER=$(printf ":%s" "$AZURE_DEVOPS_TOKEN" | base64) && git -c "http.extraheader=Authorization: Basic $AUTH_HEADER" clone https://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 && ' ``` From fe3fa251c24b5e207a770385b6eb677db0ee5cd6 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 19:31:55 +0000 Subject: [PATCH 10/15] docs: clarify Azure DevOps troubleshooting Co-Authored-By: Oz --- .../factories/integrations/azure-devops.mdx | 30 +++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx index c9500ce5e..2568b0a25 100644 --- a/src/content/docs/factories/integrations/azure-devops.mdx +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -105,10 +105,29 @@ Azure DevOps push events aren't currently available as automation triggers. ## Troubleshooting -* **An organization, project, or repository doesn't appear** - Confirm that your connected Azure DevOps user can read it, then refresh the connection. -* **Manager approval can't continue** - Complete the Microsoft Entra step before the Azure DevOps step. If another administrator completed the first step, reopen the setup link. -* **Identity provisioning remains in progress** - Microsoft Entra and Azure DevOps permission changes can take several minutes to propagate. Retry from the factory's settings if the setup reports an error. -* **An event doesn't start a run** - Confirm the automation is enabled and that every configured filter matches the Azure DevOps event. The user who created the automation must have an active Azure DevOps OAuth connection with the required scopes. Reconnect that user's account if the connection is missing, revoked, under-scoped, or belongs to another user. +### 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 @@ -117,7 +136,8 @@ Azure DevOps push events aren't currently available as automation triggers. **Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: 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 and enter `@` followed by the factory identity's name. The identity may now appear in autocomplete. If you enter the name without autocomplete, confirm that Azure DevOps formats it as a mention instead of plain text. +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.` From c173ff269d8944978dbaaa13f0ba58b77fa4e7a6 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 19:55:16 +0000 Subject: [PATCH 11/15] ci: retry cancelled CodeQL checks Co-Authored-By: Oz From 6851db6dc356285c46845b68a82caa8f16611f74 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 00:18:17 +0000 Subject: [PATCH 12/15] docs: address final Azure DevOps feedback Co-Authored-By: Oz --- .../factories/code-forges/other-code-forges.mdx | 8 +++++--- .../docs/factories/integrations/azure-devops.mdx | 14 ++++++++------ 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx index b30215afb..210e8e9aa 100644 --- a/src/content/docs/factories/code-forges/other-code-forges.mdx +++ b/src/content/docs/factories/code-forges/other-code-forges.mdx @@ -66,11 +66,13 @@ Use your code forge's documented clone format. For example, Bitbucket Cloud requ For Azure DevOps Server, add this setup command: ```bash -git -c http.extraheader="Authorization: Basic $(printf ':%s' "$CODE_FORGE_TOKEN" | base64 | tr -d '\n')" \ - clone "https://SERVER/COLLECTION/PROJECT/_git/REPO" +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. +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. diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx index 2568b0a25..ee2b7fe89 100644 --- a/src/content/docs/factories/integrations/azure-devops.mdx +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -26,13 +26,13 @@ The first-class integration supports hosted Azure DevOps Services at `dev.azure. ## How identities and access work -Your personal Azure DevOps OAuth connection limits what appears during setup. The Azure DevOps Manager creates and manages a dedicated service account identity for each factory. +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. | Owns only the Entra applications it creates. In Azure DevOps, it 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, project visibility, Service Hooks access, work item access, and permissions on the selected repositories. | +| 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. @@ -56,7 +56,7 @@ The Microsoft Entra and Azure DevOps approvals can be completed by different peo Reuse tenant approval for another Azure DevOps organization in the same Microsoft Entra tenant. Each organization requires Azure DevOps approval. :::caution -The Manager and each factory identity can each consume one Azure DevOps Basic seat. Check available licenses before connecting an organization or adding factories. +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 @@ -78,7 +78,9 @@ When setup confirms that the identity is ready, the factory uses that identity f 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 add or change a trigger: +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. @@ -131,7 +133,7 @@ Azure DevOps push events aren't currently available as automation triggers. ### Factory identity doesn't appear in comment mention autocomplete -**Cause:** The Azure DevOps identity picker for work item comments filters service-principal identities from its normal search results. This is an Azure DevOps platform limitation that Warp can't change. Warp can detect the factory identity after Azure DevOps saves the comment with the identity's mention metadata. +**Cause:** Azure DevOps hides the factory identity from @-mention autocomplete until the identity has been used in the organization. **Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: From 8caa5bacada494fb1d193b2eedbad3aa801b65d0 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 00:24:44 +0000 Subject: [PATCH 13/15] docs: tighten Azure DevOps guidance Co-Authored-By: Oz --- .../docs/factories/integrations/azure-devops.mdx | 10 ++-------- .../docs/platform/integrations/azure-devops.mdx | 1 - 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx index ee2b7fe89..1b569d2b7 100644 --- a/src/content/docs/factories/integrations/azure-devops.mdx +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -8,7 +8,7 @@ description: >- --- 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 identity for each factory's Git and pull request operations. +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. */} @@ -18,12 +18,6 @@ Warp Factories is in Early Access and available to a limited set of teams. [Requ 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/). -## What the Azure DevOps integration does - -* **Repository access** - Give factories access to selected Azure DevOps repositories from the factory UI. -* **Factory identity** - Give each factory its own native Microsoft Entra identity and service principal for Azure DevOps operations and Git attribution. -* **Trigger** - Start factory runs from Azure DevOps events such as pull requests, work item updates, and mentions of the factory identity. - ## 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. @@ -135,7 +129,7 @@ Azure DevOps push events aren't currently available as automation triggers. **Cause:** Azure DevOps hides the factory identity from @-mention autocomplete until the identity has been used in the organization. -**Workaround:** Add the factory identity to Azure DevOps's recently used identity cache: +**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. diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 73fb3f49a..67fad5797 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -10,7 +10,6 @@ import { VARS } from '@data/vars'; 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 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/). From 3b957b18aace325fe017c64bb8cc22e5d5ee22ac Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 00:30:13 +0000 Subject: [PATCH 14/15] docs: finalize Azure DevOps copy Co-Authored-By: Oz --- src/content/docs/factories/integrations/azure-devops.mdx | 4 +--- src/content/docs/platform/integrations/azure-devops.mdx | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx index 1b569d2b7..ae6a41525 100644 --- a/src/content/docs/factories/integrations/azure-devops.mdx +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -97,8 +97,6 @@ For general filter behavior, see [factory automations](/factories/automations/). | Pull request commented | Repository and target branches | | Mentioned in a pull request | Repository and mentioned users | -Azure DevOps push events aren't currently available as automation triggers. - ## Troubleshooting ### An organization, project, or repository doesn't appear @@ -127,7 +125,7 @@ Azure DevOps push events aren't currently available as automation triggers. ### Factory identity doesn't appear in comment mention autocomplete -**Cause:** Azure DevOps hides the factory identity from @-mention autocomplete until the identity has been used in the organization. +**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: diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 67fad5797..9560d4e62 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -30,7 +30,7 @@ To connect hosted Azure DevOps Services to a factory with event-driven automatio 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. From 6c80b62f1b95ddc449d1a83168ff3d3039aa5f55 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 00:35:47 +0000 Subject: [PATCH 15/15] docs: align Azure DevOps setup paths Co-Authored-By: Oz --- .../docs/factories/integrations/azure-devops.mdx | 14 +++++--------- .../docs/platform/integrations/azure-devops.mdx | 2 +- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx index ae6a41525..971aa875f 100644 --- a/src/content/docs/factories/integrations/azure-devops.mdx +++ b/src/content/docs/factories/integrations/azure-devops.mdx @@ -57,7 +57,7 @@ The Manager and every factory identity use one Azure DevOps Basic seat each. Che Start from factory setup to connect your account, select repositories, and provision the runtime identity. -1. Sign in to the {VARS.FACTORY_WEB_APP}. Next to the factory list, click **+** to create a factory. +1. Sign in to the {VARS.FACTORY_WEB_APP}. Click **+** next to **Factories** 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. @@ -80,6 +80,8 @@ To add or change a trigger in the factory dashboard: 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. +To test a default mention automation, enter `@` followed by the factory identity's name in a work item or pull request comment, then select the identity from autocomplete. + For general filter behavior, see [factory automations](/factories/automations/). ### Supported events and filters @@ -111,17 +113,11 @@ For general filter behavior, see [factory automations](/factories/automations/). **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. +**Cause:** The automation is disabled or a filter doesn't match. -**Solution:** Enable the automation, check every filter, and reconnect its creator's Azure DevOps account with the required scopes. +**Solution:** Enable the automation and check every filter. If both are correct, confirm the [automation creator's Azure DevOps connection](#requirements). ### Factory identity doesn't appear in comment mention autocomplete diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 9560d4e62..13c3c1ce9 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -87,7 +87,7 @@ Use single quotes around setup commands that reference secrets. Double quotes ca * `your-org` with your Azure DevOps organization name * `your-project` with your Azure DevOps project name * `your-repo` with your repository name - * For Azure DevOps Server (self-hosted), replace `dev.azure.com` with your server's hostname. + * For Azure DevOps Server (self-hosted), replace `dev.azure.com/your-org` with `SERVER/COLLECTION`, using your server's hostname and collection name. * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. :::caution