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.

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

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.

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

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.

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 force:auth:jwt command to specify the private key securely.

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 is not 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 an authentication file exists and another job runs an auth command, the CLI does not replace the authentication file.
• 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,

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.

Use force:auth:jwt:grant to authorize your Dev Hub org.

You are required to run this step only once, 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 is not aborted due to lack of authorization. There is 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 parameters of the force:auth:jwt:grant command to provide information about the Dev Hub org that you’re authorizing. The values for the --clientid, --username, and --instanceurl parameters are the SF_CONSUMER_KEY, HubOrg, and SF_INSTANCE_URL environment variables you previously defined, respectively. The value of the --jwtkeyfile parameter is the server_key_file variable that you set in the previous section using the withCredentials command. The --setdefaultdevhubusername parameter specifies that this HubOrg is the default Dev Hub org for creating scratch orgs.

Use the force:org:create 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 parameter specifies the output as JSON format. The --setdefaultusername parameter sets the new scratch org as the default.

The Groovy code that parses the JSON output of the force:org:create 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 force:source:push command to upload 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.

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

The force:source:push command pushes 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 force:apex:test:run command to run Apex tests.

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

• The --testlevel ${TEST_LEVEL} option 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 --resultformat tap option 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 --targetusername ciorg option specifies the username for accessing the scratch org (the value in SF_USERNAME).

The force:apex:test:run 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 force:org:delete to explicitly delete your scratch org when the tests complete. This cleanup ensures better management of your resources.

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 a Scratch Org and Display Info

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

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!