Skip to content

shipping to main

Why GitHub says your branch is out-of-date with the base branch, and how to stop the update loop

Othman Shareef · November 22, 2026 · 5 min read


GitHub says “This branch is out-of-date with the base branch” when someone merged into the base after your branch was last updated, and the repository requires branches to be up to date before merging. To unblock it, click Update branch on the pull request, wait for the required checks to pass on the new commit, then merge. If another pull request lands first, you will see the message again. That loop is what a merge queue is for.

What does “This branch is out-of-date with the base branch” mean?

Your checks ran against an older version of the base branch. Required status checks can be strict or loose, per GitHub’s docs on protected branches. With Require branches to be up to date before merging checked, the checks are strict and the branch must be up to date with the base before it can merge. GitHub notes this is the default for required status checks. The same checkbox exists in rulesets, under Require status checks to pass before merging.

You can also see the update prompt on a repository with no such rule. The Always suggest updating pull request branches setting gives people with write access the option to update any branch that is behind, whether or not the base requires it. Then the button is optional and nothing stops the merge.

How do I fix it with Update branch?

Per the docs on keeping a pull request in sync, you can update from the pull request page when there are no merge conflicts and the branch is behind the base. Clicking Update branch performs a traditional merge of the base into your branch. The new merge commit is a new head, so every required check runs again, and the pull request can merge once they pass.

If the base conflicts with your branch, the button is not offered, so resolve the conflicts first. If the head branch is itself protected, the docs warn that Update branch may not work at all. Update it locally and push instead.

Update with merge commit or Update with rebase?

The dropdown next to the button offers Update with merge commit and Update with rebase. The merge keeps your commits as they are and adds one merge commit. Rebase replays your commits on top of the latest base, which GitHub describes as a linear history without a merge commit. Rebasing rewrites those commits, so anyone else with the branch checked out has to reset to the new history. Pick rebase on a branch only you push to, and merge on a shared one. If the repository squashes on merge, the difference mostly disappears from main anyway.

Watch your approvals too. If the branch dismisses stale approvals, an update that changes the diff can cost you the approval you already had. Our post on required reviews covers how that rule behaves.

Why does my branch keep going out of date?

Main keeps moving while your checks run. You update, CI starts, and ten minutes later a teammate merges. You’re behind again and the button is back. With a dozen merges a day and slow CI, one pull request can go around several times, and every author racing for the same slot pays for a full build each round. GitHub’s comparison table says as much: strict checks mean more builds, because you update the head branch every time someone else updates the target. Auto-merge saves the clicking once checks pass, and you still lose the race to whoever merges first.

Unchecking the setting ends the loop and gives up the guarantee. With loose checks, GitHub warns that status checks may fail after you merge if your change is incompatible with the base, which is how two green pull requests can break main between them.

How does a merge queue fix the update loop?

Per GitHub’s merge queue docs, it provides the same benefits as Require branches to be up to date before merging, but it does not require a pull request author to update their branch and wait for status checks before trying to merge. Once a pull request passes its required checks, anyone with write access adds it to the queue. The queue builds a temporary branch from the latest base, plus the pull requests ahead of it, runs the required checks there, and merges what passes.

Your GitHub Actions workflows must trigger on the merge_group event, or the checks never run for queued pull requests. A branch protection rule with wildcard characters in its branch name pattern cannot use a merge queue. For the full walkthrough, see the GitHub merge queue, explained, or what a merge queue is if the idea is new.

If you review in Pyor, Update branch is in the status pill in the pull request header, so the update loop at least doesn’t send you back to github.com.

Frequently asked questions

Why does GitHub say this branch is out-of-date with the base branch?

Someone merged into the base branch after your branch was last updated, and the repository either requires branches to be up to date before merging or always suggests updating pull request branches. Click Update branch to bring the new base commits in, then wait for the required checks to pass on the new head commit.

Should I update my branch with a merge commit or with rebase?

Update branch performs a traditional merge by default, which adds a merge commit and leaves your existing commits alone. Update with rebase replays your commits on top of the latest base for a linear history, but it rewrites them, so anyone else working on the branch has to reset their local copy. Use rebase on branches only you push to.

Can I turn off Require branches to be up to date before merging?

Yes. Unchecked, GitHub calls the status checks loose: the branch can merge while behind the base, and you run fewer builds. The cost, per GitHub, is that checks may fail after you merge if your change is incompatible with what landed in the meantime. On a busy branch, a merge queue keeps the guarantee without the manual updates.

Review your next PR in Pyor.

Pyor’s merge box updates the branch, merges with any method the repo allows, turns on auto-merge, or joins the merge queue, in the same window you review in. Free for individuals, and it talks to GitHub straight from your machine.