Skip to content

How to validate a pull request against a scratch org

Turn on the Validate against Scratch step for a stage's pull requests, optionally backed by a pool. For how pooling and the validation step work, see scratch org pooling.

Prerequisites

Turn on validation

  1. Add a repository variable for the stage whose PRs you want validated:

    SCRATCH_ORG_VALIDATION_<NAME> = true

    SCRATCH_ORG_VALIDATION_SIT=true covers pull requests targeting develop, which maps to SIT.

  2. Open a pull request and watch the Validate against Scratch step: it creates a scratch org, deploys the PR metadata into it, and runs the Apex tests.

Speed it up with a pool (optional)

  1. Make the DevHub pooling-ready, once:

    npm run org:pool:activate -- --target-org <devhub>

  2. Keep a pool topped up — maintain the pool.

An empty pool falls back to creating a fresh org, so validation itself is unchanged (how a pool works).

Make it a delta validation (optional, needs a pool)

  1. Give the pool definition a seedBaseline (pool definition file).

  2. Add the repository variable:

    DELTA_DEPLOY_SCRATCH = true

Validation then deploys only the diff from the org's seed commit to the PR head. What that includes, when the pipeline skips its separate test run, and how to read a red run are in pooled delta validation.

Skip pull requests that touch no metadata (optional)

Add the repository variable SCRATCH_ORG_VALIDATION_SKIP_WITHOUT_METADATA = true; the step then skips PRs that change neither force-app nor .forceignore. The kill switch DISABLE_SCRATCH_ORG_VALIDATION and the other variables are in the environment variable reference; how the step's gate evaluates them is in how the validation step decides to run.