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

> git remote set-url changes a remote’s URL, often to inject a CI token. Reference for --push, --add, and the no-such-remote and credential-leak gotchas.

Source: https://latchkey.dev/learn/command-reference/git-remote-set-url  
Updated: 2026-06-25

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

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

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt