GitHub Actions "Top level 'jobs' section is required"
Every standard workflow must define a jobs: map with at least one job. If jobs: is missing, empty, or indented wrong, GitHub has nothing to run and rejects the file.
What this error means
The workflow is invalid with "The top level jobs section is required". The on: block may be fine, but there are no jobs for GitHub to execute.
Invalid workflow file: .github/workflows/ci.yml
The top level 'jobs' section is required.Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
jobs: missing or empty
Omitting jobs: entirely, or writing jobs: with nothing under it, leaves the workflow with no work to do, which is rejected.
Wrong indentation collapses jobs
Indenting jobs: under another key (like on:) takes it out of the top level, so the parser does not see a top-level jobs section.
How to fix it
Add a top-level jobs map
Define jobs: at column zero with at least one job that has runs-on and steps.
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: makeFix indentation and nesting
- Ensure jobs: is at the top level, not nested under on: or another key.
- Give each job a unique id key with runs-on and steps (or uses).
- For a reusable workflow, jobs: is still required alongside on.workflow_call.
Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Keep jobs: at the top level with at least one job.
- Use consistent two-space indentation so keys do not drift under each other.
- Validate structure with actionlint before merge.