Troubleshooting

”BranchDeploy is not configured”

Cause: No configuration has been saved for this project, or all configured environments are disabled.

Fix:

Cause: The work item has no Azure Repos branch or pull request linked in its Development section.

Fix:

Open the work item.
In the Development section (right panel), click create a branch or link an existing branch.
- Alternatively, open the Azure Repos pull request and link the work item from the PR’s work item section.
Once a branch or PR is linked, retry the deploy action.

BranchDeploy only reads links from the Development section of the work item. Links added in the Related Work or Links tabs are not used.

Cause: The branch linked to the work item does not match any of the allowed branch patterns configured in Project Settings → BranchDeploy.

Fix:

Go to Project Settings → BranchDeploy.
Update the Allowed branch patterns field to include the branch pattern you need.
- For example, add hotfix/* to allow hotfix branches.
Save, then retry.

If you intentionally want to allow all branches, enter * as the only pattern — but be aware this removes the safety guard.

Cause: The Azure Pipelines Run API returned an error after BranchDeploy tried to queue the run.

Common reasons:

Symptom	Likely cause
Error message mentions permissions	Your account lacks Queue builds permission on the pipeline
Error mentions branch filter	The pipeline has a branch filter that excludes the linked branch
Error mentions resource authorisation	The service connection or resource used by the pipeline is not authorised for the branch
Error mentions invalid definition	The Pipeline ID in BranchDeploy settings is wrong

Fix for permissions:

Ask an Azure DevOps Project Administrator to grant you Queue builds permission under Project Settings → Pipelines → [pipeline] → Security.

Fix for invalid Pipeline ID:

Cause: BranchDeploy is making API calls using your Azure DevOps session, and your account does not have access to the project or repository.

Fix:

Confirm you have Basic or Stakeholder access to the project.
Confirm you have Read access to the Azure Repos repository.
Confirm you have Queue builds permission on the pipeline.
If you recently changed roles or joined the project, try refreshing your browser session.

Cause: Two or more branches or pull requests are linked to the work item. BranchDeploy cannot safely choose one automatically.

Free tier behaviour: BranchDeploy shows an error message listing the candidate branches and asks you to unlink all but one, then retry.

Pro behaviour: A picker lets you select which branch to deploy from the list of candidates.

Fix (free tier):

Open the work item.
In the Development section, remove the extra branch links until only one remains.
Retry the deploy action.

Cause: The extension is not installed, or it was installed but not enabled for this project.

Fix:

Confirm BranchDeploy is installed. Go to Organisation Settings → Extensions and check that BranchDeploy appears in the installed list.
If BranchDeploy is installed but the action is not visible, try refreshing the page (Azure DevOps extensions sometimes need a hard refresh after installation).
If you are using a custom work item type, the action may not render in all views. Try opening the work item in its full-page form.

Cause: The extension’s settings component failed to initialise.

Fix:

Open your browser’s developer console (F12) while on the BranchDeploy settings page.
Look for JavaScript errors. Report them to support@branch-deploy.dev with the error text and your organisation URL.
Try a different browser to rule out browser-specific issues.

Open a support request at branch-deploy.dev/support and include: