Great news Salesforce application developers! 🎉 We’ve made it easier to build, test, and deploy your Salesforce apps on CircleCI. Now, you can create an automated development pipeline with the help of our integration with Salesforce, the Salesforce SFDX CLI orb.

This post will show you how to quickly get up and running with an automated development pipeline on CircleCI. We will utilize the ebikes-lwc sample application provided by Salesforce and our new Salesforce SFDX CLI orb. If you are completely new to Salesforce application development, this repository is also a great place to start learning.

If you have your own Salesforce application you can still follow along.

What is a CI pipeline?

For those of you coming to CircleCI for the first time, I want to give a quick overview of how a continuous integration pipeline can improve your development workflow.

In short, CircleCI helps you ship code faster and safer. A CircleCI pipeline will allow you to add new features and changes to your application and quickly test those changes prior to deployment. If your tests fail, CircleCI will let you know. Once you have confidence in your code, you can manually or automatically deploy those changes to your users.

Setup

Before we begin creating our pipeline, we have a few setup tasks to complete.

  1. The first one is easy, we simply need to enable the Dev Hub for your account. This allows you to create and manage scratch organizations, which are required for testing your applications in safe, disposable environments.

  2. The next thing we need to do is create our own self-signed SSL certificate and private key. When authenticating with the Salesforce CLI, you typically launch a browser window and log in, but in our CI environment with no human interaction, we need an alternative authentication method.

    For our JWT-based authorization we will create a certificate and Salesforce will hold our certificate, and CircleCI will hold our private key, we’ll get back to that in a moment. Follow the instructions here to create your certificate and key.

  3. Lastly, before we begin our pipeline we have to create a connected app. A connected app is how we are going to connect to our Salesforce instance in the cloud environment and will allow us to authenticate with JTW, utilizing the certificate we created in the last step.

    You can follow the steps on Salesforce here for creating a connected app. You will see that we will be storing our server.crt file with Salesforce in this step. In a moment we will be adding the server key to CircleCI. Be sure to mark down the consumer key value given by the created app.

At this point, it’s time to start prepping our project. If you already have a project you can begin with that, or start off by cloning the ebikes-lwc example we mentioned before. We want to eventually get our project hosted in our VCS provider such as GitHub or BitBucket.

Once we have our project hosted on GitHub or BitBucket, we can start assembling our pipeline.

Adding a project to CircleCI

Our project still isn’t complete, we need to add a CircleCI config file, but we’ll add that in just a moment. We have one last bit of prep work we need to take care of first.

Get started by authorizing your VCS with CircleCI and logging in. Once you are at your dashboard you can click add projects, which should present a list of projects from your account. Click Set Up Project for your Salesforce application.

On the next page, you can simply ignore the defaults. We are going to come back to this in a moment. Click Start building.

On the next page you’ll see right away that our job has failed, but don’t worry! That’s to be expected. We have not yet added our config file with our integration nor set up our environment variables.

2019-12-11-salesforce-3.png

Adding environment variables

Let’s add some required environment variables to this newly added project. In the nav bar on the left of the screen, you should see a list of projects you have added to CircleCI with a cogwheel next to them. Click the cogwheel next to our Salesforce application to reach the settings page.

From there you can click Environment Variable located under BUILD SETTINGS.

We have two secrets we must add for authentication.

Environment Variable Value
SFDX_JWT_KEY This value must contain the base64 encoded value of the private server.key file.
SFDX_CONSUMER_KEY The consumer key of the connected app for Salesforce.


The consumer key was generated in a previous step. Simply add a new environment variable with the name SFDX_CONSUMER_KEY and the value from Salesforce.

To obtain the Base64 encoded JWT key, navigate to the directory containing the self-signed certificate files you created earlier and enter the following command: base64 server.key. Once you have the base64 encoded value, copy it and add it to your project’s environment variables under the SFDX_JWT_KEY key.

2019-12-11-salesforce-6.png

Adding your config

That is all of the setup needed! To recap, so far you have:

  • Enabled the Dev Hub for your Salesforce account
  • Created a connected app
  • Enabled JWT authentication with your connected app
  • Followed the project on CircleCI
  • Added the required environment variables

At this point, CircleCI should be able to authenticate with Salesforce and thus will allow us to utilize the SFDX CLI in our config.

In the main directory of your project repository add a top level .circleci folder, and inside that create a config.yml file. This is the file CircleCI will automatically be looking for when new changes get pushed to your repository. This will act as the blueprint for what actions to perform on each update. If you aren’t familiar with CircleCI config I would highly recommend taking a look at our getting started information.

Once you have created your config.yml file, let’s start by copying over the included usage example from the Salesforce SFDX CLI orb.

version: 2.1
 orbs:
   sfdx: circleci/salesforce-sfdx@x.y
 jobs:
   install_authenticate:
     executor: sfdx/default
     steps:
       - checkout
       - sfdx/install
       - sfdx/auth:
           defaultusername: user@email.com
       - run:
           name: Run your SFDX commands here
           command: |
             echo "You now have access to the sfdx cli and may execute commands against it. https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference.htm"
 workflows:
   basic-test:
     jobs:
       - install_authenticate

Config breakdown

Let’s break this down.

version: 2.1
 orbs:
   sfdx: circleci/salesforce-sfdx@x.y

Version 2.1 of CircleCI config is required access “orbs”, it should be the default but it’s always a great idea to explicitly set the version of your config, especially if things could update in the future.

The orbs stanza is what allows us to define and import our orb packages. In this specific example, we only need the circleci/salesforce-sfdx orb, and you can see we are importing this as sfdx which we will be able to reference elsewhere in our config.

Also notice that there is a version tag at the end of our import statement @x.y, this is a placeholder value, placed here to encourage you to visit the Orb Registry page to view not only the most up-to-date documentation but also ensure you are importing the most current version of the orb.

Orbs are semver versioned so you can import a fully versioned release such as 1.0.0 however we recommend utilizing the minor version so that you may automatically pick up patch releases, ex: 1.0 -> 1.0.1 -> `1.0.2.

Jobs

Below the orb import you will find our jobs stanza with a single job in it named install_authenticate.

jobs:
   install_authenticate:

This is a job we are manually defining in our config file, it is also possible to use pre-defined jobs that sometimes come with orbs.

Your job can, of course, be named anything, and it’s not uncommon to have multiple jobs depending on your workflow. In this workflow, we are simply going to show how to install the CLI tool and authenticate against it in a single job.

Executor

CircleCI offers a wide range of execution environments from Windows, Mac, Linux, and Docker. When we are defining a job, which will execute commands, we have to select which execution environment we would like to execute those commands in.

Orbs also have the ability to define parameterizable executor configs which we have provided in the circleci/salesforce-sfdx orb. You can use the default executor to automatically select a small, fast, and efficient NodeJS Docker environment, perfect for our Salesforce application tasks.

executor: sfdx/default

Steps

Steps are a collection of executable commands we wish to executor in order, in the execution environment we defined above.

 - checkout
       - sfdx/install
       - sfdx/auth:
           defaultusername: user@email.com
  • checkout: A built-in command native to CircleCI which will fetch the source code from your repository. This is not required for the integration but is typically the first step of any project.
  • sfdx/install: An orb command supplied by the circleci/salesforce-sfdx orb which will install the latest stand-alone tar version of the CLI. By supplying an additional version parameter, you may also install a specific version via NPM. More information can be found on the orb documentation.
  • sfdx/auth: An orb command supplied by the circleci/salesforce-sfdx orb which will authenticate with your connected app utilizing JWT authentication. Ensure the environment variables SFDX_JWT_KEY and SFDX_CONSUMER_KEY have been set. You will also be required to set the defaultusername parameter as shown.

From this point on you can utilize other commands from the orb or interact with the sfdx directly with additional commands.

Example:

     - run:
         name: Check Auth List
         command: sfdx force:auth:list

Workflows

Workflows are a feature of CircleCI which allow you to instruct what jobs we want to run and when. We only have a single job in our workflow and in this case, we want it to run on every commit, so we won’t include any filters either. We’ll create a single workflow named basic-test and list our install_authenticate job.

 workflows:
   basic-test:
     jobs:
       - install_authenticate

What else can you do with the Salesforce SFDX CLI orb?

We want to hear from Salesforce developers! Let us know how you use our orb. Tweet to us @CircleCI.