git remote set-url: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git remote set-url rewrites the URL behind an existing remote name.

Swapping origin from SSH to an HTTPS token URL (or vice versa) is the most common CI use. Keep tokens out of logs and out of committed config.

What it does

git remote set-url replaces the fetch URL of a named remote (and optionally the push URL), without changing tracking config or fetched refs.

Common usage

Terminal

git remote set-url origin https://github.com/owner/repo.git
git remote set-url --push origin git@github.com:owner/repo.git
git remote set-url --add origin https://mirror.example.com/repo.git
git remote set-url origin https://x-access-token:${'$'}{TOKEN}@github.com/owner/repo.git

Options

Flag	What it does
<name> <newurl>	Set the fetch URL
--push	Set the push URL instead
--add	Add an extra URL rather than replace
--delete <pattern>	Remove URLs matching a pattern

Common errors in CI

error: No such remote ‘origin’ - the remote name does not exist (fresh git init, or a different name). Add it first. Beware embedding a token in the URL: it can be written to .git/config and leak in logs; prefer a credential helper or http.extraheader, and never echo the URL.

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.

.github/workflows/ci.yml

- 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

git remote set-url: Usage, Options & Common CI Errors?