Targeting a queue

A step says where it wants to run with the agents attribute:

steps:
  - command: make test
    agents:
      queue: "linux-medium-x86"

You can also set a default for the whole pipeline at the root of the file:

agents:
  queue: "linux-small"

steps:
  - command: make lint          # runs on linux-small

  - key: package
    command: make package
    agents:
      queue: "linux-large"      # overrides the default

Step-level targeting wins over the root-level default. That is the whole mechanism: set the common case once at the root, override the exceptions.

Within a queue, a step runs on the first available agent, ordered by how recently an agent in that queue successfully completed a job.

The failure mode to recognise

A step that targets a queue with no agents in it does not error. It waits.

Nothing is misconfigured from Buildkite’s point of view — a job is queued and no agent has claimed it. It looks exactly like a capacity shortage, and it will keep looking like one until somebody checks whether that queue has any agents at all.

A typo in a queue name produces this, silently, and it is one of the first things to check when a pipeline that used to run stops running. The queue named in the step and the queue tag on the agent have to match exactly.

Check

Write a pipeline whose steps run on the `linux-small` queue by default, containing one command step keyed `package` that runs `make package` on the `linux-large` queue instead.