Jenkinsfile Walkthrough

Define Variables

Use the def keyword to define the variables required by Salesforce CLI commands. Assign each variable the corresponding environment variable that you previously set in your Jenkins environment.

def SF_CONSUMER_KEY=env.SF_CONSUMER_KEY
def SERVER_KEY_CREDENTALS_ID=env.SERVER_KEY_CREDENTALS_ID
def TEST_LEVEL='RunLocalTests'
def PACKAGE_NAME='0Ho1U000000CaUzSAK'
def PACKAGE_VERSION
def SF_INSTANCE_URL = env.SF_INSTANCE_URL ?: "https://MyDomainName.my.salesforce.com"

Define the SF_USERNAME variable, but don’t set its value. You do that later.

def SF_USERNAME

Although not required, we assume that you used the Jenkins Global Tool Configuration to create the toolbelt custom tool that points to the CLI installation directory. In your Jenkinsfile, use the tool command to set the value of the toolbelt variable to this custom tool.

def toolbelt = tool 'toolbelt'

You can now reference the Salesforce CLI executable in the Jenkinsfile using ${toolbelt}/sf.

Check Out the Source Code

Before testing your code, get the appropriate version or branch from your version control system (VCS) repository. In this example, we use the checkout scm Jenkins command. We assume that the Jenkins administrator has already configured the environment to access the correct VCS repository and check out the correct branch.

stage('checkout source') {
        // when running in multi-branch job, one must issue this command
        checkout scm
  }

Wrap All Stages in a withCredentials Command

You previously stored the JWT private key file as a Jenkins Secret File using the Credentials interface. Therefore, you must use the withCredentials command in the body of the Jenkinsfile to access the secret file. The withCredentials command lets you name a credential entry, which is then extracted from the credential store and provided to the enclosed code through a variable. When using withCredentials, put all stages within its code block.

This example stores the credential ID for the JWT key file in the variable SERVER_KEY_CREDENTALS_ID. You defined the SERVER_KEY_CREDENTALS_ID earlier and set it to its corresponding environment variable. The withCredentials command fetches the contents of the secret file from the credential store and places the contents in a temporary location. The location is stored in the variable server_key_file. You use the server_key_file variable with the org login jwt command to specify the private key securely.

withCredentials([file(credentialsId: SERVER_KEY_CREDENTALS_ID, variable: 'server_key_file')])
   # all stages will go here 
}

Wrap All Stages in a withEnv Command

When running Jenkins jobs, it’s helpful to understand where files are being stored. There are two main directories to be mindful of: the workspace directory and the home directory. The workspace directory is unique to each job while the home directory is the same for all jobs.

The withCredentials command stores the JWT key file in the Jenkins workspace during the job. However, Salesforce CLI auth commands store authentication files in the home directory; these authentication files persist outside of the duration of the job.

This setup isn’t a problem when you run a single job but can cause problems when you run multiple jobs. So, what happens if you run multiple jobs using the same Dev Hub or other Salesforce user? When the CLI tries to connect to the Dev Hub as the user you authenticated, it fails to refresh the token. Why? The CLI tries to use a JWT key file that no longer exists in the other workspace, regardless of the withCredentials for the current job.

If you set the home directory to match the workspace directory using withEnv, the authentication files are unique for each job. Creating unique auth files per job is also more secure because each job has access only to the auth files it creates.

When using withEnv, put all stages within its code block,

withEnv(["HOME=${env.WORKSPACE}"]) {
   # all stages will go here 
}

Authorize Your Dev Hub Org and Create a Scratch Org

This sfdx-jenkins-package example uses two stages: one stage to authorize the Dev Hub org and another stage to create a scratch org.

// -------------------------------------------------------------------------
// Authorize the Dev Hub org with JWT key and give it an alias.
// -------------------------------------------------------------------------

stage('Authorize DevHub') {   
    rc = command "${toolbelt}/sf org login jwt --instance-url ${SF_INSTANCE_URL} --client-id ${SF_CONSUMER_KEY} --username ${SF_USERNAME} --jwt-key-file ${server_key_file} --set-default-dev-hub --alias HubOrg"
    if (rc != 0) {
        error 'Salesforce dev hub org authorization failed.'
    }
}


// -------------------------------------------------------------------------
// Create new scratch org to test your code.
// -------------------------------------------------------------------------

stage('Create Test Scratch Org') {
    rc = command "${toolbelt}/sf org create scratch --target-dev-hub HubOrg --set-default --definition-file config/project-scratch-def.json --alias ciorg --wait 10 --duration-days 1"
    if (rc != 0) {
        error 'Salesforce test scratch org creation failed.'
    }
}

Use org login jwt to authorize your Dev Hub org.

You’re required to run this step only one time, but we suggest you add it to your Jenkinsfile and authorize each time you run the Jenkins job. This way you’re always sure that the Jenkins job isn’t aborted due to lack of authorization. There’s typically little harm in authorizing multiple times, but keep in mind that the API call limit for your scratch org’s edition still applies.

Use the flags of the org login jwt command to provide information about the Dev Hub org that you’re authorizing. The values for the --client-id, --username, and --instance-url flags are the SF_CONSUMER_KEY, HubOrg, and SF_INSTANCE_URL environment variables you previously defined, respectively. The value of the --jwt-key-file flag is the server_key_file variable that you set in the previous section using the withCredentials command. The --set-default-dev-hub flag specifies that this HubOrg is the default Dev Hub org for creating scratch orgs.

Use the org create scratch CLI command to create a scratch org. In the example, the CLI command uses the config/project-scratch-def.json file (relative to the project directory) to create the scratch org. The --json flag specifies the output as JSON format. The --set-default flag sets the new scratch org as the default.

The Groovy code that parses the JSON output of the org create scratch command extracts the username that was auto-generated as part of the org creation. This username, stored in the SF_USERNAME variable, is used with the CLI commands that push source, assign a permission set, and so on.

Push Source and Assign a Permission Set

Let’s populate your new scratch org with metadata. This example uses the project deploy start command to deploy your source to the org. The source includes all the pieces that make up your Salesforce application: Apex classes and test classes, permission sets, layouts, triggers, custom objects, and so on.

// -------------------------------------------------------------------------
// Push source to test scratch org.
// -------------------------------------------------------------------------

stage('Push To Test Scratch Org') {
    rc = command "${toolbelt}/sf project deploy start --target-org ciorg"
    if (rc != 0) {
        error 'Salesforce push to test scratch org failed.'
    }
}

Recall the SF_USERNAME variable that contains the auto-generated username that was output by the org create scratch command in an earlier stage. The code uses this variable as the argument to the --target-org flag to specify the username for the new scratch org.

The project deploy start command deploys all the Salesforce-related files that it finds in your project. Add a .forceignore file to your repository to list the files that you don’t want pushed to the org.

Run Apex Tests

Now that your source code and test source are pushed to the scratch org, run the apex run test command to run Apex tests.

// -------------------------------------------------------------------------
// Run unit tests in test scratch org.
// -------------------------------------------------------------------------

stage('Run Tests In Test Scratch Org') {
    rc = command "${toolbelt}/sf apex run test --target-org ciorg --wait 10 --result-format tap --code-coverage --test-level ${TEST_LEVEL}"
    if (rc != 0) {
        error 'Salesforce unit test run in test scratch org failed.'
    }
}

You can specify various flags to the apex run test CLI command. In the example:

• The --test-level ${TEST_LEVEL} flag runs all tests in the scratch org, except tests that originate from installed managed packages. You can also specify RunLocalTests to run only local tests, RunSpecifiedTests to run only certain Apex tests or suites or RunAllTestsInOrg to run all tests in the org.
• The --result-format tap flag specifies that the command output is in Test Anything Protocol (TAP) format. The test results that are written to a file are still in JUnit and JSON formats.
• The --target-org ciorg flag specifies the username for accessing the scratch org (the value in SF_USERNAME).

The apex run test command writes its test results in JUnit format.

Delete the Scratch Org

Salesforce reserves the right to delete a scratch org a specified number of days after it was created. You can also create a stage in your pipeline that uses org delete scratch to explicitly delete your scratch org when the tests complete. This cleanup ensures better management of your resources.

// -------------------------------------------------------------------------
// Delete package install scratch org.
// -------------------------------------------------------------------------

stage('Delete Package Install Scratch Org') {
    rc = command "${toolbelt}/sf org delete scratch --target-org installorg --no-prompt"
    if (rc != 0) {
        error 'Salesforce package install scratch org deletion failed.'
    }
}

Create a Package

Now, let’s create a package. If you’re new to packaging, you can think about a package as a container that you fill with metadata. It contains a set of related features, customizations, and schema. You use packages to move metadata from one Salesforce org to another. After you create a package, add metadata and create a new package version.

// -------------------------------------------------------------------------
// Create package version.
// -------------------------------------------------------------------------

stage('Create Package Version') {
    if (isUnix()) {
        output = sh returnStdout: true, script: "${toolbelt}/sf package version create --package ${PACKAGE_NAME} --installation-key-bypass --wait 10 --json --target-dev-hub HubOrg"
    } else {
        output = bat(returnStdout: true, script: "${toolbelt}/sf package version create --package ${PACKAGE_NAME} --installation-key-bypass --wait 10 --json --target-dev-hub HubOrg").trim()
        output = output.readLines().drop(1).join(" ")
}

    // Wait 5 minutes for package replication.
    sleep 300

    def jsonSlurper = new JsonSlurperClassic()
    def response = jsonSlurper.parseText(output)

    PACKAGE_VERSION = response.result.SubscriberPackageVersionId

    response = null

    echo ${PACKAGE_VERSION}
}

Create a Scratch Org and Display Info

Remember when you created a scratch org earlier? Now let’s create a scratch org to install your package into, and display info about that scratch org.

// -------------------------------------------------------------------------
// Create new scratch org to install package to.
// -------------------------------------------------------------------------

stage('Create Package Install Scratch Org') {
    rc = command "${toolbelt}/sf org create scratch --target-dev-hub HubOrg --set-default --definition-file config/project-scratch-def.json --alias installorg --wait 10 --duration-days 1"
    if (rc != 0) {
        error 'Salesforce package install scratch org creation failed.'
    }
}


// -------------------------------------------------------------------------
// Display install scratch org info.
// -------------------------------------------------------------------------

stage('Display Install Scratch Org') {
    rc = command "${toolbelt}/sf org display --target-org installorg"
    if (rc != 0) {
        error 'Salesforce install scratch org display failed.'
    }
}

Install Package, Run Unit Tests, and Delete Scratch Org

To finish up, install your package in your scratch org, run unit tests, then delete the scratch org. That’s it!

// -------------------------------------------------------------------------
// Install package in scratch org.
// -------------------------------------------------------------------------

stage('Install Package In Scratch Org') {
    rc = command "${toolbelt}/sf package install --package ${PACKAGE_VERSION} --target-org installorg --wait 10"
    if (rc != 0) {
        error 'Salesforce package install failed.'
    }
}


// -------------------------------------------------------------------------
// Run unit tests in package install scratch org.
// -------------------------------------------------------------------------

stage('Run Tests In Package Install Scratch Org') {
    rc = command "${toolbelt}/sf apex run test --target-org installorg --result-format tap --code-coverage --test-level ${TEST_LEVEL} --wait 10"
    if (rc != 0) {
        error 'Salesforce unit test run in pacakge install scratch org failed.'
    }
}


// -------------------------------------------------------------------------
// Delete package install scratch org.
// -------------------------------------------------------------------------

stage('Delete Package Install Scratch Org') {
    rc = command "${toolbelt}/sf org delete scratch --target-org installorg --no-prompt"
    if (rc != 0) {
        error 'Salesforce package install scratch org deletion failed.'
    }
}