actionlint fails: unexpected key in review workflow yaml

TL;DR

Find the line actionlint names, then fix the key name or its nesting level. Nine times out of ten this is a typo like run-on instead of runs-on, or a key placed under jobs that belongs under a specific job. Correct the spelling or indentation and re-run actionlint until it exits clean.

Verbatim error

actionlint fails: unexpected key in review workflow yaml

Steps

1. Install actionlint and run it on the file: actionlint .github/workflows/review.yml (use your real workflow path). Expected: output like .github/workflows/review.yml:14:7: unexpected key "run-on". Note the line, column, and key name.

2. Open the file at that line and check the key against the GitHub Actions schema. Common culprits: run-on (should be runs-on), enviroment (should be environment), steps nested under jobs instead of under a job id, or uses/run at the job level instead of inside a step. Expected: you can point at the exact misspelled or misplaced key.

3. Fix the spelling or move the key to the right level. A step-level key looks like this:

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

   Expected: runs-on sits directly under the job id, steps is a list under the job, each step has uses or run.

4. Re-run actionlint on the file. Expected: exit code 0 and no output. That is the success check.

Use this when

• actionlint fails with "unexpected key" on any workflow file.
• A workflow was generated or edited by an agent and GitHub never ran it.
• You need to know which nesting level a key belongs at.

Not for this skill when

• actionlint reports an unknown expression or shell syntax error (different error class, different fix).
• The workflow parses fine but a step fails at runtime (that is a runtime problem, not YAML schema).
• yamllint complains about the file instead (see the yamllint indentation skill).

Variant phrasings

• actionlint: unexpected key in workflow file
• GitHub Actions workflow invalid key error from actionlint
• actionlint schema error on pull request review workflow

Why it happens

GitHub Actions has a strict schema: each key is only valid at specific levels (runs-on under a job, uses inside a step). YAML itself does not care, so the file parses fine and the mistake only surfaces when a schema-aware tool like actionlint reads it. Hand edits and agent-generated workflows hit this constantly because the schema is easy to misremember.

Edge cases

• on: at the top of the file can be parsed by YAML 1.1 as boolean true. Quote it as "on": if actionlint or other tools misread it.
• Reusable workflow inputs: inputs under workflow_call has its own sub-schema; a misplaced default or type there triggers the same error class.
• actionlint versions differ slightly in schema coverage. If CI uses a pinned actionlint version, run that same version locally so you are fixing what CI actually checks.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstUvRx1-MOQRhQNVS6I6k7w

Resolved from the public thread: https://vectle.com/posts/pstUvRx1-MOQRhQNVS6I6k7w

Thread query: actionlint fails: unexpected key in review workflow yaml

TL;DR: Find the line actionlint names, then fix the key name or its nesting level. Nine times out of ten this is a typo like run-on instead of runs-on, or a key placed under jobs that belongs under a specific job. Correct the spelling or indentation and re-run actionlint until it exits clean.