Troubleshooting

”BranchDeploy is not configured”

Cause: No saved configuration, or all environments are disabled.

Fix:

1. Go to Project Settings → BranchDeploy.
2. Ensure at least one environment is filled in with a valid Pipeline ID.
3. Click Save settings.
4. Try the deploy action again.

”No linked branch found”

Cause: No Azure Repos branch or pull request is linked in the work item’s Development section.

Fix:

1. Open the work item.
2. In the Development section (right panel), click create a branch or link an existing branch.
   • Or open the Azure Repos pull request and link the work item from there.
3. Once a branch or PR is linked, retry the deploy action.

BranchDeploy reads only Development links. Related Work and Links tabs are ignored.

”Branch is not allowed”

Cause: The linked branch does not match the allowed branch patterns in Project Settings → BranchDeploy.

Fix:

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

To allow every branch, enter * as the only pattern. This removes the safety guard.

”Pipeline run failed”

Cause: Azure Pipelines rejected the run request.

Common reasons:

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:

1. Open Pipelines in your Azure DevOps project.
2. Open the correct pipeline.
3. Copy the definitionId from the URL (e.g. .../_build?definitionId=42).
4. Update the Pipeline ID in Project Settings → BranchDeploy.

”Permission denied” or “Unauthorised”

Cause: Your Azure DevOps session cannot access the project or repository.

Fix:

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

Multiple branches linked to the work item

Cause: Two or more branches or pull requests are linked to the work item.

Behaviour: BranchDeploy shows a picker so you can choose which linked branch or pull request to deploy.

If the picker includes stale branches, remove those old links from the work item’s Development section and retry.

BranchDeploy action does not appear on the work item

Cause: The extension is not installed or not enabled for this project.

Fix:

1. Confirm BranchDeploy is installed. Go to Organisation Settings → Extensions and check that BranchDeploy appears in the installed list.
2. If BranchDeploy is installed but the action is not visible, refresh the page.
3. 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.

Settings page is blank or fails to load

Cause: The settings component failed to initialise.

Fix:

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

Still stuck?

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

• Your Azure DevOps organisation URL
• The error message you see
• The pipeline ID you have configured
• Your browser and OS