GitHub Actions "Unexpected value 'steps'" in CI

By Daniel Zoghalchali·Latchkey

The workflow validator allows steps only inside a job. When steps appears one level too high (under the workflow root, or directly under jobs), it reports "Unexpected value 'steps'".

What this error means

The run fails with "Invalid workflow file" and "(Line: N, Col: M): Unexpected value 'steps'", with the line pointing at a steps: key outside a job body.

Invalid workflow file: .github/workflows/ci.yml
(Line: 6, Col: 1): Unexpected value 'steps'

Common causes

steps defined under jobs instead of under a job

A job id was forgotten, so steps: sits directly under jobs: rather than inside jobs.<id>:.

Indentation collapsed a job

A de-indented steps: escaped its job mapping and landed at a level the schema does not accept.

How to fix it

Nest steps inside a named job

1. Add a job id under jobs:.
2. Put runs-on and steps inside that job.
3. Re-run the workflow.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

Check the indentation of the job body

Ensure runs-on and steps are indented one level deeper than the job id.

How to prevent it

• Always declare a job id between jobs: and steps:.
• Use a schema-aware editor that flags misplaced keys.
• Keep job bodies consistently indented.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions