Andrew Hanna

Andrew Hanna

sf package version create: Salesforce Package Versions Guide

sf package version create: Salesforce Package Versions Guide

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.

What does sf package version create do?

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.

What do you need before you run it?

  • A Dev Hub org, set as your default or passed with --target-dev-hub.
  • A package, created once with sf package create and mapped to its 0Ho ID in packageAliases.
  • A package directory entry with 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.

How do you create a package version step by step?

  1. Set the version. In sfdx-project.json, set versionNumber to something like 1.2.0.NEXT.
  2. Create the version. Run sf package version create --package MyPkg --installation-key-bypass --code-coverage --wait 30. You must pass either --installation-key or --installation-key-bypass.
  3. Check the request. If the wait runs out, run sf package version create report --package-create-request-id 08c... for the status, any errors and the 04t ID.
  4. Test the beta. Install it in a scratch org or sandbox with sf package install --package [email protected] --target-org MyScratchOrg --wait 10.
  5. Promote. When it passes, run sf package version promote --package [email protected]. Promotion cannot be undone.

Which sf package version create flags matter most?

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

Why can't I promote my package version?

Three causes account for most failed promotions:

  • It was built with --skip-validation. Rebuild without it.
  • Coverage is missing or under 75 percent. Add tests and rebuild with --code-coverage. Coverage is not calculated for org-dependent unlocked packages.
  • The number is already released. Only one version can be promoted per major.minor.patch, so bump the number and build again.

How do you run sf package version create in CI?

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.

FAQ

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.

Related Articles

Curious about faster shipping before you dive in? Let's talk

Commitment free!