# Choose Runners for Workflow Jobs (https://www.shipfox.io/docs/how-to/author-workflows/choose-runners)

Description: 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 [#before-you-begin]

Use the [hosted runner reference](https://www.shipfox.io/docs/reference/runner-labels) for Shipfox Cloud.
For a runner you manage, you also need access to its process or provisioner
template.

## Match a workflow to a runner [#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](https://www.shipfox.io/docs/reference/runner-labels#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
# 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 -a
```

### Override 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 [#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:

1. Confirm the runner is online and polling the same workspace.
2. Confirm its configured labels include every label required by the job.
3. Confirm the runner has capacity for another job.
4. 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](https://www.shipfox.io/docs/operations/runners) for registration and the [Runner
reference](https://www.shipfox.io/docs/reference/runner) for label configuration.