Trunk-Based Development: Faster Delivery with Less Complexity

In this tutorial, you'll learn about Trunk. We cover key concepts, practical examples, and best practices.

Trunk-based development has developers commit directly to a single shared branch with feature flags hiding incomplete work, enabling continuous delivery.

In this tutorial, you'll learn trunk-based development — a Git branching strategy where developers integrate small changes into a shared main branch several times a day. This approach reduces merge complexity, enables continuous delivery, and is used by high-performing teams at Google, Netflix, and Facebook. By the end, you'll implement trunk-based development with feature flags and automated CI.

flowchart TD
  A[Start: trunk-based dev] --> B[Create short-lived branch]
  B --> C[Make small changes]
  C --> D[Run tests locally]
  D --> E[Commit & push]
  E --> F[CI pipeline runs]
  F --> G{All tests pass?}
  G -->|No| H[Fix immediately]
  H --> E
  G -->|Yes| I[Merge to main]
  I --> J[Deploy to production]
  J --> K[Monitor & repeat]

Core Principles

Feature Flags for Incomplete Work

Feature flags let you merge incomplete features without affecting users:

# config.py
FEATURE_FLAGS = {
    "new_checkout": False,
    "dark_mode": True,
}

# app.py
if FEATURE_FLAGS["new_checkout"]:
    show_new_checkout()
else:
    show_old_checkout()

Setting Up Trunk-Based Development

# Clone main branch
git clone https://github.com/team/project.git
git checkout -b add-dark-mode

# Make small changes
echo "dark-mode: true" >}} config.yml
git add config.yml
git commit -m "feat(ui): add dark mode theme toggle"

# Run tests
npm test

# Push
git push -u origin add-dark-mode

# Create PR, get quick review, merge
# Delete branch after merge

CI Requirements for Trunk-Based

Trunk-based development requires fast, reliable CI:

name: Trunk CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

CI must complete in under 10 minutes. If it takes longer, optimize tests or parallelize.

Deployment Strategy

Deploy directly from main after CI passes:

deploy:
  needs: ci
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  steps:
    - uses: actions/checkout@v4
    - name: Deploy
      run: ./deploy.sh

For zero-downtime deployment, use blue-green or canary releases.

Trunk-Based vs Other Strategies

Common Errors

Practice Questions

Challenge

Set up a trunk-based development workflow for a JavaScript project. Create feature flags for two features (dark mode and new checkout). Make three small commits to main in one day, each with passing CI. Use feature flags so one feature is hidden in production. Write the CI/CD pipeline that deploys automatically on main commits. Remove the flag for the stable feature after one week.

Real-World Task

Migrate a team from Git Flow (with 2-week release cycles) to trunk-based development. Plan the transition: (1) Set up feature flag infrastructure, (2) Reduce CI pipeline time from 45 minutes to under 10, (3) Train team on short-lived branches, (4) Implement automated deployment from main, (5) Schedule removal of old flags after one month. This migration approach was used at DodaTech to accelerate delivery of Durga Antivirus Pro updates from bi-weekly to multiple times per day.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.