Choose Runners for Workflow Jobs
Match job labels with runners, change the runner for selected jobs, and resolve a job that stays pending.
Runner labels describe where a job can run. A runner must have every label the job needs.
Before you begin
Use the hosted runner reference for Shipfox Cloud. For a runner you manage, you also need access to its process or provisioner template.
Match a workflow to a runner
Find the runner's labels
Use shipfox for the default Shipfox-hosted runner. To choose a different size,
compare the available runners.
For a runner you manage, check SHIPFOX_RUNNER_LABELS in the runner process
or its matching provisioner template. The dashboard does not list online
runner labels yet.
Set the workflow default
Set the top-level runner field. This is a complete workflow using the
default Shipfox-hosted runner:
# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Verify on Linux
runner: shipfox
triggers:
manual:
source: manual
jobs:
verify:
steps:
- key: platform
run: uname -aOverride one job when needed
A job-level runner value replaces the workflow default. For example, add
runner: shipfox-8cpu to a build job that needs more capacity.
For a runner you manage, the value can be a list such as [linux, gpu].
One runner must have the full set.
Run and verify the job
Commit and push the file to the project's default branch. Start it from the
Workflows tab. The job leaves pending after a matching runner claims
it.
Resolve a pending job
A job can remain pending while it waits for dependencies or for a compatible runner. Use these checks after its dependencies have finished.
Open the run, select the pending job, and note its runner labels. The job may inherit labels from the workflow or the Shipfox instance default.
Check the runner process that should claim it:
- Confirm the runner is online and polling the same workspace.
- Confirm its configured labels include every label required by the job.
- Confirm the runner has capacity for another job.
- Check its log for registration, authentication, or polling errors.
Start or repair a matching runner. The pending job is claimed automatically.
You do not need to start another run. Confirm that the job leaves pending,
starts an execution, and streams step logs from the matching runner.
See Start a runner for registration and the Runner reference for label configuration.