# git push: Usage, Options & Common CI Errors

> git push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected non-fast-forward and permission errors.

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

git push sends your local branch commits to a remote repository.

Pushing publishes your work. Most CI push failures are auth, protected branches, or a remote that moved ahead of you.

## What it does

git push updates remote refs (branches/tags) using your local commits and uploads the objects needed to complete them.

## Common usage

```Terminal
git push                              # to the tracked upstream
git push -u origin feature           # push + set upstream
git push origin --tags               # push all tags
git push --force-with-lease          # safer force push
```

## Options

| Flag | What it does |
| --- | --- |
| -u / --set-upstream | Record the remote branch as upstream |
| --force-with-lease | Force only if remote matches your last fetch |
| --tags | Push tags as well |
| --delete | Delete a remote ref |
| --atomic | All-or-nothing for multiple refs |

## Common errors in CI

! [rejected] main -> main (non-fast-forward) / "Updates were rejected because the remote contains work that you do not have locally" - fetch and rebase, then push: git pull --rebase origin main. "remote: Permission to owner/repo.git denied" means the token lacks write/contents permission. On protected branches a direct push may be blocked entirely.

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

Pushing publishes your work. Most CI push failures are auth, protected branches, or a remote that moved ahead of you.

### What it does?

git push updates remote refs (branches/tags) using your local commits and uploads the objects needed to complete them.

### Common errors in CI?

! [rejected] main -> main (non-fast-forward) / "Updates were rejected because the remote contains work that you do not have locally" - fetch and rebase, then push: git pull --rebase origin main. "remote: Permission to owner/repo.git denied" means the token lacks write/contents permission.

---

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