Teams Bot Setup

The BranchDeploy Teams bot lets any team member trigger a branch deployment by typing a natural-language command in a Teams channel. No browser tabs, no Azure DevOps portal — just type and deploy.

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
Admin access to your Microsoft Teams tenant (to upload a custom app)
Project settings saved and synced to BranchDeploy from the extension settings page

Step 1 — Connect Azure DevOps

Go to your account page.
In the Connect Azure DevOps section, enter your Azure DevOps organisation URL (e.g. https://dev.azure.com/my-org) and a PAT.
Click Save credentials.

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 saved and correct.
Click Sync to BranchDeploy to push the config to the cloud.

Repeat for every project whose environments should be available to the Teams bot.

Step 3 — Install the Teams app

Go to your account page and download teams-app.zip from the Teams Bot section.
In the Teams Admin Centre, go to Teams apps → Manage apps → Upload an app → Upload a custom app.
Select the .zip file.
Once uploaded, users can add @BranchDeploy to any channel.

Step 4 — Deploy 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.
Trigger the pipeline when you click Deploy Now.

Available commands

Command	Description
`@BranchDeploy deploy #1234 to UAT`	Deploy the branch linked to work item 1234 to UAT
`@BranchDeploy deploy #1234`	Deploy with environment picker (if multiple environments configured)
`@BranchDeploy environments`	List configured environments
`@BranchDeploy history`	Show recent deployments
`@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” — Run Sync to BranchDeploy from the extension settings for each project.

“Permission denied” — Your PAT may have expired or lack the required 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.