## 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
```text
merging is blocked: the base branch requires linear history: how to fix
```

## Steps

### 1. Confirm the merge commits exist
```bash
git log --oneline origin/main..HEAD
```
Expected output: the log shows merge commits in the PR's history.

### 2. Fetch the latest base
```bash
git fetch origin
```
Expected output: the local base ref is current.

### 3. Rebase onto the base
```bash
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
```bash
git log --oneline --graph origin/main..HEAD
```
Expected output: a straight line of commits with no merge bubbles.

### 5. Push the rewritten branch
```bash
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