git remote: Usage, Options & Common CI Errors
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 originOptions
| 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 detachedFrequently asked questions
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.
Related guides
git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree.
git push: Usage, Options & Common CI Errorsgit push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected
git clone: Usage, Options & Common CI Errorsgit clone copies a remote repository into a new local directory.
git ls-remote: Usage, Options & Common CI Errorsgit ls-remote lists refs on a remote without cloning. Reference for --heads, --tags, --exit-code, and the