Configuration guide

Configure BranchDeploy per Azure DevOps project in Project Settings → BranchDeploy.

Environment name

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

Example: test

Environment description (optional)

A short settings-page note for your team. It is not shown during deployment.

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 parameter name

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

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

Environment parameter 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, parameter value user-acceptance.

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

Work item ID parameter 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 (*) is permitted but will produce a warning in the settings UI.

Free tier limits

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

If your team needs multiple environments (for example Test, UAT, and Staging on the same project), upgrade to BranchDeploy Pro. The current Azure DevOps settings page edits the project’s active environment; Pro cloud integrations can use multiple synced environments when they are configured.

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