GitHub Actions workflow file exceeds the maximum size limit

By Daniel Zoghalchali·Latchkey

GitHub enforces a maximum size for an individual workflow file. A workflow that grows past that limit - often from huge inline matrices or embedded scripts - fails to load and does not run.

What this error means

A workflow does not run and reports that the workflow file exceeds the maximum allowed size.

Error: The workflow file is too large. Workflow files must be smaller than the maximum allowed size.

Common causes

Large inline scripts or matrices

Big embedded run blocks or sprawling matrices bloat the file past the limit.

Everything in one monolithic workflow

Combining many jobs and inline config in a single file pushes it over the size cap.

How to fix it

Extract scripts and split the workflow

1. Move large run blocks into committed scripts and call them.
2. Split logical groups into separate workflow files or reusable workflows.

steps:
  - run: ./scripts/build.sh
  - run: ./scripts/test.sh

Generate dynamic matrices instead of inlining

1. Replace huge inline matrices with a job that emits a compact matrix via fromJSON.
2. This shrinks the static file substantially.

How to prevent it

• Keep run blocks in scripts and workflows modular.
• Use reusable workflows to avoid monolithic files.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions