Promote
Promote is the Salesforce action of moving something to a more advanced, public-ready state.
Definition
Promote is the Salesforce action of moving something to a more advanced, public-ready state. In second-generation packaging, it changes a package version from beta to released so the version can be installed in production and listed on AppExchange. In the older Salesforce Ideas feature, Promote is a vote that adds points to an idea to raise its ranking.
The two meanings sit far apart, but they share one idea: promoting takes something tentative and advances it to a more definitive status. The packaging sense is the one most teams use today, and it is run from the Salesforce CLI with a single command.
Two meanings of Promote, and which one you need
The packaging meaning: beta to released
When you create a second-generation managed package version, Salesforce marks it as beta. A beta version is meant for testing only. It cannot be installed in a production org, and it cannot be upgraded later, so you should keep it out of any sandbox that sits in your release pipeline (UAT or staging, for example). Promote is the step that turns that beta into a released version. A released version is the artifact you actually ship. It can be installed in production orgs, and only released versions can be listed on AppExchange. You run the action from the Salesforce CLI with the command sf package version promote. The command takes the package version you want, marks it released, and that is it. Package versions are immutable, so the bytes inside the version do not change when you promote. What changes is the status flag and what the platform will let customers do with it. Because of that, promotion is best understood as a release gate rather than a build step. You are not making a new version, you are declaring an existing one ready for the world.
The Ideas meaning: a vote worth ten points
In the Salesforce Ideas feature, Promote is how a community member votes for an idea they like. Clicking Promote adds 10 points to that idea's score, which raises its overall popularity ranking and makes it more visible to others browsing the zone. There are two rules worth knowing. You cannot promote the same idea more than once, so each person gets a single promote vote per idea. You also cannot promote an idea that you have already demoted, since promote and demote are mutually exclusive for a given user and idea. One more behavior catches people out: when you post a brand new idea, Salesforce automatically adds your own promote vote, so a fresh idea starts with 10 points instead of zero. This voting model is the original sense of the word inside the product. It predates the packaging command by years and shows up mostly in older Ideas communities and Experience Cloud sites that still run the classic Ideas feature.
Why promotion is treated as irreversible
Promoting a package version is meant to be a one-way door. Once a version is released, customers can install it, and Salesforce treats that released artifact as a stable contract. You should not plan to flip a released version back to beta as part of normal work. There is a documented support path for reverting a 2GP version to beta in narrow situations, but it is an exception handled through Salesforce, not a casual undo. Treat it that way in your process. Before you promote, make sure the version is genuinely ready: tests pass, the install works in a fresh scratch org or sandbox, and any package dependencies are themselves released. If you promote a version that depends on a beta dependency, customers cannot install it cleanly in production, so the whole point of promoting is lost. The safest mental model is that promotion publishes a promise. After you promote, the only forward path is to build and release a newer version with fixes. That is why mature ISV teams put promotion behind explicit sign-off, often in a CI pipeline, rather than letting any engineer run it ad hoc.
Where Promote sits in the release pipeline
A typical second-generation packaging flow has four stages, and Promote is the third. First you create a package version from your source, which produces a beta. Second you install that beta in a test org, run automated and manual checks, and confirm the upgrade path behaves. Third you promote the validated version to released. Fourth you distribute it, either by sharing the install URL or by submitting the package to AppExchange for listing. Promotion is the hinge between internal validation and external distribution. Everything before it is private and reversible. Everything after it is public and effectively permanent. Because the command itself is fast and quiet, the discipline has to live in the process around it. Teams commonly tie promotion to a passing build, a version tag in source control, and a release note. Some gate it behind a manual approval in their CI tool so a human signs off before the beta becomes a release. The command does not enforce any of that, which is exactly why your pipeline should.
AppExchange listing and the security review
Promoting a version to released is necessary for AppExchange, but it is not the whole story. Only released versions can be listed on AppExchange, so promotion is a prerequisite for any public listing. Listing a managed offering to the general public also runs through the Salesforce security review, a separate process that examines your package for vulnerabilities before it can be sold or distributed broadly. Promotion and security review are different gates that happen to line up in the same part of the timeline. You promote so the artifact is installable and listable. You pass security review so Salesforce will let it go live on the marketplace. Keep the two ideas distinct when you plan a launch, because confusing them leads to surprises late in a release. A version can be promoted and installable by direct URL while a listing is still working through review. Planning the promotion date and the review submission as separate milestones keeps an ISV release predictable instead of bunched up at the end.
Running the command and reading the result
The action lives in the Salesforce CLI under the package commands. You authenticate to the Dev Hub that owns the package, then run sf package version promote and pass the version you want to release. The CLI asks you to confirm, since the change is meant to be deliberate, and you can skip that prompt in automation when you are confident. On success the CLI reports that the version is now released. From that moment the version's status is released, it accepts production installs, and it becomes eligible for AppExchange listing. Nothing about the package contents changes, because the version was immutable the moment it was created. If you try to promote a version that is not ready, for example one with an unreleased dependency, the command surfaces an error rather than releasing something broken. Read that output carefully. The most common mistakes are promoting the wrong version id, or promoting before a dependency package has itself been promoted. Confirm the exact version you intend to release before you run the command, since there is no clean rollback once it succeeds.
How to promote a 2GP package version to released
Promote here means moving a second-generation managed package version from beta to released using the Salesforce CLI. Do this only when the version is fully tested and every dependency is itself released.
- Authenticate to the Dev Hub
Log in to the Dev Hub org that owns the package, since promotion is authorized against that hub. Confirm you are targeting the right hub before continuing.
- Identify the exact version
Find the package version id or the package alias and version number you intend to release. Promoting the wrong version is the most common and least recoverable mistake.
- Run the promote command
Run sf package version promote and pass the version. The CLI prompts for confirmation because the change is effectively permanent. Approve it only when you are sure.
- Verify the released status
Confirm the CLI reports the version as released. Optionally install it in a fresh test org to prove it is now production-installable before you distribute the link.
The package version alias or subscriber package version id you want to promote to released.
Skips the confirmation prompt, which is useful inside a CI pipeline once a human approval gate has already passed.
The Dev Hub username or alias that owns the package, when it is not your default hub.
- Promotion is treated as one-way; reverting a released version to beta is a narrow Salesforce support exception, not a normal undo.
- A version with a beta dependency cannot be installed cleanly in production, so promote dependencies first.
- Promoting does not list the package on AppExchange; that still requires a separate security review for public distribution.
- Beta versions cannot be upgraded, so never install a beta in a release-pipeline sandbox like UAT or staging.
Prefer this walkthrough as its own page? How to Promote in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- Release a Second-Generation Managed PackageSalesforce
- Get Ready to Promote and Release a 2GP Package VersionSalesforce
- Vote on IdeasSalesforce
Straight from the source - Salesforce's reference material on Promote.
Hands-on resources to go deeper on Promote.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. In the Salesforce packaging context, what does the Promote action do to a package version?
Q2. What is a defining characteristic of promoting a package version to Released?
Q3. In Salesforce Ideas, what does the Promote action accomplish?
Discussion
Loading discussion…