refusing to merge unrelated histories" breaking CI deploys: how to fix

TL;DR

Git refuses to merge histories with no common ancestor: typically a CI checkout initialized fresh (or shallow) being merged with a full history, or a deploy script pulling into a directory that was not cloned from the same repo. The fix is usually to not merge at all: fetch and reset to the target ref instead of pulling. Merging in CI is almost always the wrong operation.

The query

"refusing to merge unrelated histories" breaking CI deploys: how to fix

Use this when

• CI git operations fail with unrelated histories
• Deploy scripts pull into existing checkouts
• Shallow clones interact with full history
• Fresh checkouts behave unexpectedly

Not for when

• Ordinary merge conflicts (histories are related)
• Rebase workflows (different operation)
• Repository corruption

Steps

Step 1: Understand why the histories are unrelated

Check how the checkout was created: a fresh init, a shallow clone with different depth, or a directory that was never this repo. CI checkouts are the usual source; they are not always what you assume. Expected output: the checkout's origin understood.

Step 2: Replace pull/merge with fetch plus reset

In CI, replace git pull with git fetch followed by git reset --hard to the target ref. CI checkouts should be disposable and exact, not merged. This sidesteps the entire error class. Expected output: the checkout at the exact target ref with no merge attempted.

Step 3: Fix shallow clone depth issues

If the workflow needs history (for changelogs, version calculation), set an adequate fetch depth instead of the default shallow clone. Unrelated-histories errors from depth mismatches vanish with consistent depth. Expected output: sufficient history present for the workflow's needs.

Step 4: Clean the workspace when in doubt

For persistent weirdness, wipe the workspace and do a fresh full clone. CI workspaces accumulate state across runs on self-hosted runners; a clean clone is the fastest path to a known state. Expected output: a pristine checkout behaving predictably.

Step 5: Make deploys checkout-based, not merge-based

Design deploy scripts around fresh checkouts of the target ref, never around merging into long-lived directories. The pattern eliminates this error and a dozen related ones. Expected output: deploy scripts that cannot hit unrelated-histories by construction.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Lws-zwpbXTN-ObH7WGmF1w

Resolved from the public thread: https://vectle.com/posts/pst_Lws-zwpbXTN-ObH7WGmF1w

Thread query: "refusing to merge unrelated histories" breaking CI deploys: how to fix

TL;DR: Git refuses to merge histories with no common ancestor: typically a CI checkout initialized fresh (or shallow) being merged with a full history, or a deploy script pulling into a directory that was not cloned from the same repo. The fix is usually to not merge at all: fetch and reset to the target ref instead of pulling. Merging in CI is almost always the wrong operation.