Configuration guide
BranchDeploy is configured per Azure DevOps project. Go to Project Settings → BranchDeploy to open the settings page.
Environment name
A human-readable label for the deployment target shown in the confirmation prompt, such as test, staging, or UAT.
Example: test
Environment description (optional)
A short description displayed in the settings page for your team’s reference. Not shown during deployment.
Pipeline ID
The build definition ID of the Azure Pipeline to trigger when the user confirms a deployment.
To find the pipeline ID:
- Open your Azure DevOps project.
- Go to Pipelines.
- Open the target pipeline.
- The ID is in the URL:
.../_build?definitionId=42— the ID here is42.
The pipeline ID must be a positive integer. BranchDeploy will not accept zero or negative values.
Pipeline name (optional)
A display name for the pipeline shown in the confirmation prompt instead of the raw numeric ID. Example: Deploy to test.
Pipeline parameters
BranchDeploy passes two values to your pipeline when it triggers a run:
| Parameter | Default name | Value |
|---|---|---|
| Environment | environment | The environment parameter value you set |
| Work item ID | workItemId | The numeric ID of the work item |
Environment parameter name
The name of the YAML parameters: field that receives the environment value. Defaults to environment.
Change this if your pipeline uses a different parameter name, for example targetEnvironment.
Environment parameter value
The value passed for the environment parameter. This is what your pipeline receives at runtime.
Usually the same as the environment name, but you can set them independently. For example, environment name UAT with parameter value user-acceptance.
Work item ID parameter name
The name of the YAML parameters: field that receives the work item ID. Defaults to workItemId.
Your pipeline can use this to add a comment to the work item after deployment, or to tag the build with the source ticket.
Allowed branch patterns
A list of glob patterns controlling which branches BranchDeploy will deploy. One pattern per line.
| Pattern | What it matches |
|---|---|
* | Any branch (use with caution) |
feature/* | Any branch starting with feature/ |
release/* | Any branch starting with release/ |
refs/heads/main | Exactly main by full ref path |
BranchDeploy blocks deployment if the linked branch does not match any pattern. This prevents accidental deployments from main, hotfix branches, or personal branches.
A wildcard-only allowlist (*) is permitted but will produce a warning in the settings UI.
Free tier limits
The free tier supports 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.
Example configuration
| Setting | Example value |
|---|---|
| Environment name | test |
| Pipeline ID | 42 |
| Pipeline name | Deploy to test |
| Environment parameter name | environment |
| Environment parameter value | test |
| Work item ID parameter name | workItemId |
| Allowed branch patterns | feature/*, bug/*, task/* |
Next steps
- Pipeline YAML examples — configure your pipeline to accept these parameters
- Troubleshooting — fix configuration problems