# git remote: Usage, Options & Common CI Errors

> git remote manages the named connections to remote repositories. Reference for add, set-url, -v, remove, and "remote already exists" and URL errors.

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

git remote manages the short names (like origin) that point at remote repository URLs.

Remotes map names to URLs. In CI you often add or rewrite a remote to inject a token-bearing URL.

## What it does

git remote lists, adds, renames, and removes the named remotes for a repository, and can change their fetch/push URLs.

## Common usage

```Terminal
git remote -v                     # list remotes with URLs
git remote add upstream https://github.com/owner/repo.git
git remote set-url origin https://x-access-token:${TOKEN}@github.com/owner/repo.git
git remote remove upstream
git remote show origin
```

## Options

| Subcommand | What it does |
| --- | --- |
| add <name> <url> | Add a new remote |
| set-url <name> <url> | Change a remote URL |
| remove / rm <name> | Delete a remote |
| rename <old> <new> | Rename a remote |
| -v | List remotes with their URLs |

## Common errors in CI

error: remote origin already exists - use git remote set-url instead of add, or remove it first. fatal: 'X' does not appear to be a git repository means a bad URL or unreachable host; verify the URL and that credentials are embedded or available.

## 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: Usage, Options & Common CI Errors?

Remotes map names to URLs. In CI you often add or rewrite a remote to inject a token-bearing URL.

### What it does?

git remote lists, adds, renames, and removes the named remotes for a repository, and can change their fetch/push URLs.

### Common errors in CI?

error: remote origin already exists - use git remote set-url instead of add, or remove it first. fatal: 'X' does not appear to be a git repository means a bad URL or unreachable host; verify the URL and that credentials are embedded or available.

---

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