gh repo clone: Usage, Options & Common CI Errors

Clone a repo with gh - auth and fork-remote setup handled for you.

gh repo clone clones a repository using gh’s authentication, so private repos and forks work without manual credential setup. It accepts owner/repo shorthand and passes extra args to git.

What it does

gh repo clone <owner/repo> clones the repo over gh’s authenticated transport. For your own fork it also adds an "upstream" remote pointing at the parent. Anything after -- is forwarded to git clone, so depth, branch, and other flags work as usual.

Common usage

# Clone by shorthand
gh repo clone cli/cli

# Clone into a directory
gh repo clone owner/repo my-dir

# Pass git flags after -- (shallow, single branch)
gh repo clone owner/repo -- --depth=1 --branch=main

Common error in CI: authentication failed on private repo

gh repo clone fails with "could not read Username for https://github.com" or HTTP 403 cloning a private repo when gh is not authenticated in the job. Fix: export GH_TOKEN (with repo scope) before cloning; gh uses it automatically. For shallow CI clones, forward git flags after -- (e.g. -- --depth=1). In GitHub Actions, prefer actions/checkout for the main repo and use gh repo clone for additional repos with a token that can read them.

Key options

Related guides