Azure DevOps Integration

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 first version covers Azure Repos and pull request service hooks. Azure Boards (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 item scopes later, when Boards support lands.

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.

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: 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:

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: 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

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.

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.

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

Troubleshooting

Related

• GitLab Integration — the integration this one is modeled on
• Environment Variables — Azure DevOps configuration variables
• Workflows — automate actions on Azure DevOps events