sfdc-ci-toolkit

CI Scripts for Salesforce projects

This repository purpose is to centralized Continuous Integration scripts dedicated to the Salesforce platform. It allows you to build your app, sanitized your repository (profile and permission sets) and automate things for you. It has been designed and built to be fast, modular and to run with just npm as dependencies.

You can make it run into a basic alpine-node docker image. You can easily add a tasks to this script for your own needs.

Compatible and complementary to SalesforceDX

Getting Started

Works in Unix like system. Windows is not tested.

Installing

$ cd /your/sfdc/repo
$ git clone https://github.com/scolladon/sfdc-ci-toolkit.git
# Or :
$ wget http://github.com/scolladon/sfdc-ci-toolkit/archive/master.zip
$ unzip master.zip

# Then :
$ npm install

then you can either remove .git folder or add it as a submodule of your sfdc repo

Tasks prepackaged

SFDC-ci-toolkit comes with handy npm scripts for CI :

"scripts": {
  "full-build": "npm run deploy",
  "postfull-build": "npm run move-tag",
  "predeploy": "gulp pre-deploy-script",
  "deploy": "gulp deploy",
  "postdeploy": "gulp post-deploy-script",
  "partial-package": "gulp prepare-package",
  "move-tag": "./movetag.sh",
  "partial-build": "npm run partial-package",
  "postpartial-build": "npm run deploy",
  "coverage": "gulp coverage",
  "profile-completion": "gulp profile-completion",
  "profile-reconciliation": "gulp profile-reconciliation",
  "generate-package": "gulp generate-package",
  "generate-data-dictionary": "gulp generate-data-dictionary",
  "display-coverage": "gulp read-coverage",
  "prepare-runtests": "gulp prepare-runtests",
  "retrieve": "gulp retrieve",
  "dataload-insert": "gulp dataload-insert (--concurrencyMode <Serial | Parallel>)",
  "dataload-update": "gulp dataload-update (--concurrencyMode <Serial | Parallel>)",
  "dataload-upsert": "gulp dataload-upsert --extIdField <myExtIdFieldName> (--concurrencyMode <Serial | Parallel>)",
  "dataload-delete": "gulp dataload-delete (--concurrencyMode <Serial | Parallel>)",
  "oneline-profile-and-ps": "gulp oneline-profile-and-ps",
  "env-info": "gulp env-info"
}

Combined them smartly according to your need as a developer or as a release manager ;)

Here is the list of scripts with their description available in the toolkit

Usage Example

Let’s imagine you finalized the three first steps of building a Conference Management app in your sandbox and you want to deploy it to your dev org! First add the toolbox into your repo

$ cd /your/repo/path
$ wget http://github.com/scolladon/sfdc-ci-toolkit/archive/master.zip
$ unzip master.zip -d sfdc-ci-toolkit

add sfdc-ci-toolkit to your gitignore and configure the toolbox (cf Configuration) Then you go to your repository and fetch the objects, the applications, the tabs, the classes and the profiles (field, tab and class access) metadata definition using your favorite ide Then you stage and commit your changes to the repo

$ git add src/objects/*
$ git add src/applications/*
$ git add src/tabss/*
$ git add src/classes/EmailManager*
$ git add src/profiles/*
$ git commit -m 'Conference Management app thirs step cleared :rocket:'

then you will probably complete your profile so your run the profile-completion task :

$ npm run profile-completion # Or if you have gulp globally installed: $ gulp profile-completion

then you will probably check for inconsistency between your profile and the repository so your run the profile-reconciliation task :

$ npm run profile-reconciliation # Or if you have gulp globally installed: $ gulp profile-reconciliation

Then make your changes and staged everything into your repo

$ git add .
$ git commit -m 'profile alignment'

Then you want to generate your package.xml. Two way !

Then you want to prepare the test to execute to allow you to have a lightning fast deployment using Specified Test. edit the SF_TESTSUFFIX variable int the .env file with your test suffix

$ npm run prepare-runtests # Or if you have gulp globally installed: $ gulp prepare-runtests

Then edit the SF_TESTLEVEL variable int the .env file with the value ‘RunSpecifiedTests’

Now you are ready to deploy ! Package your pre and post script into the folders configured into POST_SCRIPT_PATH and PRE_SCRIPT_PATH variables. Execute your pre deploy scripts

$ npm run predeploy # Or if you have gulp globally installed: $ gulp pre-deploy-script

You are going to try the build before merging your dev. So, put the value ‘true’ into the SF_CHECKONLY variable into the .env file and :

$ gulp deploy

Execute your post deploy scripts

$ npm run postdeploy # Or if you have gulp globally installed: $ gulp post-deploy-script

If you want to fetch the coverage from the deployment (works better with a RunLocalTests) execute this command :

$ npm run coverage # Or if you have gulp globally installed: $ gulp coverage

you will get a the coverage to the lcov format in the file ‘coverage.json’ into the sfdc-ci-toolkit folder

You are ready to package your branch and merge it where you want (follow you development process) ! After having merged the dev, you are ready to deploy. Change the SF_CHECKONLY to false. You can launch a prepackaged script to automate those operations :

Configuration

copy the .env_sample file to a .env file in the root directory. It contains the definition of each required parameters with aen example value. Here is what each line is used for and where:

You can optionnaly have multiple conf files. In that case, initialize the SF_CONF_PATH env. variable with the path of the file you want to use.

SF_VERSION Used for: defining the Salesforce API version used Type of value: float one decimal precision (ex: 39.0) Used in:

SF_USERNAME Used for: connecting to Salesforce Type of value: string email format Used in:

SF_PASSWORD Used for: connecting to Salesforce Type of value: string Used in:

SF_SERVERURL Used for: connecting to Salesforce Type of value: string url format Used in:

SF_TESTLEVEL Used for: defining the test strategy when deployinh Type of value: string (NoTestRun | RunLocalTests | RunSpecifiedTests | RunAllTests) Used in:

SF_RUNTESTS Used for: defining the test to run when SF_TESTLEVEL equals “RunSpecifiedTests” Type of value: string apex test classes name Used in:

SF_CHECKONLY Used for: defining the deployment mode Type of value: boolean Used in:

SF_TESTSUFFIX Used for: selecting the test classes to run with the specified test Type of value: string Used in:

SF_SRC_PATH Used for: defining the path to the src folder Type of value: string absolute or relative path from this folder Used in:

SF_REPO_PATH Used for: defining the path to the repository folder (the folder which contains the .git and the src folders) Type of value: string absolute or relative path from this folder Used in:

POST_SCRIPT_PATH Used for: defining the path to the post script folder (the folder which contains the post scripts to execute anonymous) Type of value: string relative path from SF_REPO_PATH folder Used in:

PRE_SCRIPT_PATH Used for: defining the path to the pre script folder (the folder which contains the pre scripts to execute anonymous) Type of value: string relative path from SF_REPO_PATH folder Used in:

Here is the list of optional parameters with their default value :

How to add/modify Task

Just create a js file in the gulp-tasks folder following this canvas

// Include whatever you need

module.exports = (gulp plugins, options) => {
  // use the options object (it contains all the paramters from .env file)
  return cb => {
    gulp.src('a glob pattern')
    .pipe(plugins.yourPluginName())
    .pipe(gulp.dest('/a/dest/path'));
  };
};

Built With

Versioning

SemVer is used for versioning.

Authors

License

This project is licensed under the MIT License - see the LICENSE.md file for details

This site is open source. Improve this page.