agent-swarm.devagent-swarm.dev
Integrations

Azure DevOps Integration

Connect Azure Repos and Azure Boards so a bot mention in a pull request, or a work item assigned to the bot, creates a swarm task, and workers clone, push, and open PRs with git and the az CLI

Agent Swarm supports Azure Repos alongside GitHub and GitLab. Service hooks turn bot mentions in pull requests into swarm tasks, and workers reach Azure Repos with git and the az CLI, both authenticated with one Personal Access Token (PAT).

This version covers Azure Repos pull request service hooks and Azure Boards work item service hooks. Status comments on work items, Microsoft Entra ID service principals, and a dashboard card come later.

1. Create a bot user and its PAT

Create a dedicated Azure DevOps user for the swarm, for example agent-swarm-bot, and mint the PAT as that user, not as a person. The swarm then shows up in Azure DevOps as a peer: its pushes, PRs, and comments carry its own name, and you control its access the way you control any teammate's.

  1. Add the user to your organization and give it Basic access.
  2. Add it to each project the swarm works in, with Contributors permissions on the repositories.
  3. Signed in as that user, go to User settings > Personal access tokens > New Token.
  4. Select the scope Code: Read & write. It covers clone, push, pull requests, PR comments, and comment likes. Add Work Items: Read & write so workers can read and update work items with az boards.

Mentions are matched against the PAT owner, so @agent-swarm-bot in a PR is what triggers the swarm.

As with GitHub and GitLab, anyone who can comment on a pull request in a connected repository can trigger the swarm with a mention. Give the bot user access only to repositories where you accept that.

Work item triggers are stricter. Work item text reaches a PAT-enabled agent, so a work item assignment, description mention, or comment mention creates a task only when the person who caused the event maps to a known swarm user, or their sign-in name is listed in AZURE_DEVOPS_ALLOWED_ACTORS. Events from anyone else are dropped and logged, and the actor shows up in the unmapped-identity list for triage. Work item events are also dropped unless they belong to the organization in AZURE_DEVOPS_ORG_URL (without it, only dev.azure.com and *.visualstudio.com HTTPS organizations qualify), and the PAT is never sent to any other URL. Scope the PAT to the one organization and to the projects the swarm serves; the Work Items scope should be granted only if you use Azure Boards.

2. Configure the swarm

Set these as swarm config values (secret where marked) or as environment variables on the API server and the workers:

# Required: API + worker access (secret)
AZURE_DEVOPS_TOKEN=your-bot-pat
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-org

# Required for webhooks: the Basic auth password service hooks send (secret)
AZURE_DEVOPS_WEBHOOK_SECRET=a-long-random-string

# Optional: identity GUID of the bot (default: the identity that owns the PAT)
AZURE_DEVOPS_BOT_ID=00000000-0000-0000-0000-000000000000

# Optional: sign-in names (comma-separated) allowed to trigger work item tasks
# without a linked swarm user
AZURE_DEVOPS_ALLOWED_ACTORS=alex@your-company.com

# Optional: move the linked work item when its task starts or completes.
# State names depend on the project process (Agile: Active/Closed,
# Scrum: Committed/Done, Basic: Doing/Done). Unset means no state change.
AZURE_DEVOPS_WORKITEM_STATE_STARTED=Doing
AZURE_DEVOPS_WORKITEM_STATE_DONE=Done

# Optional: name for plain-text @mentions (default: agent-swarm-bot)
AZURE_DEVOPS_BOT_NAME=agent-swarm-bot

# Optional: git commit identity for Azure Repos
AZURE_DEVOPS_EMAIL=agent-swarm-bot@your-company.com
AZURE_DEVOPS_NAME=Agent Swarm Bot

# Optional: turn the integration off on the API and the workers
AZURE_DEVOPS_DISABLE=true

Workers read swarm config at boot, so restart them after you add the token.

3. Create the service hooks

In the Azure DevOps project, go to Project settings > Service hooks > Create subscription, pick Web Hooks, and create one subscription per event:

TriggerFilters
Pull request createdRepository and branch: optional
Pull request commented onRepository and branch: optional
Work item createdArea path and work item type: optional
Work item updatedArea path and work item type: optional. Field Assigned To is a useful filter, but the swarm also checks the field change itself, because the hook fires on comments too.
Work item commented onArea path and work item type: optional
Work item deletedArea path and work item type: optional
Work item restoredArea path and work item type: optional

On the action page of each subscription:

  • URL: https://your-server.com/api/azure-devops/webhook (must be HTTPS)
  • Basic authentication username: any value, for example agent-swarm
  • Basic authentication password: the value of AZURE_DEVOPS_WEBHOOK_SECRET
  • Resource details to send: All
  • Resource version: keep the default, 1.0, for work item events. For Pull request commented on, pick 2.0. Version 1.0 sends only the comment, without the pull request. The swarm answers it with {"created":false}, logs a warning, and creates no task. For Pull request created, keep the default, 1.0.

Use Test on the subscription to check the connection. The test payload has no bot mention, so the swarm answers {"created":false}.

Supported events

EventWhat happens
PR created with a bot mention in the descriptionCreates a task for the lead agent
New PR comment with a bot mentionCreates a task with the comment as context, linked to any active task for the same PR, and likes the comment as an acknowledgement

| Work item created, assigned to the bot or mentioning it in the description | Creates a task for the lead agent and links it to the work item | | Work item updated, Assigned To changed to the bot | Same. Other edits, and reassignments away from the bot, are ignored | | Work item comment with a bot mention | Creates a task with the comment as context. If the work item already has an active task, the new task is a child of it | | Work item deleted | Cancels the linked task if it is still active | | Work item restored | If the task was cancelled by the delete and the item is still assigned to the bot, creates a follow-up task. If the item was never linked, behaves like created |

Work item state transitions

Set AZURE_DEVOPS_WORKITEM_STATE_STARTED and/or AZURE_DEVOPS_WORKITEM_STATE_DONE to move the linked work item when its task starts or completes. The value must be a state of the work item type in your project's process. If Azure DevOps rejects it, the error is logged and the task is unaffected. Unset (the default) never changes a state. This needs the Work Items: Read & write scope.

Work item mentions work as the picker mention (data-vss-mention with the bot's identity GUID) or typed @agent-swarm-bot / @<bot sign-in name before the @>. Each delivery is deduplicated on its service-hook notification id, so retries create no second task. The swarm ignores work item events caused by the bot itself and comment edits.

Mentions work in two forms. A mention picked from the identity picker is stored as @<GUID> and matches the bot's identity. A typed @agent-swarm-bot matches AZURE_DEVOPS_BOT_NAME. The swarm ignores comments written by the bot itself, system comments, and edits to existing comments, so fixing a typo does not create a second task.

The bot is the identity that owns AZURE_DEVOPS_TOKEN, unless you set AZURE_DEVOPS_BOT_ID. The swarm ignores PRs and comments from that identity. If you mint the PAT under your own account, as is common in a test setup, your own mentions never trigger the swarm. Test from another account.

Workers

The full worker image ships the Azure CLI with the azure-devops extension. At boot, docker-entrypoint.sh:

  • adds a git credential helper for dev.azure.com and *.visualstudio.com that reads AZURE_DEVOPS_TOKEN from the environment, so the token is never written to disk;
  • exports AZURE_DEVOPS_EXT_PAT and the default organization for az, so no az devops login is needed.

The slim image has no az; git access to Azure Repos still works there.

OperationGitHub (gh)Azure DevOps
Clonegh repo clonegit clone https://dev.azure.com/org/project/_git/repo
Create PRgh pr createaz repos pr create --project <p> --repository <r> --source-branch <b>
View PRgh pr viewaz repos pr show --id <n>
View work item-az boards work-item show --id <n>
Reply on work item-az boards work-item update --id <n> --discussion "<reply>"
Comment on PRgh pr commentaz devops invoke --area git --resource pullRequestThreads --route-parameters project=<p> repositoryId=<r> pullRequestId=<n> --http-method POST --in-file <json> --api-version 7.1

az repos has no comment command, so comments go through az devops invoke with a JSON body such as {"comments":[{"content":"Done, see the latest push."}],"status":1}. Tasks created from Azure DevOps events include this recipe.

Tasks store the repository as its HTTPS clone URL, for example https://dev.azure.com/org/project/_git/repo, so a worker can clone a repository that is not registered with the swarm.

Workflow triggers

Azure DevOps events can trigger workflows:

  • azure-devops.pull_request.created
  • azure-devops.pull_request.commented
  • azure-devops.work_item.assigned: Assigned To changed on a work item (assigned_to, previous_assignee)
  • azure-devops.work_item.commented: a new work item comment (comment is its HTML)

Work item events fire for every matching service-hook delivery, whether or not the bot is involved. Both carry work_item_id, title, project, action and user_login.

Troubleshooting

SymptomCause
Test on a subscription returns {"created":false}Expected. The test payload has no bot mention.
Deliveries fail with 401 {"error":"Invalid credentials"}The Basic authentication password does not match AZURE_DEVOPS_WEBHOOK_SECRET.
Deliveries fail with 503AZURE_DEVOPS_WEBHOOK_SECRET is not set on the API server, or AZURE_DEVOPS_DISABLE=true.
A mention returns {"created":false} and no task appearsThe author is the bot identity, usually the PAT owner. Mention from another account.
A work item event returns {"created":false} and the log says the actor is not a known swarm userLink the person's Azure DevOps sign-in name to a swarm user, or add it to AZURE_DEVOPS_ALLOWED_ACTORS.
A work item delivery returns 500The bot identity lookup or task creation failed. Azure DevOps retries the delivery; nothing was recorded as handled.
Assigning a work item does nothingThe Work item updated subscription is missing, or the item was assigned by the bot identity itself.
Every comment returns {"created":false} and the API logs required resource fields are missingThe comment subscription uses resource version 1.0. Edit it and pick 2.0.

On this page