Skip to main content
Effective: 2026-02-23

​
What changed

These rules apply to unlabelled semantic versions only (for example 1.2.3). Labelled versions (such as 1.2.3-beta or 0.0.0-my-feature) are not part of these checks. When you push a new unlabelled version, the platform validates two things in addition to existing format checks.

​
1. You cannot skip a required predecessor

The API must see the right previous unlabelled release before it accepts the new one:
  • Patch bump (1.2.3): the exact unlabelled 1.2.2 must already exist.
  • Minor bump (1.3.0): at least one unlabelled 1.2.x must exist.
  • Major bump (2.0.0 when coming from 1.x): at least one unlabelled 1.x.x must exist.
1.0.0 is unchanged: there is no prior semver to require. If the predecessor is missing, push fails with 403 and guidance like: Version X requires Y to exist. Push version Y, then try again.

​
2. You cannot insert an “intermediate” version behind a newer line

You also cannot push a version if a newer unlabelled version already exists in the segment that would make yours a backward insert:
  • 1.2.3: blocked if any unlabelled 1.2.4 or higher on the same 1.2.* line already exists. Pushing 1.3.0 is still allowed when only 1.3.x or 2.x.x exists—those are not on the 1.2.* patch line.
  • 1.3.0: blocked if any unlabelled 1.4.x or higher on the same major (1.*) already exists. 2.0.0 is still allowed when only 2.x.x exists.
  • 2.0.0: blocked if any unlabelled 3.x.x or higher already exists.
If that applies, push fails with 403 and a message that an existing version would make this an intermediate release, which is not allowed.

​
What this means for you

  • Plan patch → patch → minor → major (or the minimal chain your history needs) using unlabelled semver when you are ready to record real releases; use labelled snapshots while iterating.
  • If you are stuck because old versions were removed, you may still use deprecation and, when appropriate, delete a deprecated version so your remaining unlabelled history matches what you want to push next.