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
• Build (Read) so BranchDeploy can record whether each pipeline run succeeded or failed; if you also use MCP with the same PAT, use 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, with a connection token connected so they sync to the cloud

Step 1 — Connect Azure DevOps

1. Open the Credentials tab on your account page. Saving a PAT needs an admin.
2. Your organisation URL is shown automatically. In the Azure DevOps PAT column, paste a PAT into the Personal Access Token field.
3. Click Save PAT. The Teams tab appears on your account page once a PAT is saved.

The PAT is encrypted at rest and never exposed. One PAT serves the whole workspace, so the bot uses it for everyone who deploys from Teams. We recommend creating it from a service account: otherwise every Teams and AI deploy shows in Azure DevOps as the person the PAT belongs to, and stops working if they leave.

Step 2 — Sync project config

In the BranchDeploy extension inside Azure DevOps:

1. Open any project and navigate to Project Settings → BranchDeploy.
2. Under BranchDeploy account, paste a connection token from your account (Credentials tab). Connecting a token syncs the saved settings straight away.
3. Make sure your environments are correct and click Save all environments. Every save syncs to the cloud while a token is connected.

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.

1. Open the Teams tab on your account page and click Download Teams app (.zip).
2. In the Teams Admin Center, go to Teams apps → Manage apps → Upload a custom app.
3. Select the .zip file.
4. 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:

1. Look up work item #1234 in Azure DevOps.
2. Resolve the linked branch.
3. Show you a confirmation card.
4. Record the approved request in BranchDeploy when you click Deploy Now.

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, check a connection token is connected, and click Save all environments 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.