salesforcedx-circleci-demo

A demo project showing a Salesforce project being built with SalesforceDX and CircleCI

Overview

CircleCI is a Continuous Integration service. This project demonstrates how to use Salesforce DX with Circle.

Follow the instructions below to get started. Also, take a look the SFDX Travis CI. This project is similar in implementation.

Instructions

1. Generate a an SSL server key and certificate

See keys/makeServerKey.sh as an example you can build upon.

2. Convert it to hex for storing in Circle's env variables.

Circle does a nice job of allowing you to set environment variables inside the UI in a protected way. Because OpenSSL likes key files formatted in a particular fashion, we'll convert it to hex for storage in env variables. This will make it easier to create a valid key file on the fly in the build later.

$ xxd -p server.key >> server.key.hex

3. Set up a Connected App in Salesforce for use with the JWT auth flow.

• Check Enable OAuth Settings

• Set the OAuth callback to http://localhost:1717/OauthRedirect

• Check Use Digital Signatures and add your certificate (likely server.crt) from step (1)

• Select the required OAuth scopes

  • Make sure that refresh is enabled - otherwise you'll get this error: user hasn't approved this consumer

• Once saved, click Manage to set up policies. I used "Admin Approved" for the permitted users and added the correct profiles to the app.

• Verify JWT works through the following command:

sfdx force:auth:jwt:grant --clientid [[consumer-key]] --jwtkeyfile path/to/server.key --username [[username]]

4. Create a project in github, set it up for use with SFDX, and add source files

5. Add the project to your CircleCI account

6. Configure CircleCI variables inside of the settings for your project

• HUB_CONSUMER_KEY: Your Connected App consumer key
• HUB_SERVER_KEY_HEX: The hex version of your server key from step 2
• HUB_SFDC_USER: The username for your Salesforce user

7. Add the example circle.yml and push some commits to your repo to start building

Supporting Sandbox Deployments

Please note that Salesforce DX Source Synchronization (e.g sfdx force:source:push) only works with Scratch Orgs.

Sandboxes still have a place within the Salesforce DX ecosystem. Sandboxes are much less ephemeral (temporary) and so lend themselves better for:

• Working with multiple people (such as QA)
• Larger, more complete data that should be used for testing.

Salesforce DX include a MetaData API component that handles this transition seamlessly - without the need for additional toolkits (such as Ant).

1. (Optional) Although the same key / hex can be used from the Hub, we recommend creating a new key for each sandbox for security purposes.

• Follow the steps 1-2 from above, and rename/secure the keys.

2. Create a Connected app on the Target Sandbox to use during deployment.

• Check Enable OAuth Settings

• Set the OAuth callback to http://localhost:1717/OauthRedirect

• Check Use Digital Signatures and add your certificate (likely server.crt) from previous step.

• Select the required OAuth scopes

  • Make sure that refresh is enabled - otherwise you'll get this error: user hasn't approved this consumer

• Once saved, click Manage to set up policies. I used "Admin Approved" for the permitted users and added the correct profiles to the app.

  • As always, we recommend setting up a separate Profile and User specific for deployments,
    but it is not necessary for it to work.

• Verify JWT works through the following command:

sfdx force:auth:jwt:grant --clientid [[consumer-key]] --jwtkeyfile path/to/server.key --username [[username]]

2. Configure CircleCI variables inside of the settings for your project for DEPLOY_*

• DEPLOY_CONSUMER_KEY: Your Sandbox Connected App consumer key
• DEPLOY_SERVER_KEY_HEX: The hex version of your server key (matching the Sandbox Connected App)
• DEPLOY_SFDC_USER: The username for your Sandbox Salesforce user

3. Uncomment (remove the leading #) from the deploy section of circle.yml