skippy107/cumulusci repository overview

This Linux image contains python, CumulusCI, SFDX-CLI, Google Chrome, and the Chrome Webdriver

When you start the container it will attempt to authenticate to your DevHub Org and run all the Robot tests in the CumulusCI project at /usr/src/app

Prerequisites

1. Ensure that your Docker engine is running on Linux Containers. Right click the icon and choose Linux Containers if it is not.

2. An empty initialized CumulusCI project, note the folder name

3. Ensure that your Salesforce DevHub instance is working with your local instance of CumulusCI. DevHub should be enabled for the org and you should be able to run the sample test create_contact.robot against a scratch org.

4. A connected app on your DevHub Org. (ONLY DO THIS ONCE, YOU CAN REUSE THE CONNECTED APP)

   Create a connected app for your DevHub org using instructions at https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_connected_app.htm⁠

   • Note the Consumer Key you will need it to authorize the org

5. Credential files for your project. (ONLY DO THIS ONCE, YOU CAN REUSE THESE FILES)

   Spin up a python container and connect it to your source folder

   • Docker run --rm -it -v <project folder>:/usr/src/app python:latest sh

   Use this container for the next step

   Create key and certificate using instruction at https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_key_and_cert.htm⁠

   • mkdir /usr/src/app/certs
   • Perform all steps in /usr/src/app/certs
   • Save a copy of the files in a safe place on your laptop
     • In Windows you will now see a certs folder in your cci project folder
   • Close the container

   Create a file in the certs folder called consumerKey and add your connected app Consumer Key to it.

   Create a file in the certs folder called devhubID and add your DevHub email address to it.

Using the Image

DevHub orgs are limited to three active scratch orgs and can only create six new scratch orgs per day.

When the CumulusCI container is spun up from an image it does not have any information about existing DevHub scratch orgs. Because of this it will authenticate using the credentials in the certs folder, which initializes the list of scratch orgs to zero. Then on the first test run it will create a new scratch org. When the next container is spun up it will do the same thing and so on until we reach the daily limit enforced by DevHub which is only six new scratch orgs per day.

To ensure that we re-use the scratch orgs in our containers we need to find a way for the container to see existing scratch orgs. The simple solution is to re-use the data folders that maintain the scratch org information. These are the .sfdx and .cumulusci folders. By simply mounting them to a folder in the project structure we can re-use the files every time. This will prevent CumulusCI from creating new scratch orgs unnecessarily.

Before using the mounts we have to have matching data folders created on the Docker host. This is only needed once and after that the org states will be maintained in the folders as long as the folders are mounted on every run.

Simply create two folders in the root of the CCI project folder, called _cci and _sfdx.

Place the devhubID, consumerKey, and server.key files in a folder called certs in the project folder

Interactive Session

docker run --rm -it -v <project folder>/_cci :/home/docker/.cumulusci -v <project folder>/_sfdx :/home/docker/.sfdx -v <project folder> :/usr/src/app skippy107/cumulusci:latest sh -l

From here you can run individual tests, or other sfdx-cli commands against your orgs

CI/CD Execution

All you need is docker installed on your CI/CD server.

Inside your pipeline, you will check your tests out of source code, then copy in the credentials from a safe place

Then run the container to execute all tests:

docker run --rm -it -v <project folder>/_cci :/home/docker/.cumulusci -v <project folder>/_sfdx :/home/docker/.sfdx -v <project folder> :/usr/src/app skippy107/cumulusci:latest