Route builds with runner labels

Send a pipeline’s builds to the runners that can build it, such as the Mac with Xcode 16 or the Mac reserved for release builds. Each runner advertises labels, and a build goes only to a runner that has every label the pipeline asks for.

Label rules, the detected labels, and the disk-space thresholds are listed in Runner settings.

What you need

• At least one runner that is online in Settings > Runners.
• Owner or Admin access to change a runner’s custom labels.
• Project developer, maintainer, instance admin, or instance owner access to edit the pipeline.

1. See the labels a runner has

Open Settings > Runners. The Labels column shows each runner’s labels. Every runner reports detected labels such as macos, macos-15, xcode-16, and arm64. They update on the next heartbeat after a macOS or Xcode upgrade.

If the detected labels already tell your runners apart, skip to step 3.

2. Add custom labels

1. In Settings > Runners, open the runner’s actions menu and select Edit.
2. In Custom labels, enter labels separated by commas, such as release, gpu. Use lowercase letters, digits, ., _, and -.
3. Select Save changes.

The dialog lists the runner’s detected labels under the field. Custom labels are added to them, not put in their place.

To label a runner when you register it by hand, pass --label to oore runner register.

3. Set the labels on the pipeline

1. Open the pipeline and select Edit.
2. Under Build > Runner, enter the labels in Runner labels (optional), separated by commas, such as macos, xcode-16. The field description lists the labels that connected runners report.
3. Select Save changes.

An empty field means macos.

If the repository has a .oore.yaml with runs_on, set the same labels in both places. The scheduler reads only the pipeline’s labels. The runner checks the file’s runs_on after checkout and fails the build before any command runs when it lacks one of those labels.

Verify the result

1. Start a build of the pipeline.
2. Open the build. It runs on a runner that has every label you set.

While no online runner has the labels, the build stays queued, and Settings > Runners counts it under the builds that need labels no online runner has.

Troubleshooting

The build stays queued

No online runner has every label. Compare the pipeline’s Runner labels (optional) with the Labels column in Settings > Runners. A typo, or a detected label that changed after an Xcode upgrade, such as xcode-16 becoming xcode-26, leaves the build waiting.

The build fails right after checkout

The repository’s .oore.yaml asks for a label that the claiming runner lacks. Add the label to the pipeline as well, so the scheduler picks a runner that has it.

Oore rejects the custom labels

A label uses a character outside a–z, 0–9, ., _, and -, is longer than 64 characters, or the runner has more than 32 labels.

Edit is missing from the runner’s actions

Only Owners and Admins can edit runners.

Next step

Run builds in VMs when builds need a clean machine, or a Flutter version the host does not have.