Scheduler preflight option

The preflight@scheduler option is processed by the scheduler during the scheduling of the tasks. The option allows recipes to indicate situations in which the task does not have to be executed, for example when an input precondition fails.

Checklets support this scheduler option without declaring it in their metadata. Preflight checks run in the order returned by the option definition, including config, recipe, and step options. The first matching check determines the action.

The expected format for the option value is:

preflight_option ::= [ match ] "=>" action [ preflight_status | preflight_props ]
preflight_status ::= text status message
preflight_props  ::= JSON object containing result properties
action           ::= "run" | "pass" | "pass-secret" | "pass-hidden"
                     | "fail" | "fail-secret" | "fail-hidden" | "skip"
                     | "error" | "skip-error"

If a selector matches or is empty, a results bundle based on the action and status message is created (unless the action is run). If no selectors match, or a selector matches with action run, no result is created and the step should execute as normal.

Possible values for action are:

  • run: runs the checklet. When a run action is encountered, no further preflight options are processed.

  • pass, pass-secret, and pass-hidden: will return a pass outcome without running the checklet.

  • fail, fail-secret, and fail-hidden: will return a fail outcome without running the checklet.

  • skip and skip-error: will return a skip outcome without running the checklet.

  • error: will return an error outcome without running the checklet.

A generated result contains a preflight-trigger property with the complete matched rule, and a source property with the name of the preflight module. If status is provided and does not start with a {, a status property with the status message is added. If status starts with a {, it is parsed as a (json style) dictionary of properties and added to the result properties.

Some of the actions will add additional properties to the result:

The default preflight check is:

%any error => skip-error

The scheduler inserts this check before user-defined checks unless a rule uses an error reference, such as %any error[#evaluate.*]. A not-error reference or result=="error" does not suppress the default check.

The default checks every result in the supplied results bundle. The bundle can include dependencies of dependencies. Preflight does not restrict references to the current step’s direct dependencies.

Restrict a rule to selected results

The following step fragment skips the summary only when all available evaluate.* results are skipped:

<step id="summary">
  <checklet ref="stepreport-chk" />
  <dependencies>
    <depends step="evaluate.*" />
  </dependencies>
  <options domain="scheduler">
    <option name="preflight" value="%all skip[#evaluate.*] =&gt; skip" />
  </options>
</step>

%all skip also checks other results present in the bundle. Listing evaluate.* in <dependencies> does not limit the selector. See Result reference scope for an example with a build result.

The explicit skip rule above still runs after the default error check. An error anywhere in the supplied results bundle therefore triggers skip-error first. A rule with an explicit error reference suppresses that default when a recipe needs a different error policy.

A match with no selected results is false for %all and %any. A result id filter does not verify that all expected task results are present.

Status properties

A status string supports reference placeholders. A status that starts with { must be a JSON object. Invalid JSON emits a warning and becomes a plain status property. Action properties override status properties, and preflight-trigger and source always describe the matched rule.

If no label property is supplied, the scheduler resolves the label option in the checklet domain and expands task id placeholders. Generated results also copy the current step’s options.