Run CumulusCI Headlessly#
CumulusCI can be used to run continuous integration builds in your CI system.
This section outlines how to setup services and orgs that can be defined in a particular environment such that they will be recognized by CumulusCI.
If you’re working in GitHub Actions, you can take advantage of our GitHub Actions framework to streamline your setup process. You’ll need the information in this document only if you wish to use an alternate authorization strategy or configure additional services.
Register Environment Services#
It is often the case that services you use for local development will differ from the services that you want to use in your build system. For example, developers will setup a GitHub service locally that is associated with their GitHub User, while an integration build may want to run as an integration user when interacting with GitHub. By providing environment variables with specific prefixes, CumulusCI can detect and register those services for use when running tasks and flows.
Name Environment Services#
Environment variables that define CumulusCI services adhere to the following format:
CUMULUSCI_SERVICE_<service_type>[__service_name]
All services should start with the prefix CUMULUSCI_SERVICE_
followed
immediately by the service_type
(for a full list of available services
run cci service list
). Additionally, you have the option to provide a
unique name for your service by adding a double underscore (__
)
followed by the name you wish to use. If a name is specified it is
prepended with “env-” to help establish that this service is coming
from the environment. If a name is not specified, a defualt name of
env
is used for that service.
Here are some examples of environment variable names along with their corresponding service types and names:
CUMULUSCI_SERVICE_github
–> Agithub
service that will have the default name ofenv
CUMULUSCI_SERVICE_github__integration-user
–> Agithub
service that will have the nameenv-integration-user
CUMULUSCI_SERVICE_github_enterprise__enter-user
–> Agithub_enterprise
service that will have the nameenv-enter-user
CUMULUSCI_SERVICE_connected_app
–> Aconnected_app
service with the default name ofenv
CUMULUSCI_SERVICE_connected_app__sandbox
–> Aconnected_app
service with the nameenv-sandbox
By always prepending env
to the names of services
specified by environment variables, it is easy to see which services are
currently set by environment variables and which are not.
Environment Service Config Values#
The value of the environment variables (i.e. everything that comes after
the =
character) are provided in the form of a JSON string. The
following shows an example that defines a github service via an
environment variable:
CUMULUSCI_SERVICE_github='{"username": "jdoe", "email": "jane.doe@some.biz", "token": "<personal_access_token>"}'
These values provide CumulusCI with the required attributes for a
particular service. The easiest way to find what attributes are needed
for a particular service is to look for your service under the services
tag in the CumulusCI standard
library
and provide values for all “attributes” listed under the desired
service. You can also use cci service info
to get the values from a
service you’ve configured locally.
For example, if you’re looking to register a connected_app
service,
then the attributes: callback_url
, client_id
, and client_secret
would need to be provided in the following format:
"{"callback_url": "<callback_url>", "client_id": "<client_id>", "client_secret": "<client_secret>"}"
The values
<callback_url>
,<client_id>
, and<client_secret>
should all be replaced with actual values.
GitHub Enterprise Server considerations#
The use of GitHub environment variables is supported when connecting to a repository a GitHub Enterprise Server.
The GitHubEnterprise
client is selected automatically based on the repository configuration in the cumulusci.yml
file. When the repo_url
is NOT GitHub.com an attempt will be made to connect to the base domain in repo_url
. The GitHub environemnt variables are then used to authorize.
If your use case requires dependencies on a different server, for example, upstream dependencies reside on GitHub.com but your project repository is stored on a GitHub Enterprise Server do not use , instead configure services for GitHub.com and your GitHub Enterprise Server similarly to this example:
CUMULUSCI_SERVICE_github='{"username": "jdoe", "email": "jane.doe@some.biz", "token": "<personal_access_token>"}'
CUMULUSCI_SERVICE_github_enterprise`='{"username": "jdoe", "email": "jane.doe@some.biz", "server_domain":"git.some.biz", "token": "<enterprise_personal_access_token>"}'
When connecting to repositories on GitHub.com or GitHub Enterprise Server, the service configuration for authorization is selected automatically by matching the server_domain
field to the repository domain. When a repository domain is github.com
the github
service will be used.
Register Persistent Orgs#
SFDX Auth URL Authorization#
CumulusCI can import persistent org authorization from the SFDX CLI. This capability allows you to store the SFDX auth URL for an org in your CI system’s secret storage, import it into the SFDX keychain, and then use it directly from CumulusCI.
To do so, follow these steps.
Retrieve your auth URL.
Authorize the org using
sfdx auth:sfdxurl:store
.Run
cci org import <org name> <org name>
.
JWT Flow Authorization#
Using JWT authorization provides you with the greatest control over access to your persistent org. This approach uses a Connected App and digital certificate, which you control and can rotate as desired.
First, you need a Connected App that is configured with a certificate in the “Use digital signatures” setting in its OAuth settings. You can follow the Salesforce DX Developer Guide to get this set up:
In addition to the OAuth scopes mentioned in that article, CumulusCI also requires the
full
scope.
Once you have a Connected App created, you can configure CumulusCI to use this Connected App to login to a persistent org by setting the following environment variables.
CUMULUSCI_ORG_orgName
SFDX_CLIENT_ID
SFDX_HUB_KEY
See the below entries for the values to use with each.
Important
Setting the above environment variables negates the need to use the
cci org connect
command. You can simply run a cci
command and pass
the --org orgName
option, where orgName
corresponds to the name used
in the CUMULUSCI_ORG_*
environment variable.
In the context of GitHub Actions, all of these environment variables
would be declared under the env
section of a workflow. Below is an
example of what this would look like:
env:
CUMULUSCI_ORG_sandbox:
{
"username": "just.in@salesforce.org",
"instance_url": "https://sfdo--sbxname.my.salesforce.com",
}
SFDX_CLIENT_ID: { { $secrets.client_id } }
SFDX_HUB_KEY: { { $secrets.server_key } }
The above assumes that you have client_id
and server_key
setup in
your GitHub encrypted
secrets
Note that the value of the server_key
environment variable is the
content of the file server.key
, which was created as part of your
Connected App setup. The key is in PEM format.
CUMULUSCI_ORG_orgName
#
The name of this environment variable defines what name to use for the
value of the --org
option. For example, a value of
CUMULUSCI_ORG_mySandbox
would mean you use --org mySandbox
to use
this org in a cci
command.
Set this variable equal to the following json string:
{
"username": "USERNAME",
"instance_url": "INSTANCE_URL"
}
USERNAME
- The username of the user who will login to the target org.INSTANCE_URL
- The instance URL for the org. Should begin with thehttps://
schema.
You can see an example of setting this environment variable in a GitHub actions workflow in our demo repository.
Wizard Note
If the target org’s instance URL is instanceless (i.e. does not contain
a segment like cs46 identifying the instance), then for sandboxes it is
also necessary to set SFDX_AUDIENCE_URL
to
https://test.salesforce.com"
. This instructs CumulusCI to set the
correct aud
value in the JWT (which is normally determined from the
instance URL).
SFDX_CLIENT_ID
#
Set this to your Connected App’s client id. This, combined with the
SFDX_HUB_KEY
variable instructs CumulusCI to authenticate to the org
using the JWT Bearer
Flow
instead of the Web Server
Flow.
SFDX_HUB_KEY
#
Set this to the private key associated with your Connected App (this is
the contents of your server.key
file). This combined with the
SFDX_CLIENT_ID
variable instructs CumulusCI to authenticate to the org
using the JWT Bearer
Flow
instead of the Web Server
Flow.
Multiple Services of the Same Type#
In rare cases a build may need to utilize multiple services of the same
type. To set a specific service as the default for subsequent
tasks/flows run the cci service default <service_type> <name>
command.
You can run this command again to set a new default service to be used
for the given service type.