semantic-release "@semantic-release/git" step failed in CI

The @semantic-release/git plugin commits release assets (CHANGELOG, package.json) and pushes them back to the branch. It fails when the push is rejected: no write permission, a protected branch, or the branch moved ahead during the run.

What this error means

The run fails at "Failed step \"prepare\" of plugin \"@semantic-release/git\"" or a git push error while committing release files.

[semantic-release] > Failed step "prepare" of plugin "@semantic-release/git"
error: failed to push some refs to 'https://github.com/owner/repo.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

Common causes

The token cannot push the release commit

Missing contents write, a protected branch, or read-only credentials block the commit-and-push the git plugin performs.

The branch advanced during the run

Another push landed between analysis and the git plugin push, so the non-fast-forward push is rejected.

How to fix it

Ensure push permission and a bypass token

1. Grant contents: write and use a token that can push (App/PAT if protected).
2. Set fetch-depth: 0 and persist credentials so the push authenticates.
3. Add a concurrency group so runs do not race the branch.

permissions:
  contents: write
concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

Limit what the git plugin commits

Commit only the assets you intend so the push is minimal and predictable.

["@semantic-release/git", {
  "assets": ["CHANGELOG.md", "package.json"],
  "message": "chore(release): ${nextRelease.version} [skip ci]"
}]

How to prevent it

• Give the release job push permission and a bypass-capable token.
• Use a concurrency group so the branch does not move mid-run.
• Include [skip ci] in the release commit message to avoid loops.

Related guides