Configuration guide

Configure BranchDeploy per Azure DevOps project in Project Settings → BranchDeploy. Pick the environment to edit from the Environments dropdown at the top of the page; the fields below belong to that environment.

Name

The deployment target shown in the confirmation prompt, such as test, staging, or UAT.

Example: test

Description (optional)

A short note for your team. It is also shown in the environment picker when a branch can deploy to more than one environment.

Pipeline ID

The Azure Pipeline build definition ID to queue after confirmation.

To find the pipeline ID:

1. Open your Azure DevOps project.
2. Go to Pipelines.
3. Open the target pipeline.
4. The ID is in the URL: .../_build?definitionId=42 — the ID here is 42.

The pipeline ID must be a positive integer. BranchDeploy will not accept zero or negative values.

Pipeline name (optional)

A confirmation-prompt label for the pipeline. Example: Deploy to test.

Pipeline parameters (optional)

BranchDeploy always sets the source branch on the pipeline run — that is the core of what it does. Your existing pipeline takes it from there.

The fields in this section are optional extras. They let BranchDeploy pass additional named queue-time values to your pipeline. Leave them all blank if your pipeline does not need them.

When you need these fields

Environment parameter — use this if your pipeline is shared across multiple environments (for example test, staging, or UAT) and relies on a variable to know which one to target. If your pipeline always deploys to the same place, you do not need it.

Work item ID parameter — use this if you want the pipeline to know which ticket triggered the run, for example to tag the build name or post a comment back to the work item.

If you leave these blank, BranchDeploy queues the pipeline on the linked branch only, with no extra variables. Most pipelines work this way without any changes.

Environment variable name

The name of the pipeline variable that receives the environment value. Only used when Environment variable value is also set.

Example: environment, or targetEnvironment if your pipeline uses that name.

Environment variable value

The value sent to the pipeline for this environment.

Usually the same as the environment name above, but can differ. Example: environment name UAT, variable value user-acceptance.

Both this and Environment variable name must be set for the environment variable to be sent.

Work item ID variable name

The name of the pipeline variable that receives the numeric work item ID.

Example: workItemId, or ticketId if your pipeline uses that name.

Note: BranchDeploy sends these values through the Build Queue API parameters field. In your pipeline, consume them as variables such as $(environment) or $(workItemId). If Azure DevOps rejects the run because a variable is not settable, define that variable on the pipeline and mark it Settable at queue time. See Pipeline YAML examples for details.

Allowed branch patterns

Glob patterns for deployable branches, one per line.

BranchDeploy blocks linked branches that do not match any pattern.

A wildcard-only allowlist (*) allows every linked branch, so use it only while testing your setup.

Free tier limits

The free tier includes one project per Azure DevOps organisation and one environment in that project.

If your team needs multiple environments (for example Test, UAT, and Staging on the same project), upgrade to BranchDeploy Pro.

Multiple environments (Pro)

On Pro, use Add environment on the settings page to add another environment. Each one has its own pipeline, pipeline parameters, and branch rules. Switch between environments with the Environments dropdown, and click Save all environments to save every environment at once. Saving never replaces an environment you did not remove.

When someone clicks Deploy linked branch, BranchDeploy only offers environments whose branch rules allow the linked branch:

• If exactly one environment allows it, that environment is used. The confirmation dialog names it before anything runs.
• If several allow it, BranchDeploy asks which environment to deploy to.
• If none allow it, the deployment is blocked.

Branch rules are a simple way to route work. For example, give a DEV Preview environment feature/* and a UAT environment release/*. MCP assistants follow the same rules, and they also accept an environment’s pipeline parameter value (such as PCC-DEV) in place of its name.

Example configuration

Minimal setup — BranchDeploy just sets the source branch, no extra variables passed:

With optional pipeline parameters enabled:

Next steps

• Pipeline YAML examples — use these queue-time values in YAML
• Troubleshooting — fix configuration problems