How to Create a Feature Branch Workflow in GitHub
A feature branch workflow is the standard pattern for engineering teams using Git: every change lives on an isolated branch, gets reviewed via a pull request, and merges to main only after passing CI and peer review. The challenge is not the pattern itself — it is making the workflow consistent, enforced, and low-friction across the entire team.
This guide covers how to configure a feature branch workflow in GitHub with branch protection rules, PR templates, status checks, and the naming conventions that make the branch list readable at a glance.
Step-by-step guide
Define and document your branch naming convention
Establish a branch naming pattern before creating any rules: `feature/<ticket-id>-<short-description>` (e.g. feature/ENG-123-add-auth-flow), `fix/<ticket-id>-<description>` (e.g. fix/ENG-456-null-pointer-on-signup), `chore/<description>` (e.g. chore/upgrade-dependencies), and `hotfix/<description>` for urgent production fixes. Document this convention in your CONTRIBUTING.md. The ticket ID prefix creates automatic traceability between branches and your issue tracker.
Configure branch protection rules for main
Go to GitHub repository Settings → Branches → Add rule. Set the branch name pattern to "main." Enable: Require a pull request before merging (set required reviewers to 1-2 depending on team size), Require status checks to pass before merging (add your CI workflow checks), Require branches to be up to date before merging, Do not allow bypassing the above settings (including administrators). This enforces the workflow even for senior engineers and CI/CD service accounts.
Create a pull request template
Create a file at `.github/pull_request_template.md` in your repository. Include sections: Summary (2-3 sentences on what this PR does and why), Ticket Link (e.g. Fixes ENG-123), Type of Change (checkboxes: Bug fix, New feature, Breaking change, Docs update), How to Test (step-by-step instructions for reviewers), Screenshots (for UI changes), Checklist (checkboxes: Tests added, Docs updated, No console errors, Tested on mobile if applicable). Every PR opens pre-filled with this template.
Set up required CI status checks
In your CI workflow (GitHub Actions), create jobs for: Linting (ESLint, Prettier — fast, catches style issues), Type checking (tsc --noEmit — catches type errors without building), Unit tests (Jest/Vitest — runs the test suite), and Build (ensures the project builds successfully). In the branch protection rule, add each of these as required status checks. PRs cannot merge until all checks pass. Name checks descriptively: "lint / eslint" not just "check."
Configure merge strategy and stale branch cleanup
In repository Settings → General → Pull Requests, disable Merge commits and enable Squash merging (keeps main history linear and readable) or Rebase merging (preserves individual commits). Enable "Automatically delete head branches" so merged branches are cleaned up without manual action. In Settings → Actions → General, configure the GITHUB_TOKEN permissions to allow the branch deletion action. Add a stale bot (GitHub's stale action) that comments on PRs open longer than 14 days and closes branches open longer than 30 days after the PR is merged.
Common mistakes
Branch protection rules that allow bypass
Branch protection with "Include administrators" unchecked means senior engineers or CI bots can push directly to main when under pressure. Enabling "Do not allow bypassing the above settings" means no one — including repository admins — can push to main without a PR. This is the right setting for any team that cares about code quality under deadline pressure.
Long-lived feature branches
A branch open longer than a week accumulates merge conflicts and diverges from main. Break large features into smaller branches that each represent a shippable increment. Use feature flags to merge incomplete work to main without exposing it to users. The goal is branches that live for 1-3 days, not weeks.
PR descriptions that only reference the ticket
"See ENG-123" is not a PR description. Reviewers should not need to open the issue tracker to understand what the PR does. Write a 2-3 sentence summary in the PR body explaining what changed, why it changed, and how to verify it. The PR description becomes the squash commit message — it should be meaningful to anyone reading git log six months from now.
Tips
Use GitHub's CODEOWNERS file to automatically assign reviewers based on the files changed — a PR touching authentication code automatically requests review from the security-minded engineer on the team without manual assignment
Add a branch name linting step to your CI workflow using a GitHub Action that validates branch names match your convention — this enforces naming automatically instead of relying on human memory
Use GitHub's required review dismissal on push: if the branch is updated after approval, the approval is dismissed and the reviewer must re-approve. This prevents the pattern of getting approval and then sneaking in changes afterward
How Vantage helps
A well-structured feature branch workflow generates traceability between tickets and code. When Vantage pushes tickets to your issue tracker and engineers create branches using the ticket ID in the branch name, Vantage can surface the relationship between product requirements and the code implementing them. Query the query engine with "what code implements the user authentication requirement?" and Vantage traverses from the PRD requirement to the ticket to the GitHub branch.