Wait step

A wait step waits for all previous steps to have successfully completed before allowing following jobs to continue.

A wait step can be defined in your pipeline settings, or in your pipeline.yml file. It can be placed between steps to ensure that previous steps are successful before continuing to run the rest.

pipeline.yml
- command: "command.sh"
- wait: ~
- command: "echo The command passed"

Optional attributes:

continue_on_failure Run the next step, even if the previous step has failed.
Example: true
if A boolean expression that omits the step when false. See Using conditionals for supported expressions.
Example: build.message != "skip me"
depends_on A list of step keys that this step depends on. This step will only proceed after the named steps have completed. See managing step dependencies for more information.
Example: "test-suite"
allow_dependency_failure Whether to continue to proceed past this step if any of the steps named in the depends_on attribute fail.
Default: false

Conditional wait

You can use a conditional to only wait when certain conditions are met:

steps:
  - wait: ~
    if: build.branch == "develop" || build.branch == "main"

Continuing on failure

You can also configure the wait step to continue even if the previous steps failed. If steps failed, the build will be marked as failed only after any steps after the wait with continue_on_failure: true have completed.

This is useful for processing results from previous steps, for example, test coverage or summarizing test failures. Successful steps that run after a continue_on_failure step will not affect the status of the build; if there has been a failure, the build will be marked as failed.

In the example below, if command.sh succeeds, both of the following command steps will be run. If command.sh fails, only the first will be run, and the build will then be marked as failed.

steps:
  - command: "command.sh"
  - wait: ~
    continue_on_failure: true
  - command: "echo This runs regardless of the success or failure"
  - wait: ~
  - command: "echo The command passed"

If there's a failure followed by a regular wait step, nothing after the wait step will run, including any subsequent wait steps with continue_on_failure: true. In the example below, when the first command fails, the second and third commands will not run:

pipeline.yml
steps:
  - command: "exit -1"
  - wait: ~
  - command: "echo SECOND command"
  - wait: ~
    continue_on_failure: true
  - command: "echo THIRD command"
Screenshot of a failed pipeline which didn't run the continue_on_failure wait steps

Any wait steps with continue_on_failure: true that aren't separated by regular wait steps will all run if a failure occurs. In the below example, after the first command fails, the second, third, and fourth commands will all run:

pipeline.yml
steps:
  - command: "exit -1"
  - wait: ~
    continue_on_failure: true
  - command: "echo SECOND command"
  - command: "echo THIRD command"
  - wait: ~
    continue_on_failure: true
  - command: "echo FOURTH command"
Screenshot of a failed pipeline which did run the continue_on_failure wait steps

The explicit null ~ character used in the above examples isn't required, but is recommended as a best practice. It ensures that nothing else is accidentally added to the wait before the continue_on_failure attribute.

Continuing after cancelation

The continue_on_failure attribute enables builds to continue after a failed job but not after a cancelation. If you cancel a job, any subsequent wait steps with continue_on_failure: true do not execute.

For example, if you cancel the first command, the second command doesn't run in the following plugin.yml file:

steps:
  - command: "run-first-command.sh"
  - wait: ~
    continue_on_failure: true
  - command: "run-second-command.sh"

Block steps interacting with wait steps

If a block step follows or precedes a wait step in your build, the wait step will be ignored and only the block step will run, like in this example:

pipeline.yml
steps:
  - command: ".buildkite/steps/yarn"
  - wait: ~
  - block: "unblock me"

But let's consider a different example. Now the wait step (with continue_on_failure: true) will be ignored, but the block step will also not run, because the 'previous' command step failed.

pipeline.yml
steps:
  - command: "exit -1"
  - wait: ~
    continue_on_failure: true
  - block: "unblock me"

If you need to run a block step after a failed step, set soft_fail on the failing step:

pipeline.yml
steps:
  - command: "exit -1"
    soft_fail:
      - exit_status: "*"
  - block: "unblock me"

Alternatively, it is possible to use a wait step with a block step if conditionals are used. In these cases, the wait step must come before the block step:

pipeline.yml
steps:
  - command: ".buildkite/steps/yarn"
  - wait:
    if: build.source == "schedule"
  - block: "Deploy changes?"
    if: build.branch == pipeline.default_branch && build.source != "schedule"
  - command: ".buildkite/scripts/deploy"
    if: build.branch == pipeline.default_branch