GitHub Actions "Unexpected value 'runs-on'" in CI

By Kaveh Alemi·Latchkey

runs-on belongs inside a job mapping. When it appears at the workflow root or directly under jobs:, the validator rejects the file with "Unexpected value 'runs-on'".

What this error means

The run fails with "Invalid workflow file" and "(Line: N, Col: M): Unexpected value 'runs-on'", pointing at a runs-on: key that is not inside a job.

Invalid workflow file: .github/workflows/ci.yml
(Line: 5, Col: 3): Unexpected value 'runs-on'

Common causes

A missing job id above runs-on

Without jobs.<id>:, the runs-on key has no job to belong to.

runs-on misindented to the workflow level

A de-indent pulled runs-on out of its job and up to the top of the file.

How to fix it

Move runs-on inside the job

1. Add or restore the job id under jobs:.
2. Indent runs-on inside that job.
3. Re-run the workflow.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo ok

Verify the job body indentation

Keep runs-on, steps, and other job keys one level deeper than the job id.

How to prevent it

• Declare a job id before any job-level keys.
• Use a workflow schema in your editor.
• Keep indentation uniform across jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions