## 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
```text
"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