Heroku Buildpack for Salesforce

This is the official Heroku buildpack for Salesforce apps. This buildpack enables various Salesforce specific development operations such as creating scratch orgs and pushing source, creating and installing Unlocked Packages, running Apex unit tests, and deploying metadata. It uses https://github.com/heroku/salesforce-cli-buildpack to download and setup the Salesforce CLI and jq.

Below you'll find information on the requirements in your Salesforce project repository and the config vars required to operate the buildpack. To painlessly setup your Heroku Pipeline, use this setup script.

To see an example Salesforce project that's configured to use Heroku Pipelines and CI, see salesforce-dx-pipeline-sample.

Requirements

This buildpack requires the following to be present in the Salesforce app repository you're connecting to the pipeline.

1. app.json: The app.json file provides instructions to this buildpack. In particular, the app.json provides information used by review apps that are created when a pull request is initiated.

   • buildpacks: Specifies the buildpacks used by the review apps.

     "buildpacks": [
     {
       "url": "https://github.com/heroku/salesforce-cli-buildpack#v3"
     },
     {
       "url": "https://github.com/heroku/salesforce-buildpack#v3"
     }
     

   • env: Specifies config vars and the values in the review app.

     "env": {
       "SFDX_DEV_HUB_AUTH_URL": {
         "required": true
       },
       "SFDX_BUILDPACK_DEBUG": {
         "required": true
       },
       "HEROKU_APP_NAME" : {
         "required": true
       }
     },
     

   • environments/tests/scripts: Specifies the scripts used to invoke CI tests. These test scripts are created automatically if they are not found locally.

     "environments": {
       "test": {
         "scripts": {
           "test-setup":
             "./vendor/sfdx/release.sh ci-$HEROKU_TEST_RUN_COMMIT_VERSION && ./bin/test-setup.sh",
           "test": "./bin/test.sh"
         }
       }
     },
     

   • scripts/pre-predestroy: Specifies the script to run when a review app is destroy. This script is automatically generated by the buildpack, so you don't have to specify anything.

     "scripts": {
       "pr-predestroy": "./bin/ra-org-delete.sh"
     },
     

2. sfdx.yml: This yaml file also provides information to the buildpack but specifically related to the Salesforce DX project. Here you can specify information related to how your app is configured and setup.

   scratch-org-def: config/project-scratch-def.json
   assign-permset: false
   permset-name:
   run-apex-tests: true
   apex-test-format: tap
   show-scratch-org-url: false
   open-path: 
   import-data: false
   data-plans:
   

3. sfdx-project.json: If you are using Unlocked Packages, which is the default behavior, you'll need to ensure the required packaging data is in your sfdx-project.json file.

   "packageDirectories": [
   {
     "path": "force-app",
     "default": true,
     "id": "0Ho6A0000000000",
     "versionNumber": "1.0.0.NEXT",
     "versionName": "Summer '18"
   }
   

Config Vars

The buildpack uses config vars associated with each Heroku App to controll the execution of the buildpack. These config vars are used across all stages.

Development

Note: Typically the development stage is the parent to review apps, so these config vars will also be used for all review apps generated.

• STAGE=DEV: Instructs the buildpack that this app stage is DEV.

• SFDX_CREATE_PACKAGE_VERSION=true: Instructs the buildpack to create a new package version from the source.

• SFDX_INSTALL_PACKAGE_VERSION=true: Instructs the buildpack that it will perform a package install. Setting this value to false (or excluding it) will cause the buildpack to perform a force:source:convert followed by a force:mdapi:deploy.

• SFDX_PACKAGE_NAME="$PACKAGE_NAME": Tells the buildpack the name of the package to create and install.

• SFDX_BUILDPACK_DEBUG=true: Instructs the buildpack to display debug information.

• SFDX_DEV_HUB_AUTH_URL: Provides credentials to the buildpack for connecting to the Dev Hub. You can get this value by running sfdx force:org:display --verbose --json against your Dev Hub and grabbing the sfdxAuthUrl.

• SFDX_AUTH_URL: Provides credentials to the buildpack for connecting to the org used by Development (typically a dev integration environment). You can get this value by running sfdx force:org:display --verbose --json against your org and grabbing the sfdxAuthUrl.

Staging

These values are the same as above but with the following considerations.

• STAGE=STAGING: Instructs the buildpack that this app stage is STAGING.

• SFDX_CREATE_PACKAGE_VERSION=false: Typically you don't want to create a new package version at each stage. So this value should be false.

• SFDX_DEV_HUB_AUTH_URL: Provides credentials to the buildpack for connecting to the Dev Hub. You can get this value by running sfdx force:org:display --verbose --json against your Dev Hub and grabbing the sfdxAuthUrl.

• SFDX_AUTH_URL: This should map to your staging environment, typically a full sandbox.

Production

These values are the same as above but with the following considerations.

• STAGE=PROD: Instructs the buildpack that this app stage is PROD.

• SFDX_DEV_HUB_AUTH_URL: Provides credentials to the buildpack for connecting to the Dev Hub. You can get this value by running sfdx force:org:display --verbose --json against your Dev Hub and grabbing the sfdxAuthUrl.

• SFDX_AUTH_URL: This should map to your production environment.