It’s been nearly six years since we first released second-generation managed packaging (2GP), which allows our AppExchange partners to build and distribute solutions using a CLI-based, source-driven, and automation-friendly development model.
Since then, we’ve received a ton of great feedback from our developer community, and we continue to innovate in multiple areas around developer experience, performance, metadata type parity with first-generation managed packaging (1GP), and so on. Whenever we meet with ISV developers, we consistently hear about the need for Salesforce to help them and their customers move over to the world of 2GP.
Today, I have some exciting news to share with you all! We are addressing the #1 ask from our ISV developers by introducing a new feature: Package Migrations, now generally available with Summer ’25! In a nutshell, Package Migrations fully automates the process of converting 1GP packages to 2GP and seamlessly migrates customers with installed packages across to 2GP. If you’re an ISV partner that creates managed packages, this blog post is for you!
Before we dive into the details of Package Migrations, let’s take a look at some benefits of using 2GP for package development.
Benefits of using 2GP for package development
At the heart of 2GP is a source-driven development model, where a source code repository such as Git represents the source of truth for your package. This is fundamentally different from the world of 1GP, where you use a packaging org to maintain all the metadata that you want to package and distribute to your customers.
This source-driven development model, powered by the Salesforce CLI, can dramatically boost your team’s productivity and collaboration. Developers can use the Dev Hub to quickly spin up scratch orgs, jointly build a feature, and commit it to source control. When you are ready to distribute a new version of your 2GP, simply pull the relevant branch to a local machine and use the CLI to create your new package version.
Importantly, this CLI-based approach also means that you can easily integrate your packaging process fully into CI/CD, making it easy to fully automate your workflow. You can, for instance, automatically run Salesforce Code Analyzer against a codebase and, provided no problems are found, create a new package version.
In the world of 1GP, you were stuck using a different namespace for each of your packages. In 2GP, your packages can all share the same namespace, allowing you to leverage a truly modular approach to package development to keep your packages well-organized. It’s also possible to explicitly declare dependencies among packages, ensuring that everything works together seamlessly.
With 2GP, you also get flexible versioning, which allows you to abandon package versions that you no longer want to build upon. Instead, you can specify a package version ancestor and effectively create a new branch where you want to continue your development.
Finally, supporting customers has never been easier with 2GP. In the world of 1GP, patches can only be created from a patch org. With 2GP’s source-driven development model, you can simply create a patch package version directly from the CLI and, provided that the patch abides by requirements around minor changes and package ancestry, it gets created and ready to be installed into your customer’s org.
All said, 2GP can add a ton of value to your development process. Now, let’s find out how Package Migrations can help you get to the world of 2GP.
Introducing Package Migrations
Package Migrations extends 2GP functionality with additional CLI commands and additional capabilities to help ISV developers fully transition to the world of 2GP. Read on to start moving your package to 2GP!
There are two elements to Package Migrations: package conversion and package migration. The diagram below shows how a 1GP package version can be converted into a corresponding 2GP package version using the sf package convert command. This converted package is then installed into Subscriber A, who already has an installed 1GP package version, triggering an automated migration of subscriber A’s installed 1GP package version to the converted 2GP package version.
Package conversion is initiated through the new sf package convert command. It takes the latest version of your existing 1GP package (Acme v1.0 in this example) and uses some magic behind the scenes to convert it into a corresponding 2GP package version (Acme v1.0.0.1 using 2GP version numbering).
Once you have a converted 2GP package version, you can migrate customers over to 2GP. If you have a subscriber with Acme v1.0 installed, you would start the process by treating it as a normal package upgrade: via the CLI with sf package install (see docs), URL installation, or push upgrades with the new --migrate-to-2gp flag.
As you’re trying to migrate your converted 2GP package v1.0.0.1, which matches the major.minor version of the 1GP package installed in subscriber A, we run new logic that starts the package migration process. Without changing any metadata on the customer’s org — and without requiring user intervention if you’re using push upgrades — we simply change the package references to point to the new 2GP package.
Once a customer is migrated to 2GP, any patches or upgrades to this customer’s package will need to use 2GP.
Testing conversion of a first-generation managed package
Alright, let’s get started! First of all, make sure that you have installed the Salesforce CLI.
If you installed it previously, ensure that you’re using the latest version:
sf update
Now make sure that you are running within the context of a SalesforceDX project. You can create a new project using:
sf project generate --name <Your project name>
Link the namespace of your managed 1GP by logging in to your DevHub and follow the steps.
That’s it for setup! Now you can go ahead and try to convert the latest version of your package. Note that the latest version of your package must be Managed – Released in order for you to be able to convert it.
sf package convert --installation-key mdpTest --package 033xxx --wait 20
Let’s run through the parameters. We are using the installation key mdpTest. It will be required whenever you’re trying to install this package version in the future. Alternatively, you can use --installation-key-bypass to bypass the installation key. You will need to enter your full 1GP package ID starting with 033 after --package. The conversion process might take a little while, and therefore, we added the option --wait to wait for 20 minutes. If you intend to use this converted package to migrate customers, you need to run Apex unit tests by using the --code-coverage flag.
As the conversion process executes, you will get an update on its status. Assuming that everything went well, you will get a success message with the ID and installation URL for the newly converted 2GP package version.
Converting Package... ... Successfully created the package version [08cxxx00000KzFSAA0]. Subscriber Package Version Id: 04txxx00000u1cqAAA
Package Installation URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04txxx00000u1cqAAA
As an alternative, you can use the "sf package install" command.
Congratulations, your package is now converted to 2GP, with a new package version ID! Note that your newly converted 2GP package version is a Beta version. This is fine for testing purposes. However, if you intend to use this version to migrate customers to 2GP, you need to promote your package version using the sf package version promote command.
Now that your package is converted, let’s test out migrating a subscriber org.
Testing migration of an installed first-generation managed package
Let’s test out migrating a new scratch org. You can set up a new scratch org like this:
sf org create scratch -f project-scratch-def.json -a MyScratchOrg
In the code above, -f points to your scratch org definition file. You should make sure that your scratch org definition file includes any Salesforce features that your package might depend on. Finally, we’re using MyScratchOrg as the alias for this org.
With the scratch org set up, go ahead and install the 1GP package version that you converted earlier by using the installation URL that you get from your 1GP packaging org.
Once you’ve done that, you can see the 1GP package in the Installed Packages section of the Setup menu:
Now that you installed your 1GP in the scratch org, it is ready for migration.
You can test the migration process by using the installation URL that you received at the end of the package conversion process:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04txxx00000u1cqAAA
You will now go through the same set of screens as above, but this time for your converted 2GP package.
Currently, the user interface shows the “installation” as having been completed. In reality, what we did was a package migration that was completed successfully.
Note that in this example, we’ve used the second Beta build for version 1.16, which corresponds to the same major.minor version as the 1GP package version installed earlier. As the converted 2GP is created as a Beta version and we didn’t promote it yet, it shows up as such.
Once again, you can confirm the updated package version in the Installed Packages section of the Setup menu, which also shows, in this example, the version number to be 1.16 (Beta 1).
Once you have migrated the package in your scratch org, we recommend that you test it to ensure that it works as expected.
You should also take the opportunity to verify whether apps, such as the License Management app or the Feature Management app, are showing the correct information for your migrated package.
Moving package development to 2GP
With this release, you can convert your packages and start migrating customers over to 2GP. During this time, you’ll continue using your 1GP packaging org to create new package versions, which you can then convert to 2GP. This is great to get you started, but ultimately you want to fully move package development over to 2GP and fully reap the benefits of a modern, source-driven development model.
I’m happy to say this is coming very soon as a fast-follow to package conversion and migration. That said, we strongly recommend that you get started with converting your packages and starting to migrate your customers. Some of you might have, for instance, packages with multiple layers of dependencies. This is the perfect time to create a strategy around which packages you need to first prioritize for conversion and migration (hint: we recommend starting with the leaf packages that no other packages depend on and make your way to the base packages), ahead of fully moving development over to 2GP.
Conclusion
We are very excited about Package Migrations. This release is the start of the process to help you move your packages and customers to 2GP. We encourage you to get started as soon as possible, paving the way for your company to be fully on 2GP..
In the meantime, please do let us know how you’re getting on. We’re very much looking forward to getting your feedback!
Further Resources
- Help & Discussion group in the Partner Community
- Package Migrations Summer ‘25 Release Notes
- Package Migrations documentation
- Salesforce CLI Reference for new package convert command documentation
- Second-Generation Managed Packaging documentation
About the author
John Belo is Director, Product Management for Developer Experience Products, leading the Application Lifecycle Management product space within the team. He oversees products such as Salesforce Code Analyzer v5, DX Inspector, DevOps Center, DevOps Testing, AppExchange App Analytics, and Package Migrations (helping ISV partners move from 1st generation managed packaging to 2nd generation). He’s been with Salesforce for ten years and spent the majority of this time within the AppExchange team. He started by leading a team of ISV Technical Evangelists in EMEA, and is now part of the Developer Experience Product Management team, helping developers to deliver quality solutions faster than ever.
The post Managed 2GP with Package Migrations Is Now Generally Available appeared first on Salesforce Developers Blog.
