salesforce-buildpack

by jwsources

GitHub Readme.md

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.

Below you'll find information on the requirements in your Salesforce project repository, the config vars required to operate the buildpack, and how to quickly setup Heroku Pipelines & CI using the Salesforce CLI's force:pipelines:create command.

To see an example Salesforce project that's configured to use Heroku Pipelines and CI, see https://github.com/wadewegner/salesforce-dx-pipeline-sample. It's also worth noting that this buildpack is dependent on https://github.com/heroku/salesforce-cli-buildpack, which installs the Salesforce CLI into the underlying dyno.

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"
      },
      {
        "url": "https://github.com/heroku/salesforce-buildpack"
      }
      
    • 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 (used for creating a scratch org). 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_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_AUTH_URL: This should map to your production environment.

Quick Setup

While you can setup Herokup Pipelines and CI manually, it helps to initially create using a command we provide. To get started, install the following plugin:

sfdx plugins:install @salesforce/plugins

Once installed, you can run the following command to create your Heroku Pipeline and setup CI:

sfdx force:pipelines:create

Once configured, you can immediately start using Heroku Pipelines and CI.