semantic-release "The local branch is behind the remote one" in CI

By Daniel Zoghalchali·Latchkey

Before releasing, semantic-release checks that the checked-out branch is up to date with the remote. If the local ref is behind (another push landed, or CI checked out a stale commit), it refuses to release to avoid tagging an outdated state.

What this error means

The run logs "The local branch main is behind the remote one, therefore a new version won't be published" and exits without a release.

[semantic-release] The local branch main is behind the remote one, therefore a new version
won't be published.

Common causes

A concurrent push moved the remote ahead

Another commit landed on the branch after CI checked out, so the runner ref is behind the remote head.

A shallow or detached checkout without the branch tip

The checkout landed on a commit that is not the current remote head, so semantic-release sees the local branch as behind.

How to fix it

Check out the full history on the branch

1. Set fetch-depth: 0 so the full history and branch ref are present.
2. Ensure the job runs on push to the release branch, not on a stale ref.
3. Re-run; if a real concurrent push occurred, the next run releases.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Serialize releases with concurrency

Prevent overlapping release runs so one job does not fall behind another.

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

How to prevent it

• Always use fetch-depth: 0 for semantic-release checkouts.
• Add a concurrency group so releases do not race.
• Trigger releases on push to the branch, not on outdated refs.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation