Release an Unlocked Package¶
While CumulusCI was originally created to develop managed packages, it can also be used to develop and release unlocked packages.
Warning
We do not currently support setting the Ancestor Id for a 2GP package.
Prerequisites¶
To create unlocked package versions, complete these steps.
Connect the Dev Hub org to the CumulusCI keychain by running
cci org connect devhub
. (This is necessary even ifsfdx
has already authenticated to the Dev Hub).To create an unlocked package with a namespace, you must also create a new Developer Edition org to Create and Register Your Namespace, and link the namespace to your Dev Hub.
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.
Important
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.