Gitea Actions "runner labels do not match" (runs-on) in CI

By Kaveh Alemi·Latchkey

The runs-on value in your workflow names a label that no online act_runner advertises, so the scheduler has no runner to assign. Align the workflow label with a label the runner registered.

What this error means

A job waits with a message that no runner matches its label, while other jobs on different labels run fine. The Runners page shows runners online but with different labels than your runs-on.

no matching online runner for job with labels: [ubuntu-22.04]
runner labels [ubuntu-latest,self-hosted] do not match job labels [ubuntu-22.04]

Common causes

runs-on names a label the runner never registered

The runner advertises ubuntu-latest but the workflow requests ubuntu-22.04; labels are matched literally, so nothing picks it up.

The label was registered without a mapping image

A label like ubuntu-latest needs a :docker://image (or :host) mapping; a bare or mistyped label will not match cleanly.

How to fix it

Match runs-on to a registered label

1. List the labels your runner registered under Runners in Gitea.
2. Set runs-on in the workflow to exactly one of those labels.
3. Re-run the job and confirm the runner claims it.

jobs:
  build:
    runs-on: ubuntu-latest   # must equal a label the act_runner offers

Re-register the runner with the labels you need

Register (or edit config.yaml) so the runner advertises the labels your workflows use, each mapped to a docker image or the host.

act_runner register --no-interactive \
  --instance https://gitea.example.com --token <TOKEN> \
  --labels ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://ubuntu:22.04

How to prevent it

• Standardize on a small set of labels shared by workflows and runners.
• Document which labels each runner offers and their image mappings.
• Fail fast in review if a new workflow uses an unregistered label.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions