Get Started

Install CumulusCI

Tip

These installation instructions assume some familiarity with entering commands into a terminal. If that’s completely new to you, we recommend visiting the CumulusCI Setup module on Trailhead for a step-by-step walkthrough.

On macOS

Homebrew is a prerequisite for installing CumulusCI on macOS. Follow the instructions on the Homebrew website to install Homebrew before continuing.

Install via pipx

pipx ensures that CumulusCI and its dependencies are installed into their own Python environment separate from other Python software on your computer. We cannot recommend it enough!

First, install pipx with these commands:

$ brew install pipx
$ pipx ensurepath

After pipx installs, install CumulusCI:

$ pipx install cumulusci

When finished, verify your installation.

On Linux

Install via pipx

pipx ensures that CumulusCI and its dependencies are installed into their own Python environment separate from other Python software on your computer. We cannot recommend it enough!

Installation instructions for pipx can be found here.

After pipx installs, install CumulusCI:

$ pipx install cumulusci

When finished, verify your installation.

On Windows

Install Python 3

  1. Go to the Python downloads page.

  2. Download the latest Python 3 release. Most users select the “Download Windows x86-64 executable installer” link for the most recent stable release, but it depends on your particular computer setup.

  3. Install using the installation wizard.

    • Select Add Python <version> to PATH.

    • Click “Install Now”.

_images/windows_python.png

Install via pipx

pipx ensures that CumulusCI and its dependencies are installed into their own Python environment separate from other Python software on your computer. We cannot recommend it enough!

Open your preferred terminal application (such as cmd.exe on Windows). If your terminal is already open, close it and reopen it. Enter this command:

$ python -m pip install --user pipx
_images/pipx.png

To permanently modify the default environment variables:

  1. Click Start and search for edit environment variables, or open System properties and click Advanced system settings.

  2. Click the Environment Variables button.

  3. To change System variables, you need non-restricted access (administrator rights) to your machine. Add these paths to your PATH environment variable:

    • %USERPROFILE%\.local\bin

    • %USERPROFILE%\AppData\Roaming\Python\Python38\Scripts

_images/env-var2.png

Note

Be precise when entering these paths. Add them at the very end of the Variable Value already in place. Separate each path by a semicolon (;) with no space between path names.

Open a new command prompt and verify that pipx is available:

pipx --version

Look for a version number after entering this command, such as: 0.12.3.1.

If you get an error instead, such as 'pipx' is not recognized as an internal or external command, operable program or batch file., confirm that your environment variables have been updated.

Finally, install CumulusCI with this command:

pipx install cumulusci

When finished, verify your installation.

Verify Your Installation

In a new terminal window, verify that CumulusCI installed correctly by running cci version.

$ cci version
CumulusCI version: 3.29.0 (/path/to/bin/cci)
Python version: 3.8.5 (/path/to/bin/python)

You have the latest version of CumulusCI.

You can also use this command to check whether your CumulusCI installation is up to date.

Still need help? Feel free to submit a question on our Trailblazer community group.

Set Up SFDX

Scratch orgs created by Salesforce DX allow teams to work efficiently in individual, fully-configured environments that are easy to create and destroy. We recommend working with scratch orgs throughout the development process.

To set up Salesforce DX:

  1. Install Salesforce CLI

  2. Enable Dev Hub Features in Your Org

  3. Connect SFDX to Your Dev Hub Org - Be sure to use the --setdefaultdevhubusername option!

If you have the sfdx command installed, are connected to your Dev Hub, and set the defaultdevhubusername config setting (use sfdx force:config:list to verify), you’re now ready to use cci with sfdx to build scratch orgs.

Important

SFDX supports multiple Dev Hubs, so CumulusCI uses the one set as defaultdevhubusername when creating scratch orgs.

Tip

For a detailed introduction on how to set up Salesforce CLI and Visual Studio Code to work with CumulusCI, review the Build Applications with CumulusCI module on Trailhead.

Learn more about Salesforce DX at https://developer.salesforce.com/platform/dx.

Connect to GitHub

In order to allow CumulusCI to work with your repositories in GitHub, connect GitHub as a service in cci.

First, create a new personal access token with both repo and gist scopes specified. (Scopes appear as checkboxes when creating the personal access token in GitHub.) Copy the access token to use as the password when configuring the GitHub service.

Next, run the following command and provide your GitHub username and access token as the password:

$ cci service connect github mygithub

Verify the GitHub service is connected by running cci service list:

_images/service-list.png

After you’ve configured the github service, it’s available to all CumulusCI projects.

Services are stored in the global CumulusCI keychain by default.

Work On an Existing CumulusCI Project

If you’d like to work on an existing CumulusCI project on GitHub, these are the prerequisites.

  1. Install CumulusCI

  2. Install Git

  3. Clone the Project’s GitHub Repository

Note

CumulusCI does not support projects stored on other Git hosts such as BitBucket or GitLab at this time.

You can change directories into the project’s root directory and begin executing cci commands.

For example, cci project info shows information about the project:

$ cd cumulusci-test

$ cci project info
name: CumulusCI Test
package:
    name: CumulusCI Test
    name_managed: None
    namespace: ccitest
    install_class: None
    uninstall_class: None
    api_version: 33.0
git:
    default_branch: main
    prefix_feature: feature/
    prefix_beta: beta/
    prefix_release: release/
    release_notes:
        parsers:
            1:
                class_path: cumulusci.tasks.release_notes.parser.GithubLinesParser
                title: Critical Changes
            2:
                class_path: cumulusci.tasks.release_notes.parser.GithubLinesParser
                title: Changes
            3:
                class_path: cumulusci.tasks.release_notes.parser.GithubIssuesParser
                title: Issues Closed
            4:
                class_path: cumulusci.tasks.release_notes.parser.GithubLinesParser
                title: New Metadata
            5:
                class_path: cumulusci.tasks.release_notes.parser.GithubLinesParser
                title: Deleted Metadata
    repo_url: https://github.com/SFDO-Tooling/CumulusCI-Test
test:
    name_match: %_TEST%

Start a New CumulusCI Project

If you’d like to start a new CumulusCI project, these are the prerequisites.

  1. Install CumulusCI

  2. Install Git

  3. Install the Salesforce CLI

Run the following commands to create a directory with your project’s name, navigate to said directory, and initialize it as a Git repository:

$ mkdir cci_project
$ cd cci_project
$ git init

Then, initialize the project as a CumulusCI project.

Project Initialization

Use the cci project init command within a Git repository to generate the initial version of a project’s cumulusci.yml file. CumulusCI creates a customized cumulusci.yml file by first asking questions about your project.

Prompt

What’s it for?

Project Info

The name is usually the same as your repository name. NOTE: Do not use spaces in the project name.

Package Name

CumulusCI uses an unmanaged package as a container for your project’s metadata. Enter the name of the package you want to use.

Is this a managed package project?

Yes, if this project is a managed package.

Salesforce API Version

Which Salesforce API version does your project use? Defaults to the latest API version.

Which source format do you want to use? [sfdx | mdapi]

DX source format (aka “SFDX Format”) stores data under the force-app directory. Metadata API format is the “older” format and stores data under the src directory.

Are you extending another CumulusCI project such as NPSP or EDA?

CumulusCI makes it easy to build extensions of other projects configured for CumulusCI like Salesforce.org’s NPSP and EDA. If you are building an extension of another project using CumulusCI and have access to its GitHub repository, use this section to configure this project as an extension.

Default Branch

Your project’s main/master branch in GitHub. Defaults to the branch that is currently checked out in your local repository.

Feature Branch Prefix

Your project’s feature branch prefix (if any). Defaults to feature/.

Beta Tag Prefix

Your project’s beta branch prefix (if any). Defaults to beta/.

Release Tag Prefix

Your project’s release branch prefix (if any). Defaults to release/.

Test Name Match

The CumulusCI Apex test runner uses a SOQL WHERE clause to select which tests to run. Enter the SOQL pattern to match test class names. Defaults to match classes ending in TEST.

Do you want to check Apex code coverage when tests are run?

If yes, checks Apex code coverage when tests are run.

Minimum code coverage percentage

Sets the minimum allowed code coverage percentage for your project.

Verify Project Initialization

Verify successful project initialization by verifying that cumulusci.yml exists and has contents.

$ cat cumulusci.yml
project:
    name: SampleProjectName
    package:
        name: SamplePackageName
        namespace: sampleNamespace
    .
    .
    .

The cumulusci.yml file configures your project-specific tasks, flows, and customizations.

Once you’re satisfied, add and commit it to your Git repository.

$ git add cumulusci.yml
$ git commit -m "Initialized CumulusCI Configuration"

Add Your Repo to GitHub

With your cumulusci.yml file committed, create a repository on GitHub for your new project and push your changes there, using whichever method you prefer.

Convert an Existing Salesforce Project

Converting an existing Salesforce project to use CumulusCI can follow a number of different paths, depending on whether you’re practicing the Org Development Model or the Package Development Model; whether or not you’re already developing in scratch orgs; and the complexity of your project’s dependencies on the org environment.

If you’re developing in persistent orgs and not already using source control, you’ll also need to retrieve the existing metadata from the org. Note that the processes of adopting source control and moving from persistent orgs to scratch orgs tend to look different for everyone, and these transitions sometimes require additional work.

You’re welcome to discuss project conversion in the CumulusCI (CCI) Trailblazer group.

Project Setup

Before retrieving your project’s metadata, set up the project’s root directory.

Retrieve Metadata from the Persistent Org

This documentation assumes that your project currently lives in a persistent org, such as a Developer Edition org or a Sandbox. We recommend retrieving metadata via the Metadata API (using the Salesforce CLI), followed by converting the source from Metadata API to SFDX format.

  1. If the metadata you want to retrieve isn’t already in a package, create one. See creating packages for more info.

    Note

    If your project contains a managed package, ensure that the package namespace matches the namespace you entered when running cci project init.

  2. Run the retrieve command to extract your package metadata.

$ sfdx force:source:retrieve -n package_name /path/to/project/

That’s it! You now have all of the metadata you care about in a single Git repository configured for use with CumulusCI. At this point add your repo to GitHub, or perhaps begin to Configure CumulusCI.

Setup Scratch Orgs

To see how to use scratch orgs with CumulusCI see the Manage Scratch Orgs section.

Other Conversion Considerations