Skip to main content

Test and validate Courier jobs with Courier Runner

This guide explains how to run and validate a Courier job directly with Courier Runner, bypassing the Chef 360 Platform job scheduler. Normally, Chef 360 Platform dispatches jobs to Courier Runner after you submit them through the web UI, the chef-courier-cli, or the API; use zero mode to execute a job locally for testing or CI/CD, and dry-run mode to validate a job template before you run it.

Before you begin

Before you can run courier-runner, you must install it on your system:

To install the courier-runner Habitat package, install it through Chef Habitat:

  • Install the package:

    hab pkg install chef-platform/courier-runner

  • Install the package and add the courier-runner binary to your system’s PATH:

    hab pkg install chef-platform/courier-runner --binlink

Note

The examples in this documentation assume that the package has been binlinked and the executable is available on your system PATH. If not, run commands through Habitat:

hab pkg exec chef/courier-runner courier-runner <COMMAND>

Test a Courier job locally

Use zero mode to execute a Courier job locally on a node without connecting to a message queue or Chef 360 Platform. In zero mode, Courier Runner executes each step of a Courier job using local skill interpreters, and writes detailed execution reports and files to the local filesystem.

To execute a Courier job in zero mode, follow these steps:

  1. Create a JSON Courier job template file.

  2. Run courier-runner with the --zero and --job-file flags:

    courier-runner --zero --job-file <COURIER_JOB_FILE>

    To specify a custom directory for reports, use the --output-dir <OUTPUT_DIRECTORY> option.

  3. Review the contents of the Courier job run directory. By default, Courier Runner writes execution reports to ~/.courier/zero-mode/runs/<RUN_ID>/.

    The output directory contains the following files:

    job.json : Contains the overall job execution status, start and completion timestamps, and run metadata.

    step-<STEP_NUMBER>-<ATTEMPT_NUMBER>.json : Contains detailed status for a specific step and attempt number. Step statuses include active, success, failure, skipped, and abandoned. The report includes execution timing, extracted outputs, and error details if the step failed.

    For each step attempt, Courier Runner generates an evidence directory named <JOB_ID>_<STEP_NUMBER>_<ATTEMPT_NUMBER>/ containing:

    rawInterpreterOutput : The complete, unescaped standard output stream produced by the interpreter during step execution.

    rawInterpreterError : The complete standard error stream produced by the interpreter.

    extracted output files : Any individual files or artifacts captured by the step’s outputFieldRules definition.

    <JOB_ID>_<STEP_NUMBER>_<ATTEMPT_NUMBER>.txt : A copy of the step execution report for local inspection.

    Note

    If a step definition marks an input or output field as sensitive ("sensitive": true in expectedInputs or outputFieldRules), Courier Runner redacts that value in all generated step-*.json report files with the text ************** (sensitive info).

    Redaction doesn’t apply to raw interpreter captures: rawInterpreterOutput and rawInterpreterError always contain the complete, original console output, including any values marked as sensitive. To limit exposure, Courier Runner restricts run output folder permissions to 0700, so only the user account that ran the job can read the evidence files.

Validate a Courier job with dry-run mode

Dry-run mode validates a Courier job against the local system without executing any commands or saving database records. It performs pre-flight checks on template syntax, interpreter availability, condition expressions, and cross-step data dependencies.

To validate a Courier job, follow these steps:

  1. Create a JSON Courier job template file.

  2. Run courier-runner with the --zero, --dry-run, and --job-file flags:

    courier-runner --zero --dry-run --job-file <COURIER_JOB_FILE>

    When Courier Runner runs in dry-run mode, it performs the following checks:

    • Template syntax

      Validates that the JSON template matches the Courier job specification and includes at least one executable step.

    • Interpreter availability

      Checks that every interpreter referenced in the job steps exists on the host, using the configured paths in ~/.courier/config.yaml and the local Habitat package repository.

    • Condition syntax

      Validates that step conditions use valid comparison operators and expressions.

    • Cross-step data dependencies

      Inspects inputs marked as required in subsequent steps (expectedInputs) and verifies that a preceding step declares a matching outputFieldRules rule to supply that value. If a required input isn’t explicitly supplied by a preceding step, Courier Runner displays a warning.

  3. Review the report returned to the standard output.

    The report lists each step and marks every check it ran against that step with one of the following statuses:

    • OK: The check passed.
    • WARN: The check passed, but found a potential runtime issue, such as a cross-step input that no preceding step explicitly provides.
    • ERROR: The check failed, such as when a required interpreter isn’t available or a condition expression is invalid.

    The report ends with a Result line that summarizes the overall outcome as OK, OK (<N> warning(s)), or FAILED (<N> error(s)).

Note

Dry-run mode returns standard exit codes:

  • Exit code 0: The job template is valid (may contain warnings).
  • Non-zero exit code: Validation failed due to missing interpreters, invalid condition rules, or missing required step 0 inputs.

See also

Thank you for your feedback!

×