Learn · Failure handling

Soft failures and stopping early

Soft failures

soft_fail lets a step fail without failing the build:

steps:
  - command: make lint
    soft_fail: true

The distinction that matters: the step is still marked as failed. You can see it, it is red, the information is not lost. What changes is that the build as a whole is not failed by it.

This is not the same as a passing step, and treating it as one is how a linter quietly stops being enforced. soft_fail is right for genuinely advisory checks. If nobody looks at the red step, you have not made the check advisory — you have deleted it.

You can soft-fail selectively by exit status:

    soft_fail:
      - exit_status: 2

Stopping a doomed build

By default, when a step fails the rest of the build keeps going. Sometimes that is what you want — you would rather see all the failures at once. Often it is not, especially when a hundred parallel jobs are about to run for twenty minutes to tell you what you already know.

cancel_on_build_failing opts a step out of that:

  - command: make slow-thing
    cancel_on_build_failing: true

Now if the build is already failing, this step is cancelled rather than started.

On a large fan-out this is one of the cheapest savings available: the work is already known to be wasted, and cancelling it costs nothing but a line of configuration.