Trunk-Based Development and Feature Flags Cheatsheet

Long-lived branches feel safe. Your feature is isolated, nobody breaks it, and you merge when it is "done". Then merge day arrives: three weeks of drift, conflicts in files you never touched, and a release that bundles twelve changes nobody can test in isolation.

Trunk-based development takes the opposite bet. Everyone integrates into one branch, at least daily, and the main branch is always releasable. The thing that makes this possible for work that takes longer than a day is separating deploy from release: code ships to production switched off, and a feature flag decides when users see it.

This post is a cheatsheet for both halves. It covers the rules, the branching variants, the CI that has to back them up, the kinds of feature flags and how to implement them, and the discipline that keeps flags from becoming the next source of outages.

1. The vocabulary

2. The rules, as DORA measures them

DORA's research (the team behind the Accelerate State of DevOps reports) found that teams practicing trunk-based development achieve higher software delivery and operational performance. Its capability guide reduces the practice to three checkable rules:

DORA also names the common blockers, and none of them are about Git:

• Heavy code review. If review takes days, people batch changes to avoid paying the cost twice. Small PRs need fast, ideally same-day, reviews.
• Asynchronous review only. Waiting overnight for a comment round trip doubles branch lifetime. Pairing or quick synchronous reviews help.
• Weak automated tests. If trunk is not protected by fast tests that run before merge, "always releasable" is a hope, not a property.

A note for 2026: the DORA 2025 report on AI-assisted development describes AI as an amplifier of whatever system it lands in. Coding assistants make it cheap to produce large diffs. Small batches, fast review and a strong test suite are what keep that extra output from turning into larger, riskier merges.

3. Two styles of trunk-based development

A typical day with short-lived branches:

git switch main && git pull --rebase
git switch -c feat/checkout-tax-rounding

# ... small change, tests, commit ...
git commit -am "Round tax per line item behind flag checkout.tax-per-line"

# Rebase on the latest trunk before opening the PR (keeps history linear)
git fetch origin && git rebase origin/main
git push -u origin feat/checkout-tax-rounding
gh pr create --fill --base main

# After approval: squash-merge and delete the branch
gh pr merge --squash --delete-branch

What about releases?

TBD does not forbid release branches. It forbids developing on them.

• Release from trunk (tag a commit and deploy it) when you deploy continuously.
• Cut a release branch from trunk when you must support a shipped version (mobile apps, on-premise software). Fixes land on trunk first and are cherry-picked to the release branch, never the other way around. No new features on release branches.

4. The CI that makes it safe

Trunk-based development moves risk from "merge day" to "every merge". That only works if every merge is verified quickly.

A minimal GitHub Actions workflow that supports a merge queue:

# .github/workflows/ci.yml
name: ci
on:
  pull_request:
  merge_group:          # required so the merge queue can run checks
permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@<full-commit-sha>
      - uses: astral-sh/setup-uv@<full-commit-sha>
      - run: uv sync --locked
      - run: uv run pytest -q

5. Large changes without long-lived branches

"This feature takes six weeks" is not a reason for a six-week branch. Three techniques cover nearly every case.

Branch by abstraction in miniature:

from typing import Protocol


class TaxCalculator(Protocol):
    def tax(self, lines: list[tuple[int, float]]) -> int: ...


class LegacyTax:
    """Rounds once on the order total (old behavior). Amounts in cents."""

    def tax(self, lines: list[tuple[int, float]]) -> int:
        return round(sum(amount * rate for amount, rate in lines))


class PerLineTax:
    """Rounds per line item (new behavior, required in some jurisdictions)."""

    def tax(self, lines: list[tuple[int, float]]) -> int:
        return sum(round(amount * rate) for amount, rate in lines)


def tax_calculator(flags, ctx) -> TaxCalculator:
    # Step 4: the switch. Step 5 deletes LegacyTax and this function.
    if flags.is_enabled("checkout.tax-per-line", ctx):
        return PerLineTax()
    return LegacyTax()

6. The four kinds of feature flags

Pete Hodgson's classification on Martin Fowler's site is still the most useful one. The category decides how long a flag should live and how it should be managed.

Two practical consequences:

• Release and experiment toggles are temporary. Each one should have an owner and a removal date when it is created.
• Permission toggles are product logic. Once a flag is a permanent entitlement, it often belongs in your authorization model, not in a flag system.

7. Implementing flags: evaluation, targeting, rollout

A flag check takes a flag key, an evaluation context (user, account, region, environment) and a default. The default matters: it is what you get when the flag service is down or the key is missing, so it must be the safe behavior.

A self-contained evaluator with deterministic percentage rollout:

import hashlib
from dataclasses import dataclass, field


@dataclass
class Flag:
    key: str
    enabled: bool = False                            # global kill switch
    rollout_percent: int = 0                         # 0-100
    allow: set[str] = field(default_factory=set)     # always on for these users
    deny: set[str] = field(default_factory=set)      # always off for these users


def bucket(flag_key: str, user_id: str) -> int:
    """Stable 0-99 bucket: the same user always lands in the same bucket per flag."""
    digest = hashlib.sha256(f"{flag_key}:{user_id}".encode()).hexdigest()
    return int(digest[:8], 16) % 100


def is_enabled(flag: Flag | None, user_id: str, default: bool = False) -> bool:
    if flag is None:
        return default                    # unknown flag: safe default
    if not flag.enabled or user_id in flag.deny:
        return False
    if user_id in flag.allow:
        return True
    return bucket(flag.key, user_id) < flag.rollout_percent


tax = Flag("checkout.tax-per-line", enabled=True, rollout_percent=10, allow={"qa-team"})
users = [f"user-{i}" for i in range(10_000)]
share = sum(is_enabled(tax, u) for u in users) / len(users)
print(f"{share:.1%} of users see the new tax logic")  # close to 10%
print(is_enabled(tax, "qa-team"))                     # True
print(is_enabled(None, "user-1"))                     # False (safe default)

Hashing the flag key together with the user ID keeps rollouts sticky (raising 10% to 25% keeps the first 10% in) and independent across flags (the same users are not always the guinea pigs).

In production, use a flag service or library rather than your own. To avoid tying application code to one vendor, OpenFeature (a CNCF incubating project since December 2023) defines a vendor-neutral API with providers for most commercial and open source flag systems:

from openfeature import api
from openfeature.evaluation_context import EvaluationContext

# api.set_provider(...)  # your vendor's or an open source provider, set once at startup
client = api.get_client()

ctx = EvaluationContext(targeting_key=user.id, attributes={"plan": user.plan})
if client.get_boolean_value("checkout.tax-per-line", False, ctx):
    ...

Implementation rules that hold for any system:

8. Progressive delivery: release in steps

A flag on its own is a light switch. Combined with metrics, it becomes a controlled rollout.

Define the guardrail metrics and the rollback trigger before stage 1. "Roll back if checkout error rate rises by more than 0.5 percentage points over the control group" is a decision you can automate. "Roll back if something looks wrong" is not.

This applies to configuration and infrastructure as much as to features. In Google Cloud's June 12, 2025 outage, a new quota-checking code path in Service Control was not protected by a feature flag; a policy change with blank fields hit it in every region and crashed the binaries. Google's incident report states that with flag protection the issue would have been caught in staging, and commits to making changes to critical binaries flag-protected and disabled by default.

9. Flag debt: the part teams skip

Every flag doubles the number of code paths it touches. Ten interacting flags are over a thousand combinations, and nobody tests them all.

The cautionary tale is Knight Capital in August 2012. According to the SEC order, a new deployment repurposed an old flag that had once activated retired "Power Peg" code. A technician did not deploy the new code to one of eight servers, so on that server the reused flag triggered the dead code. In about 45 minutes the system sent millions of orders and Knight lost more than $460 million. Dead code, a reused flag and a manual deploy: every item in this section was missing.

A cheap "time bomb" test that fails CI when a temporary flag outlives its date:

from datetime import date

TEMPORARY_FLAGS = {
    # key: (owner, remove_by)
    "checkout.tax-per-line": ("payments-team", date(2026, 6, 15)),
    "pricing-page.variant": ("growth-team", date(2026, 5, 31)),
}


def test_no_expired_flags():
    expired = {k: v for k, v in TEMPORARY_FLAGS.items() if v[1] < date.today()}
    assert not expired, f"Remove or re-justify expired flags: {expired}"

10. Anti-patterns

Why this matters

• Small batches are the lever. Integration pain, review quality and blast radius all scale with change size. Trunk-based development keeps batches small by design.
• Deploy and release are different decisions. Separating them lets engineering ship continuously while product decides when users see a change.
• Flags are a safety system. Percentage rollouts and kill switches turn a bad change into a partial, reversible event instead of a global outage.
• Flags are also inventory. Every flag has a carrying cost. Owners, expiry dates and removal as part of "done" keep the cost bounded.
• The pipeline is the contract. Fast required checks, a merge queue and a "revert first" rule are what make "always releasable" true.

Final Thoughts

Trunk-based development is less about Git than about habits: merge small changes daily, keep trunk green, and never let a branch become the place where work hides. Feature flags make those habits possible for work that is bigger than a day.

Start by measuring what you have: count branches older than two days and flags older than their purpose. Then move one team to short-lived branches with a merge queue, put the next feature behind a flag with an owner and an expiry date, and delete the flag when it ships.

Sources

• DORA, Capabilities: Trunk-based development: three or fewer active branches, merging at least daily, no code freezes; common pitfalls and measures.
• DORA, 2025 State of AI-assisted Software Development Report (September 2025): AI as an amplifier of existing practices.
• Paul Hammant, Trunk Based Development: committing to trunk vs. short-lived branches, branch by abstraction, release branches and cherry-picking.
• Martin Fowler, Continuous Integration (2024): integration frequency, keeping the mainline healthy, fixing broken builds immediately.
• Pete Hodgson, Feature Toggles (aka Feature Flags) (October 2017): release, experiment, ops and permission toggles; toggle debt; testing configurations.
• Martin Fowler, BranchByAbstraction (2014).
• GitHub, GitHub merge queue is generally available (July 2023).
• CNCF, OpenFeature becomes a CNCF incubating project (December 2023).
• Google Cloud, Service Health incident report for the June 12, 2025 outage (June 2025): missing feature flag protection and the commitment to flag-protect critical binary changes.
• U.S. Securities and Exchange Commission, In the Matter of Knight Capital Americas LLC (October 2013): repurposed flag, Power Peg code, more than $460 million lost in about 45 minutes.