gh pr checkout: Usage, Options & Common CI Errors

Check out any pull request branch locally - even from a fork.

gh pr checkout fetches a pull request’s head branch and switches to it, handling the fork remote setup for you. It is the quickest way to test someone’s PR locally or in CI.

What it does

gh pr checkout <number|branch|url> fetches the PR’s commits and checks out a local branch tracking them, configuring the fork’s remote when the PR comes from a fork. It saves the manual git fetch origin pull/N/head dance.

Common usage

# Check out PR #42 locally
gh pr checkout 42

# Check out by URL or branch name
gh pr checkout https://github.com/owner/repo/pull/42

# Give the local branch a custom name
gh pr checkout 42 --branch review-42

Common error in CI: shallow clone / detached HEAD checkout fails

In CI, gh pr checkout can fail to find PR refs because actions/checkout does a shallow, single-branch fetch, or you have no repo remote. Fix: pass --repo owner/name, ensure GH_TOKEN is exported, and if you need full history fetch with depth 0 first (actions/checkout fetch-depth: 0). For most CI you do not need this at all - actions/checkout already checks out the PR merge ref; use gh pr checkout mainly for ad-hoc local review.

Key options

Related guides