Preparing pools

Preparing a pool builds a set of scratch orgs upfront, each one already carrying the managed package dependencies and the packages in your repository. A scratch org taken from a prepared pool is ready for use immediately, whether it is being used as a just-in-time environment for validation or as a developer environment.

As more third-party managed packages and configuration metadata enter a repository, the setup time for a fresh scratch org grows — package installs, data loading scripts, permission set assignments. Preparing a pool moves that cost off the critical path.

Running prepare

The pool definition is stored on sfp server (see Defining a pool). Prepare reads it by repository and tag:

sfp server pool scratch init -p ci -r flxbl-io/sf-core

The command answers to the aliases sfp prepare, sfp pool prepare, sfp pool scratch prepare and sfp pool scratch init.

------------------------------------------------------------------------------------------
sfp-pro  -- ❤️ by flxbl.io ❤️ -Version:51.0.0 -Release:NOV 25 -Build:399 -Docker:51.0.0
------------------------------------------------------------------------------------------
Command  : sfp server pool scratch init --tag=ci --repository=flxbl-io/sf-core --loglevel=info
------------------------------------------------------------------------------------------
command: prepare
Pool Name: flxbl-io-scratch-ci-test-to-delete-1
Requested Count of Orgs: 6
Scratch Orgs to be submitted to pool in case of failures: true
All packages in the repo to be installed: true
Enable Source Tracking: true
Fetch artifacts from pre-authenticated NPM registry: true
------------------------------------------------------------------------------------------
Validating Org Authentication Mechanism..
Fetching Artifacts
Fetching checkpoints for prepare if any.....
Computing Allocation..

Current Allocation of ScratchOrgs in the pool flxbl-io-scratch-ci-test-to-delete-1: 2
Remaining Active scratchOrgs in the org: 10
ScratchOrgs to be allocated: 4
Generate Scratch Orgs..
Waiting for all scratch org request to complete, Please wait
Requesting Scratch Org SO1..

Steps undertaken by the prepare command

Setting up

1. Read the pool definition from the server for the given repository and tag.
2. Check out the branch the pool targets into a worktree. Artifacts, scripts, sfdx-project.json and the scratch org definition are all read from that worktree, not from the working directory the command was launched in.
3. Resolve the artifact source — the server's internal registry, an NPM registry the server issues credentials for, or a custom fetch script, as configured by fetchArtifacts.
4. Resolve the Dev Hub named in the pool configuration and verify its authentication. The Dev Hub must hold a valid SFDX auth URL or access token; a Dev Hub authenticated another way is rejected. No pooling metadata is required on the Dev Hub — see Setting up your Salesforce org for scratch org pools.

Building the artifact set

5. Determine which packages to install. A releaseConfigFile narrows the set to the packages in that release configuration, plus their cross-domain dependencies. A package carrying "ignoreOnStage": ["prepare"] is excluded.
6. Fetch the artifacts from the configured registry, resolving each package's version from its latest git tag. If fetchArtifacts is not configured, the packages are built from the head of the branch instead.
7. Read checkpoints. A package marked "checkpointForPrepare": true in sfdx-project.json becomes a checkpoint: if succeedOnDeploymentErrors is set, an org is only kept when at least one checkpoint package deployed successfully. See Checkpoint packages.
8. Resolve external package dependencies to concrete versions from sfdx-project.json.

Creating the orgs

9. Compute the allocation from the requested capacity, the pool's current instances on sfp server, and the Dev Hub's remaining scratch org limit.
10. Create the scratch orgs in parallel, in batches of batchSize and within waitTime, and register each org with sfp server as PROVISIONING, credentials included. The registration is authoritative: an org that cannot be registered is deleted rather than left untracked. The scratch org definition's description is stamped with the pool tag for attribution on the Dev Hub side.

Preparing each org

11. On each scratch org, in parallel:

    • Relax IP ranges, if relaxAllIPRanges or ipRangesToBeRelaxed is configured.
    • Install the sfpowerscripts artifact package (04t1P000000ka9mQAA), which records the packages installed in the org. Set the SFPOWERSCRIPTS_ARTIFACT_PACKAGE environment variable to install your own build of it; the source is available here.
    • Run preDependencyInstallationScriptPath, if configured. See Lifecycle scripts.
    • Install the managed package dependencies declared in sfdx-project.json.
    • Apply Vlocity configuration, if enableVlocity is set.
    • Install all the artifacts that were fetched or built.
    • Run postDeploymentScriptPath, if configured. It receives the deployment status as its third parameter.

12. Mark each completed org AVAILABLE on sfp server — the authoritative hand-off into the pool. An org whose preparation failed, or that the server could not mark available, is deleted from the Dev Hub — unless the failure was a package deployment error and succeedOnDeploymentErrors is set.