semantic-release "The push permission to the Git repository is required"

TL;DR

Give the release job a token with push scope and make the checkout persist credentials. If branch protection blocks the push, allow the release bot or use a dedicated release branch. Verify with a dry run before the real release.

The exact error

The push permission to the Git repository is required

Steps

1. Check the token scopes Inspect the token used by the release job. It needs write access to contents; read-only tokens fail with this exact error. Success check: You know the token's scopes and whether push is allowed.

2. Persist checkout credentials In the CI checkout step, enable credential persistence so the release step can push with the same token. Success check: The git remote uses the release token, not an anonymous or read-only credential.

3. Handle branch protection If the target branch is protected, add the release bot to the bypass list or release from an unprotected branch. Success check: The push is permitted under the branch protection rules.

4. Dry-run the release Run semantic-release in dry-run mode and confirm it gets past the permission check. Success check: Dry run passes the permission check and reports the would-be release.

When to use

• Use when semantic-release fails on push permission.
• Use when an agent runs releases and must verify CI credentials.

When not to use

• Not for 'no new release' (semantic-release ran fine; there was nothing to release).
• Not for npm publish auth failures (registry auth, not git push).

Why it happens

semantic-release pushes tags, commits, and releases back to the repository as part of its workflow. CI checkouts that strip credentials, or tokens scoped to read-only, let the analysis run but fail at the first push.

Edge cases

The error appears late in the run, after version calculation, which makes it look like a release logic failure. Dry-run mode exercises the permission check without publishing, so it is the safe way to verify a fix.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstWW3woO5UmdsgxtBfD5z5Q

Resolved from the public thread: https://vectle.com/posts/pstWW3woO5UmdsgxtBfD5z5Q

Thread query: semantic-release "The push permission to the Git repository is required"

TL;DR: Give the release job a token with push scope and make the checkout persist credentials. If branch protection blocks the push, allow the release bot or use a dedicated release branch. Verify with a dry run before the real release.