Configure Metadata Deployment#
deploy task uses the Metadata API to deploy metadata from the repository to a Salesforce org.
deploy offers multiple sophisticated capabilities to suit the needs of your project.
Specifying the Deploying Package and Test Run Levels#
path option to specify the path to the metadata you wish to deploy. The metadata may be in either Metadata API or Salesforce DX source format. SFDX-format source will automatically be converted to Metadata API for deployment. This conversion takes place prior to application of transforms (below) and requires that the path be listed as a package directory in
Set the test run level with the
test_level option. Available values are
RunSpecifiedTests. If you use
RunSpecifiedTests, you must also supply a list of tests with the
specified_tests option. This option accept a comma-separated value at the command line or a list in your
deploy allows you to specify transforms that run against your metadata before it is delivered to the Salesforce platform. Some of these transforms are built-in, and others you can specify in your
cumulusci.yml to suit your project’s specific needs.
Four of the
deploy transformations are built-in, and controlled by task options (see below). Others, including the flexible
find_replace transform, are specified by your customization in
You can specify transforms to run everywhere
deploy is invoked by using customization in your
tasks: deploy: options: transforms: - transform: find_replace options: patterns: - find: foo replace: bar
You can also add a transform for just a specific flow step:
flows: my_flow: steps: 1: task: deploy options: transforms: - transform: find_replace options: patterns: - find: foo replace: bar
or override the options in an out-of-the-box flow:
flows: deploy_packaging: options: deploy: transforms: - transform: find_replace options: patterns: - find: foo replace: bar
deploy task, like many others in CumulusCI, supports namespace injection. This strategy allows you to flexibly inject your package’s namespace into (or remove it from) your metadata to suit various deployment contexts. See Namespace Injection for more information about namespace injection.
In most cases, you don’t need to customize
deploy options for namespace injection, as the task will automatically infer the appropriate strategy. If you do find an edge case where inference does not suit your needs, you can configure namespace injection using the following options.
namespace_inject: set to specify the namespace to inject against tokens.
namespace_strip: set to specify the namespace prefix to remove.
unmanaged: set to
Trueto replace namespace tokens with the empty string.
namespaced_org: set to
Trueto replace the special
NAMESPACED_ORGtokens with the namespace. Note that the packaging org is considered a namespaced-org context.
deploy can automatically remove references (
<packageVersions/> elements) to the versions of other managed packages from
*-meta.xml files in your metadata. This cleaning is controlled by the
clean_meta_xml option, which defaults to
Static Resource Bundling#
For products that are in Metadata API source format,
deploy, can automatically Static Resource content that is stored uncompressed in an alternate directory into the ZIP files expected by the platform. To use this capability, set the option
static_resource_path to the path where you store unzipped Static Resource content. CumulusCI will ZIP each subdirectory and place the archives in the
staticresources directory in the deployment bundle. You must include required
-meta.xml files in the
Feature-Parameter Cleaning for Unlocked Packages#
Unlocked Packages do not support Feature Parameter metadata. When CumulusCI is building an Unlocked Package, this transform will automatically remove Feature Parameter metadata from the deployment bundle.
Find-and-Replace Variable Injection#
CumulusCI allows you to specify arbitrary injections of data against tokens you define in your metadata. This capability is often used, for example, to inject secure keys or tokens from environment variables.
Configure injection with the
find_replace transform like this:
task: deploy options: transforms: - transform: find_replace options: patterns: - find: foo replace: bar
To use an environment variable as the source of the value to replace, use the
replace_env key. Note that it’s valid to use multiple runs of
find_replace; they will be applied in sequence.
task: deploy options: transforms: - transform: find_replace options: patterns: - find: AUTH_TOKEN replace_env: SECURE_ACCESS_KEY - find: foo replace: bar
Stripping Components with a
This transformation allows you to deploy a subset of a metadata directory based on a
package.xml manifest by removing unwanted components. It will compare components available in the source folder with a provided
package.xml file and delete/modify component files which are not found.
task: deploy options: transforms: - transform: strip_unwanted_components options: package_xml: PACKAGE_XML_FILE_PATH