Creating an Unlocked Package
Creating an Unlocked Package
- Open the Packages tab and click on New to create a new Package record.
- Select Salesforce Package as record type.

- Fill in the required fields:
- Package Name: Give your package a name. Please note that blank spaces are not allowed.
- Package type: Select Unlocked.
- Source Org Credential: The org credential from where the metadata of the package is going to be retrieved.
- Package Repository: This is the repository where the package will be stored:
- Packages can be saved in a single repository or independently in different repositories.
- The metadata of each package is saved in a folder labeled with the name of the package.
- Target Dev Hub Org: The org credential of the dev hub org which will be used to create and store the package and its versions.
- Source Api Version: The API version with which the source of your package is compatible. This field is important if you are using a metadata type that has changed in a recent Salesforce release.
- Other relevant fields in the Salesforce Package record:
- Package Id: Related package identifier. It is used as a package Id for package version creation and also used in the sfdx-project.json file as a package alias.
- Description: Add a description for the package.
- Package Namespace: This field is not required for unlocked packages.
- No Namespace: Enables the creation of a package with no namespace and is available only for unlocked packages.
- Sfdc Login Url: The login URL that the force:auth commands use. If this is not specified, the default will be login.salesforce.com. Override the default value if you want users to authorize to a specific Salesforce instance.
- Click on Save.
Loading Metadata into an Unlocked Package
Once you have created the unlocked package, you can start loading metadata:
- Open the Package record you have created and click on Manage Metadata::
- You will see a metadata grid with all the metadata included in the selected org credential. Select the metadata you want to include in the package (you can create, for instance, a Service package with classes, objects, fields, custom labels and so on related to cases):
- Once you have selected all the necessary components, click on Save. Copado will create a new folder in the master branch of the selected Git repository and will commit the selected metadata from the source org credential.
- Click on the Back button to return to the record page.
Generate a Project Definition File
A Salesforce DX Project Configuration file contains all the information needed in order to create an unlocked package.
To create a project definition file, navigate to the Package record and click on Generate Project Definition File. You will then see a summary of the file:

Versioning an Unlocked Package
A package version is a fixed snapshot of the content of the package and its related metadata. The package version lets you manage changes and track the differences each time you release or deploy a specific set of changes.
To generate a new version of a package, follow these steps:
- Open the Package record and click on Generate New Version:
If you are creating the first version of your package, you will see the following warning: “You need to create a package first to be able to generate beta version”:
- Click on Generate package to create the unlocked package.
- Once the package has been successfully generated, or if you had already created the package and just wanted to create a new version, click again on Generate New Version to create a new version of the package.
- In the Preview Details section, provide the following information:
- Give your version a name and provide a version number. Please note that version numbers must be in major.minor.patch.build format (e.g. 1.0.0.0).
- Add a description of your package (e.g. a summary of the features).
- Provide an installation key. This is an optional parameter for key-protected packages. If you leave it empty, the installationkeybypass parameter will be automatically set to true:
- Once you are done, click on Generate Beta Version to create a new version of the package that can be installed.
Promote Beta Version to Released Version
Prior to installing your package in a production org, you need to promote it to Released.
To do that, follow these steps:
- Navigate to the Package Versions related list and open the record of the version you would like to promote:
- On the drop-down menu, click on Promote Beta to Release:
- You will see a screen with a summary of the definition file:
- Click on Promote Package.
- Once the package has been promoted, the Package Version record will be automatically flagged as Is Released: