BranchPilot — Create Branches from Work Items in Azure DevOps

Automate Git branch creation directly from Azure Boards Work Items. Enforce consistent branch naming conventions, automatically link branches to Work Items, and keep your team's Git workflow clean — with zero manual effort.

The Problem BranchPilot Solves

Every developer on an Azure DevOps team goes through the same ritual dozens of times a day:

1. Open a Work Item (Bug, User Story, Task, Feature…)
2. Switch to the repository
3. Type a branch name — trying to remember the team naming convention
4. Forget to link the branch back to the Work Item

The result: inconsistent branch names, broken traceability between code and tickets, and wasted time.

BranchPilot eliminates all of this with one click.

What BranchPilot Does

BranchPilot adds a "New branch…" action to the Work Item context menu in Azure Boards. When clicked, it opens a panel where the developer selects the target repository and the source branch — the branch name is generated automatically according to your team's naming rules.

The branch is created in Git and immediately linked to the Work Item so it appears in the Work Item's Development section, giving full traceability from ticket to code.

Key Features

One-click branch creation from any Work Item

Create a Git branch directly from a Bug, User Story, Task, Feature, Epic, or any custom Work Item type — without leaving Azure Boards.

Smart branch naming engine

Define naming rules based on:

• Source branch (e.g. branching from hotfix/* → auto-prefix hotfix/, branching from develop → feature/)
• Work Item type (Bug → bugfix/, User Story → feature/, Task → task/)
• Fallback default for everything else

Rules use glob patterns (hotfix/*, release/*) or regular expressions for maximum flexibility.

Automatic Work Item linking

The newly created branch is automatically linked to the Work Item using the standard Azure DevOps artifact link (ArtifactLink). No need to manually associate branches — the Development panel updates immediately.

Configurable Work Item state transitions

Optionally move the Work Item to a target state (e.g. "Active", "In Progress") as soon as the branch is created, keeping your board up to date automatically.

Always-explicit repository and source branch selection

No silent assumptions. The developer always selects the target repository and the "Based on" branch — preventing accidental branches off the wrong base.

Editable branch name (optional)

Allow developers to manually adjust the auto-generated name before confirming, or lock it to enforce strict naming conventions.

Per-project configuration hub

Full settings UI available in Project Settings → BranchPilot. Configure naming rules, templates, state transitions, and general options — all stored per Azure DevOps project.

Export and Import configuration

Export the project configuration as a JSON file and import it into other projects. Perfect for teams managing multiple repositories or projects with a shared branching strategy.

Bilingual UI — English and Italian

The extension interface is fully available in English and Italian, with automatic language detection from the project settings.

How It Works

Step 1 — Open a Work Item

Open any saved Work Item on Azure Boards. The Work Item must have an ID (it must be saved at least once).

Step 2 — Open the context menu

Click the ⋯ overflow menu on the Work Item form or the board card and select "New branch… (BranchPilot)".

Step 3 — Choose repository and source branch

A side panel opens. Select:

• Repository — the Git repository where the branch will be created
• Based on — the source branch to branch from (defaults to the repository's default branch)

Step 4 — Confirm the branch name

The branch name is generated instantly from your naming rules. Review it, adjust it if allowed, and click Create.

Result

The branch is created in Git and linked to the Work Item. The Work Item's Development section shows the new branch immediately. If a state transition is configured, the Work Item state is also updated.

Branch Naming Engine

Branch names are generated by a rules engine with strict precedence:

1. rulesBySourceBranch  ← first match wins (evaluated on the "Based on" branch)
2. rulesByWorkItemType  ← first match wins (case-insensitive Work Item type)
3. defaults             ← fallback template

Example naming rules and output

Template tokens

Compose branch names using dynamic tokens:

Example template: {prefix}{wi.id}-{wi.title} → feature/42-add-payment-provider

Name sanitization

BranchPilot automatically sanitizes the generated name to produce valid Git branch names:

• Special characters (spaces, /, :, ", &, (, ), etc.) → replaced with -
• Consecutive separators collapsed to a single -
• Leading and trailing - stripped
• Forced to lowercase (configurable)
• Truncated to maxLength characters (default: 80, hard limit: 250), always preserving the Work Item ID

Supported Branching Strategies

BranchPilot is designed to work with any Git branching strategy:

GitFlow

• develop → feature/{id}-{title}
• hotfix/* → hotfix/{id}-{title}
• release/* → release/{id}-{title}
• Bug type → bugfix/{id}-{title}

GitHub Flow / Trunk-Based Development

• Any source → feature/{id}-{title} (single rule, simple template)

Custom enterprise conventions

• Full regex support: ^app/release\d+(/.*)?$ → app/release/{id}-{title}
• Multiple repo overrides with different templates per repository

Configuration

Open Project Settings → BranchPilot to configure. All settings are stored per Azure DevOps project using the Extension Data Service.

General settings

{
  "general": {
    "lowercase": true,
    "nonAlnumReplacement": "-",
    "maxLength": 80,
    "allowManualNameOverride": true
  }
}

Full configuration schema

{
  "schemaVersion": 1,
  "general": {
    "lowercase": true,
    "nonAlnumReplacement": "-",
    "maxLength": 80,
    "allowManualNameOverride": true
  },
  "defaults": {
    "template": "feature/{wi.id}-{wi.title}",
    "workItemState": { "enabled": false, "state": "Active" }
  },
  "repoOverrides": {
    "my-repo-name": {
      "defaultTemplate": "custom/{wi.id}-{wi.title}"
    }
  },
  "rulesBySourceBranch": [
    {
      "name": "Hotfix branch rule",
      "matchType": "glob",
      "match": "hotfix/*",
      "prefix": "hotfix/",
      "template": "{prefix}{wi.id}-{wi.title}",
      "workItemState": { "enabled": true, "state": "In Progress" }
    },
    {
      "name": "Release branch rule",
      "matchType": "regex",
      "match": "^release(/.*)?$",
      "prefix": "release/",
      "template": "{prefix}{wi.id}-{wi.title}"
    }
  ],
  "rulesByWorkItemType": [
    {
      "workItemType": "Bug",
      "prefix": "bugfix/",
      "template": "{prefix}{wi.id}-{wi.title}",
      "workItemState": { "enabled": true, "state": "Active" }
    },
    {
      "workItemType": "User Story",
      "prefix": "feature/",
      "template": "{prefix}{wi.id}-{wi.title}",
      "workItemState": { "enabled": true, "state": "Active" }
    },
    {
      "workItemType": "Task",
      "prefix": "task/",
      "template": "{prefix}{wi.id}-{wi.title}"
    }
  ]
}

Export / Import

In Project Settings → BranchPilot:

• Export JSON — downloads the current configuration as branchpilot-config.json
• Import JSON — loads a configuration exported from this or another project

Required Permissions

BranchPilot requires the following Azure DevOps scopes:

Installation

From the Visual Studio Marketplace

1. Install from Visual Studio Marketplace.
2. Open any Azure DevOps project.
3. Navigate to Project Settings → BranchPilot to configure naming rules.

Private / on-premises install

# 1. Clone the repository
git clone https://github.com/managerfx/branch-pilot-az-devops.git
cd branch-pilot-az-devops

# 2. Install dependencies
npm install

# 3. Build and package
npm run package

# 4. Upload the generated .vsix via Organisation Settings → Extensions → Upload

Troubleshooting

Diagnostic details

When an error occurs, a collapsible Diagnostic details section appears in the panel. Click Copy diagnostics to copy a structured JSON log — useful when reporting issues at github.com/managerfx/branch-pilot-az-devops/issues.

Use Cases

• Development teams enforcing a company-wide Git branching convention (GitFlow, GitHub Flow, trunk-based)
• Scrum / Kanban teams wanting to keep Azure Boards Work Items automatically linked to branches
• Tech leads who want to remove manual steps and naming errors from the developer workflow
• Enterprise teams managing multiple repositories with different branching strategies per repo
• Regulated environments where traceability between tickets and code changes is mandatory

License

MIT © FeliceLombardi Source: github.com/managerfx/branch-pilot-az-devops