Skip to content

Scratch Org CI ​

Reusable workflow that runs a full scratch org lifecycle: it authenticates to the Dev Hub, creates a scratch org, optionally installs dependency packages, deploys the source, optionally assigns permissions and runs anonymous Apex setup scripts, brings the Agentforce agents to the org, runs Apex tests and, on request, agent tests, and always deletes the scratch org again.

Reusable workflow - call it from your own repository with uses:. View source

Inputs ​

InputDescriptionTypeRequiredDefault
source-dirSource directory to deploy to the scratch org.stringnoforce-app
build-scriptOptional npm script to run from the repository root before the deployment, e.g. "build:ui-bundles" to build the UI bundles of a Multi-Framework project. It runs with the package manager of the repository and with SF_TARGET_ORG set to the scratch org. Leave empty to skip.stringno-
definition-filePath to the scratch org definition file.stringnoconfig/project-scratch-def.json
duration-daysNumber of days before the scratch org expires.stringno1
test-levelApex test level for the test run. Ignored when apex-tests is set.stringnoRunLocalTests
apex-testsComma-separated or multi-line list of Apex tests to run as "Class" or "Class.method". A selection always runs with RunSpecifiedTests. Leave empty to run the test-level.stringno-
packagesComma-separated or multi-line list of dependency packages (aliases or IDs) to install, e.g. "04t...,04t...". Leave empty to skip.stringno-
permission-setsComma-separated or multi-line list of permission sets to assign to the scratch org admin user before the tests run. Leave empty to skip.stringno-
permission-set-groupsComma-separated or multi-line list of permission set groups to assign to the scratch org admin user. Leave empty to skip.stringno-
permission-set-licensesComma-separated or multi-line list of permission set licenses to assign to the scratch org admin user. Leave empty to skip.stringno-
apex-file-pathComma-separated anonymous Apex file(s) or glob(s) to execute before the tests, e.g. "./scripts/apex/setup/*.apex". Leave empty to skip.stringno-
deploy-agentsBring the Agentforce agents found in source-dir to the org after the deployment - publish and activate them, then deploy their tests. The scratch org definition has to enable Agentforce. A project without agents skips this.booleannotrue
activate-agentsActivate the agent versions after publishing. Set to false to leave the currently active versions in place.booleannotrue
agent-post-publish-dirComma-separated or multi-line list of source directories to deploy once the agents exist, e.g. permission sets granting access to an agent. Keep them outside of source-dir. Leave empty to skip.stringno-
agent-testsRun the agent tests of the project against the scratch org. Opt-in, because they consume Einstein Requests or Flex Credits and can change org data. Needs deploy-agents. A project without agent tests skips this.booleannofalse
agent-test-namesComma-separated or multi-line list of agent tests to run instead of all tests of the project. Leave empty to run all.stringno-

Secrets ​

SecretDescriptionRequired
SFDX_CONSUMER_KEYConsumer key (client ID) of the Dev Hub connected app used for the JWT flow.yes
SFDX_JWT_SECRET_KEYContents of the private server key (server.key) used for the JWT flow.yes
SFDX_USERNAMEUsername of the Dev Hub integration user to authenticate as.yes

Example usage ​

Copy this caller into your project's .github/workflows/ directory (source):

yaml
# Example: call the reusable scratch org CI workflow.
# Copy this file into your project's .github/workflows/ directory.

name: Scratch Org CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Least-privilege token: the called workflow only reads the repository and talks
# to Salesforce. A reusable workflow can never get more permissions than the
# caller grants here.
permissions:
  contents: read

jobs:
  scratch-org-ci:
    uses: svierk/salesforce-devops-starter-kit/.github/workflows/scratch-org-ci.yml@v1.8.0
    with:
      source-dir: force-app
      # Build what the deploy needs but Git does not hold, e.g. the UI bundles
      # of a Multi-Framework project - an npm script in your root package.json:
      # build-script: build:ui-bundles
      definition-file: config/project-scratch-def.json
      duration-days: '1'
      test-level: RunLocalTests
      # Run only a selection of Apex tests instead (implies RunSpecifiedTests):
      # apex-tests: AccountServiceTest,LeadServiceTest.testConversion
      # Optional dependency packages to install before deploying:
      # packages: '04t...,04t...'
      # Optional permissions and setup scripts applied before the tests run:
      # permission-sets: 'My_App_Admin'
      # apex-file-path: ./scripts/apex/setup/*.apex
    secrets:
      SFDX_CONSUMER_KEY: ${{ secrets.SFDX_CONSUMER_KEY }}
      SFDX_JWT_SECRET_KEY: ${{ secrets.SFDX_JWT_SECRET_KEY }}
      SFDX_USERNAME: ${{ secrets.SFDX_USERNAME }}

Released under the MIT License. · llms.txt for AI agents