Release an Unlocked Package

While CumulusCI was originally created to develop managed packages, it can also be used to develop and release unlocked packages.


We do not currently support setting the Ancestor Id for a 2GP package.


To create unlocked package versions, complete these steps.

Create a Package Version

To create a new unlocked package version, run the create_package_version task against a scratch org.

$ cci task run create_package_version --org <org_name> --package_type Unlocked

This task looks in your default Dev Hub org (as configured in sfdx) for an unlocked package with the name and namespace specified in the task options (defaulting to the name and namespace from the project__package section of the cumulusci.yml file). If a matching package doesn’t exist, CumulusCI first creates a Package2 object, and then submits a request to create the package version. When completed (which can take some time), the task outputs a SubscriberPackageVersion ID, which can be used to install the package in another org.

If a package version already exists with the exact same contents, as determined by the hash of the package metadata, its SubscriberPackageVersion ID is returned rather than creating a new version.

Handle Dependencies

CumulusCI tries to convert dependencies configured under the project section of the cumulusci.yml file into a SubscriberPackageVersion ID (04t key prefix). This format is required for dependencies in the API to create a package version.

For dependencies that are specified as a managed package namespace and version, or dependencies specified as a GitHub repository with releases that can be resolved to a namespace and version, CumulusCI needs a scratch org with the dependencies installed to execute this conversion in the create_package_version task.


Install the dependencies in this scratch org before running the create_package_version task!

The scratch org’s definition file also specifies the correct org shape when building the new package version.

For dependencies that are an unpackaged bundle of metadata, CumulusCI creates an additional unlocked package to contain them.

Promote a Package Version

To be installed in a production org, an 2GP package version must be promoted to mark it as released.

Use the promote_package_version task along with a valid SubscriberPackageVersionId to promote a 2GP package.

$ cci task run promote_package_version --version_id 04t000000000000

If additional unlocked packages were created to hold unpackaged dependencies, they must be promoted as well. To promote dependencies automatically use --promote_dependencies True.

$ cci task run promote_package_version --version_id 04t000000000000 --promote_dependencies True

Alternatively, you can use the sfdx force:package:version:promote command to promote a 2GP package.

Install the Unlocked Package

To install an unlocked package with CumulusCI:

Configure either the update_dependencies or the install_managed task and provide the SubscriberPackageVersion ID of the unlocked package to be used.

The update_dependencies task can be configured in the cumulusci.yml file.

For the install_managed task, run it via cci

Or configure it in the cumulusci.yml file.

To install unlocked packages in an org that doesn’t use CumulusCI, use one of these methods.