Teams bot
The BranchDeploy Teams bot lets team members request and confirm deployment approvals from a Teams channel. It resolves the linked Azure Repos branch for a work item, shows a confirmation card, and records the approved request in your BranchDeploy audit log.
The current Teams bot path is an approval and audit workflow. It does not queue Azure Pipelines directly yet. For direct pipeline queuing, use the Azure DevOps extension or the MCP integration.
Requires a BranchDeploy Pro licence.
Prerequisites
Before you start:
- A BranchDeploy Pro subscription (upgrade here)
- An Azure DevOps Personal Access Token (PAT) with Work Items (Read) and Code (Read) scopes so the bot can resolve work item branches
- If you also use MCP with the same PAT, include Build (Read & Execute) so MCP can queue pipeline runs
- Admin access to your Microsoft Teams tenant (to upload a custom app)
- Project settings saved in the extension (saving automatically syncs them to the cloud)
Step 1 — Connect Azure DevOps
- Go to your account page and open the Credentials tab.
- Your organisation URL is shown automatically. Paste a PAT into the Personal Access Token field.
- Click Save PAT.
Your PAT is encrypted at rest and never exposed.
Step 2 — Sync project config
In the BranchDeploy extension inside Azure DevOps:
- Open any project and navigate to Project Settings → BranchDeploy.
- Make sure your environments are correct.
- Click Save — your config syncs to the cloud automatically.
Repeat for every project whose environments should be available to the Teams bot.
Step 3 — Install the Teams app
BranchDeploy is installed by uploading its app package to your tenant (sideloading). Your Teams admin needs to allow custom app uploads in the Teams admin settings.
- Go to your account page, open the Teams tab, and click Download Teams app (.zip).
- In the Teams Admin Center, go to Teams apps → Manage apps → Upload a custom app.
- Select the
.zipfile. - Once uploaded, anyone in your tenant can add @BranchDeploy to a channel (Apps → Built for your org → BranchDeploy).
Coming soon: a public Microsoft Teams Store listing so you can find BranchDeploy by searching inside Teams, without an admin upload. Until then, use the sideload steps above.
Step 4 — Request from Teams
In any channel where BranchDeploy is added, type:
@BranchDeploy deploy #1234 to UAT
The bot will:
- Look up work item #1234 in Azure DevOps.
- Resolve the linked branch.
- Show you a confirmation card.
- Record the approved request in BranchDeploy when you click Deploy Now.
Available commands
| Command | Description |
|---|---|
@BranchDeploy deploy #1234 to UAT | Request approval for the branch linked to work item 1234 in UAT |
@BranchDeploy deploy #1234 | Request approval using the single configured environment, or get prompted to specify one |
@BranchDeploy environments | List configured environments |
@BranchDeploy history | Show recent audited deployment requests |
@BranchDeploy help | Show all available commands |
Troubleshooting
“Organisation not found” — Make sure your Azure DevOps organisation name in the account page matches the ADO organisation your PAT belongs to.
“No environments configured” — Open the project’s Project Settings → BranchDeploy in the extension and click Save to re-sync its config to the cloud.
“Permission denied” — Your PAT may have expired or lack the required Work Items / Code read scopes. Reconnect in the account page.
Bot not responding — Check that the bot was successfully added to the channel (not just the team). Try @BranchDeploy help.
“No linked branch found” — The work item has no linked pull request or branch. Open the work item in Azure DevOps and link a branch or PR first.
