git remote add: Usage, Options & Common CI Errors
git remote add gives a URL a short name like upstream so you can fetch and push to it.
Adding an upstream or a token-bearing remote is a routine CI step. The main pitfall is re-running the command and hitting "already exists" - make the script idempotent.
What it does
git remote add creates a new remote entry mapping a name to a fetch (and push) URL and sets up the default refspec for that remote.
Common usage
git remote add upstream https://github.com/owner/repo.git
git remote add -f --tags upstream https://github.com/owner/repo.git
git remote add -t main origin https://github.com/owner/repo.git
# idempotent pattern:
git remote add upstream <url> 2>/dev/null || git remote set-url upstream <url>Options
| Flag | What it does |
|---|---|
| <name> <url> | Register the remote |
| -f | Fetch immediately after adding |
| -t <branch> | Track only the named branch(es) |
| --tags / --no-tags | Control tag following on fetch |
| -m <branch> | Set the remote’s default HEAD branch |
Common errors in CI
error: remote <name> already exists - a re-run of the job. Guard with the || git remote set-url pattern, or check git remote get-url first. A bad URL surfaces later as "does not appear to be a git repository" on the first fetch.
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