actionlint.yaml: Configure Custom Runners
actionlint reads .github/actionlint.yaml to learn custom runner labels and configuration variable names so it stops flagging them as unknown.
Out of the box actionlint only knows GitHub-hosted runner labels. The config file teaches it your self-hosted labels and config variables.
What it does
actionlint loads .github/actionlint.yaml. self-hosted-runner.labels lists your custom runs-on labels so they pass validation, and config-variables declares the names available under the vars context so references to them are not flagged.
Common usage
self-hosted-runner:
labels:
- linux-x64-large
- gpu-runner
config-variables:
- DEPLOY_ENV
- FEATURE_FLAGSConfig keys
| Key | What it does |
|---|---|
| self-hosted-runner.labels | Custom runs-on labels to accept |
| config-variables | Allowed vars context names (null = allow all) |
| paths | Per-glob ignore patterns for specific errors |
In CI
Keep actionlint.yaml in .github/ so the linter finds it automatically. Setting config-variables to a list makes any unlisted vars.X an error, which catches typos; set it to null only if you do not want that check.
Common errors in CI
"label \"X\" is unknown" persists when the label is missing from self-hosted-runner.labels or the file is not under .github/. "undefined config variable \"Y\"" means Y is not in config-variables; add it or correct the name. A malformed actionlint.yaml is reported as a config parse error before any workflow is linted.