PR lifecycle and merge strategies — squash, merge commit, and rebase

A PR ends when merged or closed. The merge strategy determines the trunk’s shape. Squash, merge commit, rebase — three strategies, three histories, three audit consequences.

The PR lifecycle

A PR moves through six states. Draft — change being prepared. Open — change ready. Changes requested — reviewer asked for revisions. Approved — required approvals met. Merged — merge event on base ref. Closed — withdrawn or rejected.

stateDiagram-v2
    [*] --> Draft
    Draft --> Open: ready for review
    Open --> ChangesRequested: reviewer asks for revisions
    ChangesRequested --> Open: author pushes fix
    Open --> Approved: required approvals met
    Approved --> Merged: merge button pressed
    Open --> Closed: withdrawn or rejected
    Merged --> [*]
    Closed --> [*]

The three merge strategies

gh pr merge 123 --squash --subject "feat(login): v2 login path" --body "Closes #456"
gh pr merge 123 --merge
gh pr merge 123 --rebase

Squash collapses the branch into one commit on the base ref. Merge commit keeps the head’s commits and adds a merge commit with two parents. Rebase replays the head commits onto the base ref; no merge commit.

flowchart LR
    subgraph squash["squash"]
        M1["main"] --> S["single commit on main"]
        S --> S1["tip"]
        F1["feature: a,b,c"] -. "collapsed" .-> S
    end
    subgraph merge["merge commit"]
        M2["main"] --> N1["main tip"]
        N1 --> M["merge commit"]
        F2["feature: a,b,c"] --> M
        M --> M3["new main tip"]
    end
    subgraph rebase["rebase"]
        M4["main tip"] --> R1["a'"]
        R1 --> R2["b'"]
        R2 --> R3["c'"]
        R3 --> R4["new main tip"]
        F3["feature: a,b,c"] -. "replayed" .-> R4
    end

The trade-off

The trade-off is between readable history and atomic history. Squash produces a trunk where each commit is one atomic change — easy to revert, easy to bisect. Merge commit preserves the conversation but is harder to read. Rebase is linear like squash but preserves commits, so the audit trail no longer matches the conversation.

For an infrastructure repository, the operational answer is usually squash with a detailed PR description. The description is where the rationale lives; the squash commit is where the change lives.

Production discipline

1. Pick one strategy per repository. Mixed trunk is harder to read and bisect.
2. Document the choice in CONTRIBUTING.md.
3. Configure the squash author. Default to the PR author.
4. Use a detailed PR description. When squashing, the description is the audit trail.
5. Disable force-push to merged branches.

Cross-course references

• GitOps with Argo CD - Part IV (SyncPatterns): how merge strategy interacts with the GitOps sync trigger.
• CI/CD Pipeline Patterns - Part VI (ReleaseEngineering): how merge strategy interacts with release tagging.
• Terraform for Production Sysadmins - Part XI (PRWorkflows): the Terraform-specific merge strategy decision.

Quiz