Pool definition file

A pool is described by one JSON object in config/project-<tag>-pool-def.json. org pool-prepare loads it (org-pool/lib/pool-definition.mjs) for the --tag it is given, or from the path passed as --config. No other command reads the file: org pool-fetch, org pool-list, org pool-cleanup, org pool-release and the pool claim inside org scratch-create work from the pool state on the DevHub's ScratchOrgInfo records and take the tag as a flag.

{
    "tag": "ci",
    "maxAllocation": 10,
    "maxOrgsPerRun": 4,
    "seedConcurrency": 4,
    "durationDays": 1,
    "configFilePath": "config/project-scratch-def.json",
    "succeedOnError": false,
    "seedScript": "config/scratch-org-setup/ci-pool-seed.mjs",
    "seedBaseline": "branch:master"
}

Keys

Key	Type	Required	Default	Meaning	Read by
tag	string	yes	—	The pool's name. Must be non-empty and equal the --tag the command was given (compared after lower-casing the flag). Stamped on each org's ScratchOrgInfo record and used by every pool command to select orgs.	org pool-prepare; the value itself by every org pool-* command
maxAllocation	integer	yes	—	Target size of the pool: the number of active orgs (available, allocated or in progress) the pool is topped up toward. --max <n> lowers it for one run.	org pool-prepare
maxOrgsPerRun	integer	no	5	Upper bound on the orgs one pool-prepare run creates. The run creates max(0, min(maxAllocation − active, maxOrgsPerRun, remaining DevHub scratch-org limit)) orgs.	org pool-prepare
seedConcurrency	integer	no	4	How many of the run's orgs are created and seeded at the same time. Each seeding runs in its own git worktree and child process.	org pool-prepare
durationDays	integer	no	2	Lifetime passed to sf org create scratch --duration-days for each pool org.	org pool-prepare
configFilePath	string	no	config/project-scratch-def.json	Scratch-org definition file passed to sf org create scratch --definition-file.	org pool-prepare
succeedOnError	boolean	no	true	true: a failed provisioning (creation or seed) deletes that org, is counted as failed, and the run continues with the rest of the batch; the run exits 1 only if no org was created. false: the first failure is re-thrown, ending the run with exit code 1 after the batch settles.	org pool-prepare
seedScript	string	no	— (orgs are pooled bare)	Repo-root-relative path of a module exporting async seed({ targetOrg, devHubConnection, targetOrgConnection, run }). Loading the definition fails (exit code 4) if the file does not exist; running the seed fails (exit code 4) if the module has no seed export. The hook runs once per new org between In Progress and Available; a throwing hook fails that org's provisioning.	org pool-prepare (via org-pool/lib/seed.mjs)
seedBaseline	string	no	— (no commit stamped)	Declares the commit the seed hook leaves the org's metadata at. Forms: tag (latest tag reachable from origin/master), branch:<name> (head of origin/<name>, fetched if absent), or any git revision. When set, the run resolves it to a SHA, compares it with the checkout's HEAD, logs a mismatch, and stamps HEAD on every org as Seeded_From_Commit__c. An unresolvable value, or an undeterminable HEAD, exits 4.	org pool-prepare (via org-pool/lib/seed-baseline.mjs)

Validation

The loader rejects, with exit code 4:

• a file that cannot be read or is not valid JSON, or whose top level is not an object;
• any key outside the ten listed above;
• a missing or empty tag, a missing or non-integer maxAllocation;
• a wrong type on any optional key (maxOrgsPerRun, seedConcurrency, durationDays must be integers; configFilePath, seedScript, seedBaseline non-empty strings; succeedOnError a boolean);
• a seedScript path that does not exist;
• a tag that differs from the requested tag.

Missing optional keys are filled from the defaults above; the result is the definition the run uses.

Effect on claim time

The stamped Seeded_From_Commit__c is the only definition-derived value a claim sees. org scratch-create --use-pool reads it from the claimed org; when it is set and DELTA_DEPLOY_SCRATCH is on, the claim deploys the delta from that commit to HEAD instead of the full push. See pooled delta validation and how to maintain the scratch org pool.