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.