Branching Strategy Template (Trunk-Based, SLSA Source)

Branching Strategy: [Repository, product or organisation name]

Standard for how code changes flow through version control: the chosen branching model and why, branch types and naming, numbered policy statements, protection rules for each protected branch, commits, pull requests and merge methods, release branches, tags and hotfixes, handling long-running work, exceptions, compliance measurement and review. Aligned with the SLSA specification v1.2 Source track (protected references, continuous history, technical controls and two-party review), the DORA capability "trunk-based development" (dora.dev), Conventional Commits 1.0.0 and Semantic Versioning 2.0.0. Replace every [bracketed] value and every row marked Example. Worked examples use Corvid Commerce, a fictional SaaS company that runs an online checkout platform.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Roles and responsibilities
3. Branching model selection
4. Branch types and naming
5. Policy statements
6. Protection rules
7. Commits, pull requests and merging
8. Releases, tags and hotfixes
9. Long-running and risky work
10. Exceptions and emergency changes
11. Compliance measurement
12. Adoption and migration
13. Review cycle and related documents
14. Glossary and references

1. Purpose and scope

1.1 Purpose

This standard sets one way of integrating, reviewing and releasing code across [Organisation]. It aims to keep the default branch always releasable, to make every change reviewed and traceable, to give release engineering a predictable flow for patches, and to provide the source integrity controls that auditors and customers expect.

1.2 Scope

1.3 Applicability

All people with write access to in-scope repositories, including contractors and automation accounts, follow this standard. Automation accounts follow the same protection rules as people unless listed in the bypass register (section 10.3).

2. Roles and responsibilities

R = responsible, A = accountable, C = consulted, I = informed.

3. Branching model selection

3.1 Candidate models

3.2 Decision criteria

Example: Scores run from 1 (poor) to 3 (good). Trunk-based scores (3 x 3) + (2 x 1) + (3 x 3) + (2 x 3) + (2 x 3) = 9 + 2 + 9 + 6 + 6 = 32. Trunk with release branches scores 6 + 6 + 9 + 4 + 6 = 31. GitHub flow scores 9 + 2 + 6 + 6 + 6 = 29. Git flow scores 3 + 6 + 3 + 2 + 4 = 18.

3.3 Decision

Example: Corvid Commerce adopts trunk-based development with short-lived branches for all SaaS services. The on-premises payment connector, which customers install and for which two minor versions are supported, adds release branches per minor version. Git flow is not used for new repositories. Record the decision in Architecture Decision Record (dev/adr) as [ADR-021].

DORA describes trunk-based development as few active branches, branches that live for hours rather than days, merges into trunk at least daily and no code freeze or integration phase. Use these as the behaviours to measure in section 11.

4. Branch types and naming

Allowed <type> prefixes: feat, fix, docs, refactor, test, chore, perf, ci, build, aligned with the commit types in section 7.1. Use lower-case letters, digits and hyphens only; names are at most [60] characters.

5. Policy statements

The key words MUST, MUST NOT, SHOULD and MAY are used as requirement levels in this section.

6. Protection rules

6.1 Ruleset per reference

6.2 Mapping to SLSA Source track

Example: The checkout monorepo (tier 1) meets Level 3 today because source provenance is issued and the organisation rulesets have been continuously enforced since revision [abc1234]. Payment service repositories target Level 4: they already require two approvers, and they claim Level 4 once [90 days] of continuous enforcement with an empty bypass list is evidenced. Tier 2 repositories target Level 3. Read the SLSA source requirements page for the normative wording before claiming a level.

7. Commits, pull requests and merging

7.1 Commit messages

Commits that land on main follow Conventional Commits 1.0.0: a type, an optional scope, an optional ! for a breaking change, a colon and a short imperative description. A BREAKING CHANGE: footer explains incompatible changes. With squash merging, the pull request title becomes the commit message, so the title check enforces the format.

feat(checkout)!: require idempotency key on payment capture

BREAKING CHANGE: clients must send the Idempotency-Key header on POST /captures.
Refs: CHK-812

The release pipeline derives the next version from these types according to Versioning and Release Policy (dev/versioning-release-policy): fix gives a patch, feat a minor and a breaking change a major increment under Semantic Versioning 2.0.0. Before 1.0.0, record in Versioning and Release Policy how breaking changes are numbered, because major version zero carries no stability promise.

7.2 Pull request rules

1. Keep pull requests small: Example: fewer than [400] changed lines excluding generated files and lockfiles. Reviewers may ask for a split above that size.
2. Fill in the pull request description using the Pull Request template (dev/pull-request): what changed, why, how it was tested, and the linked ticket.
3. Open draft pull requests early for design feedback; code owners are requested when the pull request is marked ready.
4. Review within the service levels in Code Ownership Policy (dev/code-ownership-policy).
5. The author merges after approval and green checks, unless the repository uses an automatic merge queue.

7.3 Merge methods

7.4 Merge flow

The flow shows a change from branch creation to deployment when a merge queue is used.

8. Releases, tags and hotfixes

8.1 SaaS services (trunk only)

Each merge to main produces a build that the pipeline deploys. A release is the deployment of a specific digest; the pipeline tags the commit with the version computed from commit types. Hotfixes are ordinary small pull requests to main that follow the emergency path in section 10.2 when urgent. Rolling back is a revert pull request or a promotion of the previous digest, as defined in CI/CD Pipeline Design (dev/ci-cd-pipeline-design).

8.2 Installed software (trunk with release branches)

The diagram shows a fix that reaches two supported minor versions.

1. The release manager creates release/<major>.<minor> from main at the agreed cut point and announces it.
2. Only fixes and release-stabilising changes enter a release branch, each through a pull request that references the original commit on main.
3. The release pipeline tags v<major>.<minor>.<patch> on the release branch; tags are never moved.
4. When a minor version reaches end of support, the release branch is locked (read-only) and kept for history.
5. Every release follows Release Checklist (dev/release-checklist).

8.3 Hotfix worked example

Example: A defect in tax rounding (CHK-901) affects v4.2.4 and v4.3.0 of the on-premises connector. The fix merges to main as fix(tax): round half-even per invoice line. Cherry-pick pull requests to release/4.3 and release/4.2 pass the release test suite, receive two approvals each and are tagged v4.3.1 and v4.2.5 by the release pipeline. The fix reaches all supported versions within [2 working days].

9. Long-running and risky work

When a branch must live longer than the BR-POL-007 maximum (for example a vendor-mandated framework upgrade), the owner records an exception (section 10.1) and rebases on main at least daily.

10. Exceptions and emergency changes

10.1 Exception process

1. The repository maintainer requests an exception with the rule ID, scope, reason, compensating control and end date.
2. AppSec reviews the risk; the engineering director approves exceptions longer than [30 days].
3. The exception is recorded in the register below and reviewed at expiry. Expired exceptions are closed or renewed with a new approval.

10.2 Emergency changes

During a declared incident the incident commander may authorise a reduced path: one approver where two are normally required (release/* and payment services), and non-security checks marked as not required for that pull request. The platform team applies the change as a time-boxed ruleset adjustment, logged in the bypass register (10.3) and reverted when the incident closes. Code owner review, at least one independent approval, security checks, signing and history rules still apply. The change is reviewed by a code owner within [one working day] after the incident and listed in the postmortem (dev/postmortem).

10.3 Bypass register

10.4 Safe expunging

Rewriting history on a protected branch is allowed only to remove leaked secrets, personal data or content under a legal takedown. The platform lead and AppSec approve it, the secret is rotated first, the operation is logged with the before and after commit identifiers, and affected teams are told to re-clone.

11. Compliance measurement

Example: In September the checkout monorepo merged 410 pull requests. The median branch lifetime was 0.6 working days, 7 branches exceeded 5 working days and 1 of them was covered by BR-EXC-002, so BR-MET-003 is 6 and the six owners were contacted. Ruleset coverage was 39 of 41 repositories (95.1%); the two gaps were new repositories created outside the template.

Report these metrics monthly to the platform team and quarterly in Delivery Performance Report (dev/delivery-performance-report). Use them to improve the system, never to rank individuals.

12. Adoption and migration

13. Review cycle and related documents

Review this standard at least annually, after any change to the source platform's protection features, after a source integrity incident, and when the SLSA Source track changes. The platform team exports the live ruleset configuration at each review and compares it with section 6.

Related documents:

• Code Ownership Policy (dev/code-ownership-policy) for code owner assignment and review service levels.
• Versioning and Release Policy (dev/versioning-release-policy) for version numbers and support windows.
• CI/CD Pipeline Design (dev/ci-cd-pipeline-design) for required checks and deployment.
• Feature Flag Policy (dev/feature-flag-policy) for hiding unfinished work.
• Software Configuration Management Plan (quality/scm-plan) for baselines and configuration control.
• Contributing guide (dev/contributing) and Governance (dev/governance) for open-source contributors and maintainers.
• Software Supply Chain Security Assessment (security/supply-chain-security) for the SLSA assessment across tracks.

14. Glossary and references

14.1 Glossary

14.2 References

Standard and licence note

Based on the SLSA specification v1.2 Source track; SLSA level names and requirement concepts are used with attribution to the SLSA project (slsa.dev), published under the Community Specification License 1.0, and level meanings here are paraphrased. Trunk-based development behaviours follow the DORA capability page on dora.dev (Google LLC, CC BY 4.0). Conventional Commits 1.0.0 (CC BY 3.0) and Semantic Versioning 2.0.0 (CC BY 3.0) are cited by name and rule. Ruleset setting names reflect GitHub documentation; GitHub and GitLab are trademarks of their owners; this template is not affiliated with or endorsed by them, and the rules apply to any Git hosting platform with equivalent controls. Git flow is described from general knowledge and cited, not copied. Corvid Commerce is fictional. This template is original text written for this collection. Check the current official versions of each source before use. Template licence: MIT.