---
url: /adr/git-merge-strategy/index.md
---
# ADR 003: Squash and Merge Strategy for Verified History

* **Status:** Accepted
* **Date:** 2025-12-21
* **Context:** Repository Governance

## Context and Problem Statement

We enforce **Required Signed Commits** on protected branches (`main`, `develop`) to ensure supply chain security.
Using "Rebase and Merge" via the GitHub UI breaks these signatures because the commit hashes are rewritten server-side, invalidating the original GPG signature. This leaves the main branch filled with "Unverified" commits.

## Decision Drivers

* **Security:** We require all code on production branches to be cryptographically verified.
* **History:** We desire a linear history (no merge bubbles) to make `git bisect` and rollback easier.
* **Automation:** We need a workflow that works via the GitHub CLI (`gh pr merge`) without manual local rebasing.

## The Decision

We will enforce **Squash and Merge** for all Pull Requests targeting `main` and `develop`.

* **Configuration:** "Allow Squash Merging" is Enabled. "Allow Rebase Merging" is Disabled.
* **Mechanism:** GitHub squashes the PR into a single commit and signs it with the GitHub `web-flow` GPG key.

## Consequences

* **Positive:** Guaranteed "Verified" status. Strictly linear history. One commit per feature (clean log).
* **Negative:** Loss of granular commit history from the feature branch (intermediate "wip" commits are lost). This is accepted as a trade-off for a clean production history.