## 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
```text
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:
   ```yaml
   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/pst_UvR_x1-MOQRhQNVS6I6k7w