The AppExchange Release Workflow: From Package Version to Subscriber Upgrade

Short answer: an AppExchange release runs in five stages: create a beta package version, validate it, promote it to released, link it to your listing, then move subscribers onto it. Every second-generation managed package version is born a beta, promotion is a one-way door, and only security-reviewed packages can be pushed into subscriber orgs.

What is the AppExchange release workflow, end to end?

1. Create the version. Every 2GP version is created as a beta. A beta is installable for testing and can never be listed.
2. Validate it. Install into a clean scratch org and into a sandbox shaped like a real subscriber, then run the full test suite.
3. Promote it. sf package version promote turns the beta into a released version.
4. Update the listing. In the Partner Console, under Publishing and Listings, use Link Your Solution to attach the released version, then publish.
5. Move subscribers. Self-serve install, a recommended version, or a push upgrade.

Most ISV teams already do all five somewhere. What they usually lack is the ordering, the gate between each stage, and a reliable record of which subscriber org sits on which version.

How do you make a package version upgradable?

Upgradability is decided by ancestry, not by the version number you typed. Each new 2GP version declares an ancestor in sfdx-project.json, and Salesforce recommends ancestorVersion: HIGHEST so it tracks your highest promoted version automatically. Existing customers cannot upgrade to a package version created without a specified ancestor, so one build with a missing ancestor produces a version nobody can reach.

• Keep ancestry linear unless you have a deliberate reason to branch.
• Treat the skip-ancestor-check flag as an incident, not a workflow.
• Use version numbers the way subscribers read them: major for sweeping change, minor for new features, patch for small corrections.

What has to be true before you promote?

Promotion is the gate that matters most, because it cannot be undone.

• A beta version must pass a 75% code coverage requirement before it can be promoted.
• You can promote and release a given package version number only once, and you cannot revert it to beta.
• The ancestor has to be correct, because the released version is the step your subscribers upgrade through.

Run promotion from your pipeline behind one explicit human approval, never from whichever laptop is authenticated to the Dev Hub. Grant the promote permission through a permission set, not to everyone with CLI access.

When does security review actually happen?

For a first listing, security review sits between validation and publication and it is the long pole in the calendar. For updates the picture is different. You do not need a full security review for every patch or upgrade, and what governs publication is the listing status. If the listing shows Ready to List, you can publish the updated listing without submitting the new version for review. If it shows Security Review Required, you cannot publish until that version passes.

Salesforce also runs periodic re-reviews, and a version with significant change is likelier to trigger one. So budget review time into releases that change architecture, authentication or outbound calls, not into routine bug fixes. Check the current rules in the ISVforce guide to updating a listing before planning a quarter around them.

How do you upgrade subscribers without stranding anyone?

Three levers, from least to most invasive:

1. Self-serve install. Subscribers install from the listing or an install URL when they are ready. Slowest convergence, lowest risk.
2. Recommended version. With 2GP you can mark a version as recommended, and subscribers then see an Upgrade to Recommended Version option on their Installed Packages page. A nudge, not a decision taken for them.
3. Push upgrade. You upgrade subscriber orgs yourself, choosing which orgs, which version and when. Only packages that passed the AppExchange security review are eligible, Salesforce Partner Support enables the capability, and 2GP push upgrades run from the CLI or SOAP API, not the user interface.

A staged rollout that holds up: your own orgs first, then partner and sandbox orgs, then a small cohort of consenting customers, then everyone else in scheduled off-peak batches. Leave a full business day between cohorts, not an hour.

What actually goes wrong

• There is no downgrade. A subscriber who upgrades cannot roll back, so your rollback plan is a forward patch version. Keep the release branch ready to cut one the same day.
• The listing drifts from the package. A promoted version never linked to the listing means new prospects install last quarter's build while your docs describe this quarter's.
• Ancestry breaks quietly. Nothing fails at build time. It fails months later, in a customer org, as an upgrade that will not start.
• Subscriber sandboxes get skipped. Tell customers in your release notes to upgrade a Full or Partial sandbox first. It is the only rehearsal either side gets.

What should you automate first?

1. Version creation with code coverage computed on every merge to the release branch.
2. Automatic install and smoke test of that beta in a clean scratch org.
3. Promotion behind exactly one human approval, with the ancestor checked first.
4. A version register: which subscriber org runs which version, updated after every push.

Teams postpone the fourth item and regret it, because support quality depends on it more than anything else here. Serpent covers 1GP, 2GP and managed-package workflows, cross-package dependency resolution and version management across subscriber orgs on every plan, including the free one. More packaging playbooks live in our SF Guides library.

FAQ

Can I unpromote a package version?

No. You can promote a version number only once and it cannot be undone, so treat promotion as a release decision, not a build step.

Do I need a new security review for every release?

No. A full review is not required for every patch or upgrade. Publication depends on your listing status, and Salesforce may still ask for a periodic re-review when a version changes significantly.

Why can my customer not upgrade to my newest version?

Usually ancestry. Existing customers cannot upgrade to a version that was created without a specified ancestor, so check the ancestor before you check anything else.

What is the difference between a recommended version and a push upgrade?

A recommended version shows subscribers an Upgrade to Recommended Version option and leaves the timing to them. A push upgrade moves their org for them, on your schedule.

Do beta versions count as releases?

No. Every 2GP version starts as a beta, which is installable for testing only. It becomes a release the moment it is promoted.