Workload targeting

Stacks, deployments, and workflow templates choose how work finds a runner. The Runners page only registers and organizes agents; targeting lives on the workload.

◎

Strategies

Strategy What you set Scheduler behavior
automatic Nothing required Best available self-hosted runner in scope; hosted fleet if axio-\* labels require it
runner-group Group name Only runners in that group (still must be online, in scope, and have capacity)
specific-runner Runner name Pin to one agent
labels Customer or hosted labels All listed labels must match
provider-runner Hosted label such as axio-linux Shared Axio fleet only (subscription required)
⚙

Preference

Controls whether the scheduler considers self-hosted or provider runners.

Preference Behavior
customer Self-hosted only
provider Shared Axio fleet only
automatic Self-hosted first; hosted if axio-\* labels are present
i

runnerPreference: provider is set automatically when hosted labels are present.

⌘

Scope chain

For customer-hosted work, the scheduler walks environment → project → organization and only considers runners whose group scope covers that resource.

◆
Environment Runners in groups scoped to this environment
↓
■
Project Runners in groups scoped to this project
↓
▦
Organization Runners in groups scoped to this organization
i

A workspace-scoped group is not used by another workspace. An organization-scoped group is eligible everywhere in the org (subject to labels and capacity).

✓

Eligibility checklist

A runner can take a job only if all of these are true:

  1. Effective status is ONLINE (heartbeat ≤ 90 seconds)
  2. Not paused, draining, disabled, or in maintenance
  3. Has a free job slot activeJobs \< maxConcurrentJobs
  4. Labels match
  5. Group / scope covers the workload
  6. Version is not BLOCKED
  7. For hosted labels: tenant plan has providerRunnerAccessEnabled and the fleet has capacity
ϟ

AUTO_SELECT

Some APIs expose AUTO_SELECT as “best available runner” — same idea as strategy: automatic.

!

When no runner matches

Deployment/workflow logs typically show:

  • No runner is available
  • No hosted runner available for label "axio-linux"
  • IaC CLI missing on the assigned runner

See troubleshooting and IaC requirements