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 arunaction is encountered, no further preflight options are processed.pass,pass-secret, andpass-hidden: will return a pass outcome without running the checklet.fail,fail-secret, andfail-hidden: will return a fail outcome without running the checklet.skipandskip-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:
pass-secretandfail-secretwill also add a secret property with valueTrue.pass-hiddenandfail-hiddenwill add secret and hidden properties with valueTrue.skipandskip-erroradds a skipped property with valueTrue.skip-erroradditionally adds a deps-error property with valueTrue.
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.*] => 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.