When you need to distribute Salesforce apps at scale, managed packages are your go-to solution. A Salesforce managed package is a protected, upgradeable bundle of app components that developers distribute on the AppExchange for customers to install in their orgs.
Salesforce handles each metadata type differently, and managed and unmanaged packages are no different. You can usually install packages straight into Salesforce orgs, but this isn’t always the best option when you have production access controls in place or need to install packages across many orgs or sandboxes.
With Gearset, you can easily deploy your packages through your pipeline or commit them to your version control system (VCS). This not only maintains collaboration within the team, but means you can easily automate your deployments — packages included. Before we show you how to do this with Gearset, here’s what you need to know about packages.
What are packages in Salesforce?
In Salesforce, packages act as a container for a bundle of metadata that you want to keep together. These packages can contain something as small as an individual custom object, or something as big as a set of related apps, including various app components. You’ll find Salesforce partners often use managed packages when they’re looking to distribute or sell their apps to Salesforce users through the AppExchange marketplace.
There are two package types:
Salesforce managed packages are tightly controlled by the package creator or owner. They’re mostly locked down so you can see the components that make up the package but you aren’t able to add to the package or see hidden package details. Salesforce allows some attributes of managed package components to be edited after installation but these customizations will live outside the package.
You can still make customizations by adding on top of the package, like adding a custom field to work with a managed object. The owner can also upgrade the package, and uses a license management application to control how many production orgs the package is installed in, using user-based licenses and org-based licenses.
Managed packages also come with a few important guardrails that make them safer for large-scale distribution. Every managed package requires a globally unique namespace prefix, which Salesforce automatically adds to component API names to prevent naming conflicts with other packages or a customer’s existing metadata.
Any package listed on the AppExchange must first pass Salesforce’s rigorous Security Review to ensure it meets strict standards for code quality, data protection, and platform security.
Salesforce also uses component manageability rules to control which parts of a managed package subscribers can edit. This separation ensures that subscriber-editable properties — like page layouts or help text — aren’t overwritten during upgrades, while developer-controlled components such as Apex code or permission sets (but not profile settings) are updated safely.
These safeguards allow developers to deliver improvements without breaking subscriber customizations.
Salesforce unmanaged packages are open source. They can be fully viewed and edited by whoever has installed the unmanaged package. The owner has no control over the contents once it’s in the hands of the installer and the package isn’t held under any license restrictions or able to be upgraded via push updates. These types of packages are great for in-house development or for sharing code with other Salesforce users and organizations.
Stop flying blind: How Truckstop brought clarity to a complex org
Types of managed packages
Managed packages can be broken down into two different types — first-generation and second-generation.
First-generation managed packages
First-generation packages are mostly locked down by the original developer. The package is owned by a packaging org — with only one package allowed in each. If you need multiple packages, then each one must have its own packaging org. These packages depend on an org-driven model, but they can also be committed to your version control.
Second-generation packages (2GP)
Second-generation packages rely entirely on source-driven development. Salesforce created 2GP because they wanted to remove the dependency on orgs for packaging and introduce more automation via the command line through Salesforce DX.
This type of package is only available for those using Salesforce DX as developers use scratch orgs as a runtime environment to build and test the customizations. These are then merged into the VCS before you build your package. A 2GP is owned by a Dev Hub org and acts as a holding space for one or more packages.
First-generation managed packages use org-based development with the Metadata API, while second-generation managed packages use source-driven development with Salesforce CLI. Salesforce recommends 2GP for new applications. But many existing AppExchange packages were built with 1GP, and understanding 1GP deployment methods remains valuable for teams working with these established packages or in the process of migration. Because the majority of Salesforce professionals use the Metadata API, rather than Salesforce CLI, we’re going to focus on deploying first-generation managed packages in this blog post.
Can you install a managed package in a sandbox?
Yes you can — and you absolutely should! Installing a Salesforce managed package in a sandbox allows you to test business logic like triggers and flows. Even though you can’t open the package and add to it, you can build modifications that work alongside the contents of the package — like building a custom field for a managed object, specifically for testing purposes.
Installing a managed package in a sandbox won’t affect the licenses — they’re only used when you install the package into a production environment.
Should you use source control for managed packages?
It’s not always necessary to manage your packages in source control, but it is good practice for maintaining consistency and collaboration across all your environments. The AppExchange typically lists the latest available version of the package, which means source control can come in really handy if you’re running an earlier version. For instance, if you’re spinning up a new dev org and the original package has been updated to v2 in the AppExchange. You might not want to commit to v2 until you’ve finished testing — so having your v1 package in your VCS will allow you to carry on until you’re ready to upgrade.
If you aren’t using source control to track your managed packages, then you’ll have to manually install them in each org — which can be a real pain when you have a few to install at a time. Simply using version control to deploy the installed packages to your other orgs means you can keep track, and also automate using continuous integration.
For larger teams or companies that tightly control permissions in their production org, a user needs the Download AppExchange Packages permission to install a managed package. When using a DevOps platform like Gearset, you can automate managed package installations by deploying the InstalledPackage metadata type — but only for first-generation managed packages, and only when you deploy it on its own with no other metadata in the manifest. Second-generation and unlocked packages require Salesforce CLI commands instead.
Managing managed packages at scale also means thinking about backup and recovery. When planning backups that involve managed packages, focus on the data and metadata stored in managed package objects and any customizations your team has built on top of the package. You can always reinstall the managed package itself from the vendor. Protecting your data, your added fields, your automations, and your custom reports ensures full recoverability even though the publisher owns and maintains the package components themselves.
How do you upgrade a managed package?
Package owners can release a patch or upgrade to the package once it’s been installed in your org. There are a few different ways that you can upgrade your installed package:
Most of the time, you find the upgrade in the AppExchange and choose to install it. While this feels like a more manual way to upgrade than other methods, you have control over when you upgrade.
You need to opt-in to push upgrades. By giving access to the package owner, the upgrade goes straight into the org where the package is installed. This is easy, but if you’re using source control, you have to remember to refresh your branch to bring it in.
Packages can also be upgraded when new Salesforce versions are released. These releases happen three times a year.
How to deploy managed packages in Gearset
NOTE: Gearset’s comparisons have had an upgrade! We’re updating all our blog posts with the new UI images — but in the meantime, you can learn more about what’s changed.
Gearset makes managed package deployments easy, because we handle the complexity so you can treat them like any other metadata type. There’s only a few steps you need to take from org comparison to successful deployment — you can sign up for a free trial of Gearset and follow along.
Select your source and target orgs
From the Compare and deploy page, select your source and target orgs – in this case, your sandbox as your source and your production org as your target.
Select a comparison filter
Select the relevant comparison filter or build your own before pressing Compare now.
Choose the installed package you’d like to deploy
On the comparison screen, you’ll see a side-by-side view of all the changes between your orgs. They’re separated into New, Changed or Deleted tabs. Choose the installed package(s) you want to deploy and click Next to finalize the deployment.
Run the problem analyzers
Gearset’s problem analyzers will pick up any missing dependencies or flag any other issues that could cause the deployment to fail, as well as suggesting a fix. Gearset will also run static code analysis on your deployment package, to highlight any violations. Once you’re happy, click through to the Pre-deployment summary.
Pre-deployment summary
Give your deployment a friendly name and include any notes your team will find useful. You can then choose to Validate deployment, Deploy now, or schedule the package to deploy at another time.
Finish your deployment
Once the deployment has run, you’ll be given a summary of the deployment and can download a full PDF report at any time from the Deployment history page.
Easily migrate your customizations with Gearset
Gearset won’t display customizations if the package versions don’t match on both sides of the comparison. So you’ll need to install or update your package in the target org first, before you deploy any customizations. This prevents deployments that use features from the package that aren’t available on the target, and saves you from manually removing parts of the package during an upgrade.
Effortlessly deploy managed packages
With everything tracked in source control you have one source of truth and can easily deploy your packages across your pipeline without needing to go and install each one in each Salesforce org. And, Gearset looks after your packages just like any other metadata. They get the same first class treatment from our clever comparison engine and are checked by our 70+ problem analyzers.
See for yourself how easy deploying managed packages can be with your free 30-day trial of Gearset! No credit card number needed, just connect up your orgs and you’re ready to go. It couldn’t be easier to get started.
FAQ
How do I create a managed package in Salesforce?
You’ll need to set up a dedicated packaging environment, register a namespace, add your app components, and create a version you can distribute to other orgs.
Salesforce now directs developers to 2GP for new development. Here’s a simple overview of the process:
- Turn on Dev Hub and choose a namespace: Dev Hub acts as the home base for your package. After enabling it, you’ll pick a namespace — a short, unique prefix that identifies all components in your package.
- Store your app’s files in version control (like Git): 2GP works from source code stored in Git rather than building directly in Salesforce. This lets you track changes and collaborate with your team.
- Build and test your app in scratch orgs: Scratch orgs are temporary Salesforce environments you can quickly spin up to build and test your work without touching your production org.
- Create your package version using the Salesforce CLI: Once your app is ready, you’ll run a command through the Salesforce CLI to create a new package version. This becomes the installable version of your managed package.
- Test the package in sandbox environments: Before you release it, install your package in a sandbox to verify it works, upgrades smoothly, and integrates with other customizations.
- Use permission sets instead of profiles: Salesforce recommends using permission sets for access control because they update cleanly when you release new package versions.
- Prepare for AppExchange (optional): If you want to publish your package on the AppExchange, you’ll need to pass Salesforce’s Security Review and provide documentation for your customers.
- Release updates when ready: Once your package is live, create new versions and push upgrades to customers when you make improvements or fixes.
