> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/environment-management/pools/scratch-org-pools/pool-operations/preparing-pools.md). # 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](/flxbl/sfp/environment-management/pools/scratch-org-pools/defining-a-pool.md)). Prepare reads it by repository and tag: ```bash 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](/flxbl/sfp/environment-management/pools/scratch-org-pools/setting-up-your-salesforce-org-for-scratch-org-pools.md). ### 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](/flxbl/sfp/environment-management/pools/scratch-org-pools/pool-operations/preparing-pools/checkpoint-packages.md). 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](https://github.com/dxatscale/sfpowerscripts-artifact). * **Run `preDependencyInstallationScriptPath`**, if configured. See [Lifecycle scripts](/flxbl/sfp/environment-management/pools/scratch-org-pools/defining-a-pool.md#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. {% hint style="info" %} Source tracking is enabled by default. Prepare deploys packages with `source:push` and persists source tracking files as sfpowerscripts artifacts. When an org is fetched from the pool, the tracking files are restored into the local `.sf` directory using the [@salesforce/source-tracking](https://github.com/forcedotcom/source-tracking) library, so a developer can deploy only their own changes. Set `enableSourceTracking` to false to turn this off. {% endhint %} {% hint style="warning" %} A lifecycle script that exits non-zero fails preparation for that scratch org and the org is deleted. `succeedOnDeploymentErrors` does not cover this — it applies to package deployment failures only. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp/environment-management/pools/scratch-org-pools/pool-operations/preparing-pools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.