
Andrew Hanna

Andrew Hanna

sf package version create builds a new, installable version of an
unlocked or second-generation managed package in your Dev Hub from the metadata in
your project. Run it with --code-coverage and without
--skip-validation if you ever want to promote that version, or it stays a
beta that can never reach production.
The command takes the package contents in a directory, or a package alias or 0Ho ID,
and creates a package version in the Dev Hub, as the
Salesforce CLI reference
describes. Each version gets a unique subscriber package version ID that starts with
04t. When the command finishes inside its wait time, the CLI writes a new alias such
as [email protected] into the packageAliases section of
sfdx-project.json.
New versions start in beta. Beta versions install in scratch orgs and sandboxes but not in production, while promoted, released versions install in any org, as the Trailhead unlocked package unit shows.
--target-dev-hub.
sf package create and
mapped to its 0Ho ID in packageAliases.
versionName and
versionNumber. Using the NEXT keyword, as in
1.0.0.NEXT, lets the build number increment for you.
Still choosing a package type? The secrets of second-generation managed packages covers the trade-offs, and if you inherited an old one, unmanaged packages and how to move off them explains the exit.
sfdx-project.json, set
versionNumber to something like 1.2.0.NEXT.
sf package version create --package MyPkg --installation-key-bypass
--code-coverage --wait 30. You must pass either --installation-key or
--installation-key-bypass.
sf package version create report --package-create-request-id 08c... for
the status, any errors and the 04t ID.
sf package install --package [email protected] --target-org MyScratchOrg --wait
10.
sf package version promote --package [email protected]. Promotion cannot be
undone.
--code-coverage: runs the packaged Apex tests and stores coverage. You
need it to promote, and promotion requires at least 75 percent.
--skip-validation: skips dependency, ancestor and metadata checks for
speed. Versions built this way cannot be promoted, and the flag cannot be combined
with --code-coverage.
--async-validation: returns the version before validation finishes, so
testing can start sooner in CI.
--definition-file: a scratch-org-style file listing the features and
org settings your metadata depends on.
--version-number and --version-name: override
sfdx-project.json for a single run.
--branch and --tag: record the source branch and a tag on
the version.
--post-install-script and --uninstall-script: Apex classes
that run after install, upgrade or uninstall, for managed packages only.
Three causes account for most failed promotions:
--skip-validation. Rebuild without
it.
--code-coverage. Coverage is not calculated for org-dependent unlocked
packages.
Split it into two lanes. On feature branches, --skip-validation or
--async-validation keeps the loop short. On the release branch, build
with --code-coverage and full validation, so the artifact you test is the
one you can promote. Track your Dev Hub's daily allowance with
sf limits api display and its PackageVersionCreates entry,
because a build on every commit uses it up fast.
A beta install is only as useful as the data in the org it lands in. Serpent seeds sample or masked data as part of environment setup and release pipelines, so scratch orgs and refreshed sandboxes come back populated without a manual script, and deploying data is on every plan, including the free Essentials plan. See Serpent pricing for what each plan includes.
Once a version is promoted, the AppExchange release workflow takes it to subscriber upgrades. If your team still ships with change sets, start with the change sets to continuous delivery playbook first.
What is the difference between sf package create and sf package version create?
sf package create registers the package once, with its name and type.
sf package version create builds each installable version of it.
Can I install a beta package version in production?
No. Beta versions install in scratch orgs and sandboxes. Promote the version to released before installing it in production.
Do unlocked packages need 75 percent code coverage?
To promote, yes. You can build a beta without coverage, but it can never be released.
What if sf package version create times out?
The request keeps running in the Dev Hub. Check it with
sf package version create report and the 08c request ID.
More packaging and CI/CD how-tos live in our SF Guides.
Commitment free!