Adopting automated versioning

This feature is in limited preview — it is available to selected customers only, and behaviour and commands may change based on feedback. Reach out to the flxbl team if you would like early access.

Automated versioning is opt-in per project, and within an enabled project, opt-in per package. Nothing changes for any package until its version is set to the sentinel 0.0.0.NEXT.

Step 1: Enable the feature on the project

Enable Server-Managed Versioning in your project's settings — either when creating the project, or later from the project's build workflow settings:

• New projects: toggle Server-Managed Versioning in the create project dialog. The onboarding preflight will then take care of seeding your packages (see below).
• Existing projects: open the project's settings for the build workflow and enable Server-Managed Versioning.

The setting unlocks the version pipeline for builds of this project. By itself it changes nothing — every package still carries its explicit version and behaves classically until you opt it in.

Step 2: Opt packages in

There are three ways to onboard packages, and you can mix them freely.

New projects: seeded during onboarding

When a project is created with the setting enabled, the onboarding preflight resolves the current version of every package (from your existing git tags, the DevHub for unlocked packages, or the version in sfdx-project.json), records them on the server, and includes the stripped sfdx-project.json in the configuration pull request it raises:

// Before — in your repository
"versionNumber": "2.4.0.NEXT"

// After — in the preflight PR
"versionNumber": "0.0.0.NEXT"

Review and merge the PR as usual (squash merging is fine), and every build from then on computes versions automatically.

Existing projects: adopt lazily, one package at a time

The recommended path for existing projects is gradual adoption through your normal pull request workflow. Pick a package, set its version to 0.0.0.NEXT in a PR, and merge:

 {
   "path": "src/sales",
   "package": "sales",
-  "versionNumber": "2.4.1.NEXT",
+  "versionNumber": "0.0.0.NEXT",
   "type": "source"
 }

The next build resolves the package's base version from its existing release tags or the versions already recorded on the server, and the first publish records it going forward. Squash merging this change is fine. All other packages remain user-managed until you opt them in the same way.

Bulk onboarding: sfp project version seed

To onboard every package in one shot, run the seed command from the branch you want to onboard (typically your trunk):

sfp project version seed --repository myorg/myrepo

The command:

1. Resolves the current published version of every package — git tags first, then the DevHub (unlocked packages), then sfdx-project.json
2. Records each version on the server
3. Strips all version numbers to 0.0.0.NEXT
4. Commits, tags and pushes the change to the branch

Seeded Packages:
┌──────────────┬───────────┬──────────────┐
│ Package      │ Version   │ Source       │
├──────────────┼───────────┼──────────────┤
│ sales        │ 2.4.1.45  │ git-tag      │
│ sales-ui     │ 1.2.0.45  │ git-tag      │
│ core-crm     │ 3.1.0.12  │ devhub       │
│ utils        │ 1.0.0.0   │ sfdx-project │
└──────────────┴───────────┴──────────────┘

The seed command pushes a commit and tags directly to the branch, so it requires push access (use branch-protection bypass or run it as your CI bot). Do not run it through a squash-merged pull request — the tags it creates must point at commits that remain on the branch. If direct pushes are not an option, use the lazy adoption path instead, which has no such requirement.

Checking the state of your packages

sfp project version list shows, for each package, the version in sfdx-project.json next to what the server has recorded:

sfp project version list --repository myorg/myrepo

Package Versions (branch: main)
┌──────────────┬────────┬───────────────────┬─────────────────┬─────────────┬─────────┐
│ Package      │ Type   │ sfdx-project.json │ Server (latest) │ Last Intent │ Updated │
├──────────────┼────────┼───────────────────┼─────────────────┼─────────────┼─────────┤
│ sales        │ source │ 0.0.0.NEXT        │ 2.5.0.46        │ minor       │ 2d ago  │
│ sales-ui     │ source │ 0.0.0.NEXT        │ 1.2.1.46        │ patch       │ 2d ago  │
│ utils        │ source │ 1.0.0.NEXT        │ -               │ -           │ -       │
└──────────────┴────────┴───────────────────┴─────────────────┴─────────────┴─────────┘

2 seeded, 1 unseeded (3 total)

Overriding a version temporarily

Need to force a specific version for one release? Set it explicitly — an explicit version is always honoured verbatim:

"versionNumber": "3.0.0.NEXT"

The next build produces 3.0.0.<build> for that package, marked as an override in the build output. Set it back to 0.0.0.NEXT to return it to server management; the pipeline continues from the highest version it has seen.

Opting out: sfp project version restore

The reverse of seeding. The restore command writes the last published version of each managed package back into sfdx-project.json and commits the change:

# Return everything to manual versioning and disable the feature
sfp project version restore --repository myorg/myrepo

# Return only selected packages — the feature stays enabled for the rest
sfp project version restore --repository myorg/myrepo -p sales -p sales-ui

Restored Packages:
┌──────────────┬─────────────┬────────┐
│ Package      │ Version     │ Source │
├──────────────┼─────────────┼────────┤
│ sales        │ 2.5.0.NEXT  │ server │
│ sales-ui     │ 1.2.1.NEXT  │ server │
└──────────────┴─────────────┴────────┘

A full restore (no -p flags) also disables the project setting, completing the opt-out; pass --keep-enabled to restore the versions but leave the feature on. Server records are kept either way, so re-adopting later picks up exactly where you left off.