Choose which runners an agent runs on

Declare labels on a runner and require them on an agent, so that sessions run on the right machines.

Agents and runners are not paired. A runner declares labels, an agent states requirements over them, and Blaise offers a session only to runner instances that satisfy them.

Declare labels on a runner

Add a labels mapping to the blaise.yml the runner starts with:

blaise.yml

version: 1
labels:
  os: linux
  pool: [build, gpu]
  site: ${{ env.RUNNER_SITE }}

A value is a string, or a list of strings; a string is the same as a list of one. Labels are read when listen starts and sent each time it connects, so change them and restart the runner. The configuration reference lists the limits.

Check what a machine declares with blaise-agent status.

Require labels on an agent

Open Settings → Agents and edit the agent, or create one.
Under Runner requirements, choose Add requirement.
Enter the label name and the values it must include. Separate several values with commas.
Save.

The form shows how many online instances satisfy the requirements before you save.

How a requirement is read

Every requirement must hold: they are combined with AND.
For one label, the runner's values must include every value you list. A requirement pool: gpu is met by pool: [build, gpu]. A requirement pool: [build, gpu] needs both.
Only values are compared, exactly: there is no wildcard and no negation.
An agent without requirements runs on any runner of its workspace.

Common patterns

You want	Runner labels	Agent requirements
An agent that needs a GPU	`gpu: "true"`	`gpu: "true"`
Production work only on the CI machines	`env: ci`	`env: ci`
A repository that only one machine can see	`repos: [web, api]`	`repos: web`
Linux build machines in one site	`os: linux`, `site: eu-west`	both of those keys

Check why a session waits

A session that no online instance can serve shows Waiting for a runner and names the values that are missing. If it says no runner is online, start blaise-agent listen; if it says no instance matches, add the label to a runner, or relax the requirement.

Revoking and counting runners

Settings → Runners lists every registered runner with its instances. Revoke a runner there to invalidate its token. To add capacity under one authorization, start another listen process with the same token; it counts as another instance of the same runner.