> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/adopting-automated-versioning.md).

# Adopting automated versioning

{% hint style="warning" %}
**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.
{% endhint %}

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:

```diff
 {
   "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 │
└──────────────┴───────────┴──────────────┘
```

{% hint style="warning" %}
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.
{% endhint %}

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/adopting-automated-versioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.