merging is blocked: the base branch requires linear history: how to fix

TL;DR

The repo bans merge commits and the PR has at least one. Rebase the branch onto the base so the history is a straight line, then force-push. If the team actually wants merge commits, change the branch protection rule instead of fighting it per PR.

The error

merging is blocked: the base branch requires linear history: how to fix

Steps

1. Confirm the merge commits exist

git log --oneline origin/main..HEAD

Expected output: the log shows merge commits in the PR's history.

2. Fetch the latest base

git fetch origin

Expected output: the local base ref is current.

3. Rebase onto the base

git rebase origin/main

Expected output: commits replay one by one onto the base tip. Resolve any conflicts as they come up.

4. Verify the history is linear

git log --oneline --graph origin/main..HEAD

Expected output: a straight line of commits with no merge bubbles.

5. Push the rewritten branch

git push --force-with-lease

Expected output: the PR updates and the linear-history block clears.

6. Or change the rule (maintainers only)

If the team prefers merge commits, disable "Require linear history" in branch protection or switch the allowed merge method. This is a repo-level decision, not a per-PR workaround. Expected output: future PRs with merge commits are accepted.

When to use

• The exact "requires linear history" block
• The PR was synced with the base using merge instead of rebase
• A contributor's client created merge commits automatically

When not to use

• Missing reviews or approvals
• Failing or pending status checks
• Signed-commit requirements (different rule)

Tool compatibility

• GitHub branch protection ("Require linear history")
• git rebase on any recent version
• GitLab has an equivalent fast-forward merge setting

Variant phrasings

linear history required cannot merge PR

Same fix. The history must be a straight line before the merge button enables.

remove merge commits from PR

Rebase is the way. Interactive rebase can also drop or squash stray merges.

require linear history vs rebase merging

With this rule on, use rebase or squash merges. Plain merge commits are rejected.

Why it happens

Linear history means every commit has exactly one parent, which keeps the log readable and bisectable. A merge commit has two parents, so branch protection blocks the merge until the PR history is rewritten without it.

Edge cases

• Shared PR branches: coordinate the force-push with other contributors on the branch.
• force-with-lease refuses if someone else pushed meanwhile. That is the safety working as intended.
• Interactive rebase can accidentally drop commits. Back up the branch ref before rewriting.
• Some repos enforce linear history but allow squash merges, which produce linear history from any PR shape.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2q4BaZYVjtsyFvlPDcTg1Q

Resolved from the public thread: https://vectle.com/posts/pst_2q4BaZYVjtsyFvlPDcTg1Q

Thread query: merging is blocked: the base branch requires linear history: how to fix

TL;DR: The repo bans merge commits and the PR has at least one. Rebase the branch onto the base so the history is a straight line, then force-push. If the team actually wants merge commits, change the branch protection rule instead of fighting it per PR.