How-To2026-08-2810 min read

How to Set Up a Feature Branch Workflow in GitHub

A feature branch workflow means all new development happens on isolated branches that are merged into main through pull requests, never committed to directly. When implemented with GitHub's branch protection rules and a clear naming convention, it keeps main continuously deployable, makes code review enforceable, and creates a clear record of what changed and why.

This guide covers how to set up a feature branch workflow in GitHub, including branch naming conventions, protection rules, merge strategies, and how to handle long-running feature branches.

Step-by-step guide

01

Define a branch naming convention

Establish a naming convention before creating the first branch: feature/LIN-123-short-description for features (with ticket number), fix/LIN-456-bug-description for bug fixes, chore/update-dependencies for maintenance, and release/v2.4.1 for release branches. Ticket numbers in branch names create traceability from branch to issue without searching. Enforce the convention in your CONTRIBUTING.md and PR review guidelines.

02

Set up branch protection for main

In Settings > Branches > Add rule for "main": enable Require pull requests (no direct pushes), set Required approvals to 1-2, enable Dismiss stale approvals when new commits are pushed, enable Require status checks (your CI pipeline), and enable Require branches to be up to date. Consider also protecting "release/*" branches with similar rules. These settings make the branch protection robust against both accidents and intentional bypasses.

03

Configure your merge strategy

Choose one merge strategy and enforce it consistently. Squash merge keeps a clean main history (one commit per feature, containing the PR title and ticket number) — best for teams where history readability matters. Merge commit preserves full feature branch history — best for large features where the commit progression has meaning. Rebase merge maintains linear history without merge commits — requires clean branch discipline. Disable the other merge strategies in repository settings so the team cannot mix strategies per PR.

04

Create a pull request template

Add .github/pull_request_template.md with: a description field, linked issue (closes #123 or closes LIN-456 for Linear), testing instructions, and a checklist. When engineers use Linear or Jira, add a requirement that every PR must have a linked issue — this creates full traceability from requirement to ticket to branch to PR to merge. Configure your project to auto-close linked issues when the PR merges.

05

Handle long-running feature branches with flags

Feature branches that live longer than 2-3 days diverge from main and create painful merge conflicts. For large features, use feature flags (LaunchDarkly, Unleash, or a simple environment variable) to merge feature code into main behind a disabled flag while development continues. This keeps all branches short-lived and main continuously deployable, even when a feature is not ready for users.

Common mistakes

Branches that live too long

A feature branch open for 2 weeks accumulates hundreds of diverging commits from main. The merge becomes a multi-hour conflict resolution session that blocks the sprint. The solution is either smaller features (ship less, more often) or feature flags that allow merging incomplete features. Branches should live days, not weeks.

No connection between branches and tickets

A branch named "johns-changes" tells you nothing about what changed or why. Branch names should include the ticket number so anyone can navigate from branch to ticket in one step. Configure GitHub to display linked issues in the PR sidebar and to auto-close issues when the linked PR merges.

Mixed merge strategies in the same repository

If some PRs are squash-merged and others use merge commits, git history becomes unreadable. Configure the repository to allow only one merge strategy. Consistency in git history is what makes bisect, blame, and revert operations useful — inconsistency makes them unreliable.

Tips

Use GitHub's auto-merge feature to merge PRs automatically when all required checks and approvals are satisfied — this removes the manual "someone needs to click merge" bottleneck that stalls reviews at the end of the sprint

Set up a GitHub Action that posts a comment on PRs open longer than 5 days, alerting the author and reviewer that the branch is at risk of significant divergence

Create a .github/CODEOWNERS file that auto-assigns reviewers for specific directories, so feature branches touching auth code automatically require the security team's review

How Vantage helps

GitHub manages your branch workflow. Vantage connects the feature branches to the product requirements they are implementing: each branch links to a ticket, each ticket links to PRD requirements, and each requirement connects to the customer signal that justified it. When an EM reviews a PR, Vantage can surface the acceptance criteria from the PRD so the reviewer can verify the implementation matches the spec.

Frequently asked questions

Spend less time on setup, more on decisions

Vantage connects your tools and generates specs grounded in real data. Free to start.

Free to start. No credit card required.

Related reading