Learn · Dependencies and flow control

Steps that never ran

Two things decide whether a step runs: its dependencies, and its conditions.

Branch filters restrict a step to particular branches:

  - key: deploy
    branches: "main"
    command: make deploy

if conditions are more general, and can look at anything in the build’s context:

  - command: make deploy
    if: build.branch == "main" && build.source != "schedule"

Use branches for the simple case and if when the rule involves more than the branch name. They are not interchangeable — branches is a filter applied to the branch, if is an expression evaluated against the whole build.

Reading a step that did not run

This is where people misdiagnose builds. Buildkite distinguishes:

• failed — the job ran and its command exited non-zero
• broken — the job never ran at all

A broken job means something prevented execution: an if evaluated false, a branch filter did not match, or a step it depended on failed. Nothing was executed, so there are no logs to read and nothing in the command to fix.

When someone reports “the deploy failed” and the job is broken, the deploy did not fail. Look at the condition or the upstream dependency instead — it will save you an hour of reading logs that do not exist.