Checkpoint packages
Mark packages whose deployment must succeed for a prepared scratch org to be kept in the pool.
A checkpoint package is a package whose deployment must succeed for prepare to keep a scratch org in the pool. It is a per-package setting read from sfdx-project.json during prepare, not a property of the pool definition.
Marking a package as a checkpoint
Set checkpointForPrepare to true on the package directory in sfdx-project.json.
| Attribute | Type | Description |
|---|---|---|
| checkpointForPrepare | boolean | During prepare, the scratch org is kept only if a checkpoint package deploys. Default false |
{
"packageDirectories": [
{
"path": "core-crm",
"package": "core-crm",
"versionNumber": "4.7.0.NEXT",
"checkpointForPrepare": true
},
{
"path": "feature-billing",
"package": "feature-billing",
"versionNumber": "1.2.0.NEXT"
}
]
}More than one package can be marked. Prepare collects every package directory carrying checkpointForPrepare: true and logs Fetching checkpoints for prepare if any..... while it does so.
Behaviour during prepare
Checkpoint packages refine what happens when a package fails to deploy while an org is being prepared. The outcome depends on succeedOnDeploymentErrors (see Defining a pool).
succeedOnDeploymentErrors | Checkpoint packages defined | Deployment has a failure |
|---|---|---|
true (default) | no | Org is kept with whatever deployed (a partial org) |
true (default) | yes | Org is kept only if at least one checkpoint package deployed; otherwise the org is deleted |
false | any | Org is deleted on any failure — checkpoint packages add nothing |
When the deployment has no failures, checkpoint packages have no effect — the org is added to the pool as usual.
When succeedOnDeploymentErrors is true, prepare keeps an org even if some packages failed. Checkpoint packages narrow that: an org is kept after a failure only when at least one checkpoint package deployed. If none of the checkpoint packages deployed, the org is deleted instead of being added to the pool, even though succeedOnDeploymentErrors would otherwise have kept it.
Every org deleted because no checkpoint package deployed is counted by the sfpowerscripts.prepare.org.checkpointfailed metric. See Available metrics.