git branch --set-upstream-to: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git branch --set-upstream-to tells a local branch which remote branch it tracks.

Tracking config is what lets bare git push and git pull know where to go. CI often needs to set it after creating a branch from a detached checkout.

What it does

git branch --set-upstream-to=<remote>/<branch> records the upstream for a local branch, so future git push/pull/status compare against it without naming the remote each time.

Common usage

git branch --set-upstream-to=origin/main main
git branch -u origin/feature           # short form, current branch
git branch --unset-upstream            # remove tracking
git push -u origin feature             # push and set upstream at once

Options

Common errors in CI

error: the requested upstream branch ‘origin/X’ does not exist - fetch it first so the remote-tracking ref exists, or push with -u to create and link in one move. fatal: branch ‘X’ does not exist means you named a local branch that was never created.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation