BranchLens

Correlates your local Git branches with Jira ticket statuses so you can see release readiness at a glance — without keeping it all in memory.

Built for solo developers who keep branches local (no PRs) and need to know what's tested, what's ready to merge, and what's still in progress.

What it does

BranchLens scans your local branches, extracts Jira ticket keys from branch names, fetches ticket statuses, and shows each branch with a release-readiness state in the sidebar.

Release states

Setup

1. Open a git repository in VS Code

BranchLens reads your local branches — no remote access needed.

2. Configure Jira credentials

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run:

BranchLens: Configure Jira

You'll be prompted for:

• Jira base URL — e.g. https://yourorg.atlassian.net
• Jira email — your Atlassian account email
• Jira API token — generate one at id.atlassian.com/manage-profile/security/api-tokens

Credentials are stored in VS Code's encrypted SecretStorage — never in plain settings.

Branch naming

BranchLens extracts Jira ticket keys using the pattern [A-Z]+-\d+. Any branch following these conventions works:

feat/PROJ-123-my-feature
fix/PROJ-456-bug-description
PROJ-789-short-name

Branches without a matching ticket key show as No ticket.

Jira status lists

Which Jira statuses count as To Do, In Progress, Done and Hold is configurable per repo — edit them in the Configuration panel (one status per line, case-insensitive), or click a category on an Unmapped branch's detail panel. They're saved in .branchlens/settings.json:

{
  "statuses": {
    "todo": ["TO DO"],
    "inProgress": ["IN PROGRESS"],
    "done": ["DONE", "TESTED ON BETA", "READY TO TEST STAGING", "TESTED ON STAGING"],
    "hold": ["READY TO TEST BETA", "IN PROGRESS DEV", "READY TO BUILD", "CANNOT REPRODUCE"]
  }
}

The values above are the defaults. If a status is in several lists, Done wins, then Hold, In Progress, To Do.

Per-repo data (.branchlens/)

BranchLens keeps a hidden .branchlens/ folder in the repo root:

• settings.json — repo-specific settings: branch hierarchy and Jira status lists
• cache.json — Jira tickets, so the tree loads instantly after a reload. Tickets are re-fetched after 10 minutes or on Refresh; if Jira is unreachable, the last cached data is shown.
• .gitignore — ignores the whole folder, so it never shows up in git status

No credentials are written here; those stay in SecretStorage.

Branch hierarchy

BranchLens supports a configurable hierarchy of up to 3 base branches (e.g. develop → master → production). Base branches are filtered out of the branch list and used to track how far each feature branch has been promoted.

Configure via the BranchLens Configuration panel (bottom panel area). The hierarchy is saved per repository in .branchlens/settings.json:

{ "hierarchy": ["develop", "master", "production"] }

Repos without that file fall back to the global branchlens.hierarchy VS Code setting.

• 1 level — just a development branch (e.g. ["develop"])
• 2 levels — develop + main (e.g. ["develop", "master"])
• 3 levels — full pipeline (e.g. ["develop", "master", "production"])

The detail panel shows which levels a branch has been merged into:

develop ✓  →  master ✓  →  production ✗

Configuration panel

Open the bottom panel and select the BranchLens tab to:

• Edit the branch hierarchy with up/down reordering
• See a live pipeline preview
• Check Jira connection status and reconfigure credentials

To open: Cmd+Shift+P → Open View → BranchLens: Configuration

Branch detail panel

Click any branch in the sidebar to open a detail panel showing:

• Jira ticket status, priority, assignee, and last updated
• Merge hierarchy pipeline
• Commits ahead of the base branch
• Last commit and branch age
• Uncommitted diff (if you're on that branch)
• Actions: Checkout branch, Open in Jira, Delete branch

Refreshing

BranchLens auto-refreshes when Git refs change (branch create/delete/switch). To manually refresh, click the refresh icon (↺) in the sidebar header or run:

BranchLens: Refresh Branches

Requirements

• VS Code 1.85 or later
• A local Git repository
• A Jira Cloud account with API access