Title: GitHub Actions waiting for a runner to pick up job
URL: https://codemany.com/problems/github-actions-waiting-for-runner
Description: GitHub Actions waiting for a runner to pick up this job? Check labels, runner groups, repo access and busy machines. Fix each cause in a few minutes.
All pages as Markdown: https://codemany.com/llms.txt

---

[Home](https://codemany.com/) › [Problems](https://codemany.com/problems)

# "Waiting for a runner to pick up this job"

This message means no online runner can take the job right now. Most often the `runs-on` labels don't match; other causes are repo access, busy runners or an offline machine.

## The short answer

When GitHub Actions is waiting for a runner, it is looking for one that is online, free, allowed to see the repo, and has every label in `runs-on`. If no runner fits all four, the job waits. Check them in the order below.

## Labels do not match

GitHub gives a job only to a runner that has every label in `runs-on`. One typo, and the job waits forever:

```
# waits: no runner has the label "codemay"
runs-on: [self-hosted, codemay]

# runs
runs-on: [self-hosted, codemany]
```

Compare your labels with Settings › Actions › Runners. Each extra label narrows which runners can take the job. Codemany's labels are listed in [Runner labels](https://codemany.com/docs/advanced#labels).

Labels of GitHub-hosted runners, such as `ubuntu-latest`, never match a self-hosted runner. Don't mix them in one `runs-on`.

## The runner cannot see the repo

A runner added to one repo only serves that repo. Organization runners live in runner groups, and a group can be limited to some repos. Public repos are kept out of groups unless you allow them. Check Organization settings › Actions › Runner groups. Also check that the runner was added in the right place: the repo, or the organization that owns it.

## All runners are busy

Each runner runs one job at a time. A [matrix build](https://codemany.com/articles/github-actions-matrix) can start many jobs at once, and a GitHub self-hosted runner queue grows fast. In Settings › Actions › Runners, each runner shows Idle, Active or Offline. If all are Active, add runners, or limit the matrix:

```
strategy:
  max-parallel: 2
  matrix:
    node: [20, 22, 24]
```

On Codemany, each machine runs as many jobs as it has room for. See [how many jobs per machine](https://codemany.com/docs/machines#size).

## The machine is offline

If the runner shows Offline, no job can reach it. Work through [the offline runner checks](https://codemany.com/problems/self-hosted-runner-offline). A Mac that sleeps goes offline too. Codemany keeps the Mac awake while jobs run.

## How Codemany matches jobs

Every Codemany runner carries `self-hosted` and `codemany`. GitHub's runner adds the system and CPU labels, such as `macOS`, `Linux`, `ARM64` or `X64`. Codemany adds tool labels when the tool is there: `xcode`, a version like `xcode-26.0`, and `docker`.

```
runs-on: [self-hosted, Linux, codemany]
```

Each repo keeps a warm runner while there are spares. Idle runners move to repos with waiting jobs. Codemany sizes each machine: about 4 GB of memory, 2 cores and 15 GB of disk per job. [Codemany Console](https://codemany.com/features/fleet-view) shows every machine, and you can change how many jobs one runs at once. Public repos stay off until you turn them on, so a public repo's job waits until then.

A job that asks for a tool label waits for a machine with that tool. The `docker` label, for example, is there only while Docker runs. Start the tool, or drop the label.

## Questions

### Why is my job queued forever?

Usually its runs-on labels match no online runner.

### Which labels does Codemany use?

self-hosted and codemany, plus tool labels it adds such as docker.

### How many jobs can one machine run?

Codemany sizes it to the machine: an 8 GB Mac runs 1 job at a time, a 16 GB Mac runs 3. You can change it in Codemany Console.

## Related

Read next: [runner labels](https://codemany.com/docs/advanced#labels), [jobs per machine](https://codemany.com/docs/machines#size), [runner offline](https://codemany.com/problems/self-hosted-runner-offline) and [the fleet view](https://codemany.com/features/fleet-view).

[Start a 14-day trial](https://codemany.com/docs/get-started) $20 a month for 2 machines. No card needed.