GitHub Actions "Top level 'jobs' section is required"

By Daniel Zoghalchali·Latchkey

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.

Actions annotation

Invalid workflow file: .github/workflows/ci.yml
The top level 'jobs' section is required.

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.

.github/workflows/ci.yml

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

Fix 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.

How 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.

Frequently asked questions

What causes ""jobs section required""?