Validating GitHub Actions Workflows with act's `--validate` Flag

The act CLI provides a --validate flag that performs JSON Schema and model-level validation on workflow files, catching syntax errors and structural issues before any containers run.

Validating GitHub Actions workflows locally saves time by catching configuration errors before pushing to GitHub. The nektos/act tool includes a built-in validation mode that checks workflow files for schema compliance and logical consistency without executing any job steps. This feature makes act function as a fast, offline linter for your CI/CD pipelines.

How the --validate Flag Works

When you invoke act with the --validate flag, the tool executes a two-phase validation process defined in cmd/root.go.

Schema Validation Phase

First, act validates the raw YAML against the official GitHub Actions JSON Schema stored in pkg/schema/workflow_schema.json. This step uses the gojsonschema library to verify that fields like jobs, steps, runs-on, and uses conform to the expected types and structures.

Model-Level Validation Phase

After successful schema validation, the YAML is unmarshaled into Go structs defined in pkg/model/workflow.go. The tool then runs additional checks that JSON Schema cannot express, including:

• Job name uniqueness via validateJobName in pkg/model/planner.go
• needs dependency resolution to ensure referenced jobs actually exist
• Matrix strategy validation via validateStrategy to check for valid strategy configurations
• Action syntax verification in pkg/model/action.go for proper uses declarations

If any validation fails, act aggregates all errors and exits with a non-zero status code, printing detailed file and line context for each issue.

Validating Single vs. Multiple Workflows

The --validate flag works with both individual workflow files and entire repository directories.

Validate a Specific Workflow File

Point act to an exact workflow path using the -W (or --workflows) flag:

act --validate -W .github/workflows/build.yml

This command parses only the specified file and reports any schema or model violations immediately.

Validate All Repository Workflows

When run from the repository root without the -W flag, act discovers and validates every *.yml or *.yaml file under .github/workflows/:

act --validate

Combining Validation with Dry Run

To see the execution plan after confirming validity, combine --validate with --dryrun (or -n):

act --validate --dryrun

This sequence first verifies the workflow structure, then prints the planned job execution graph without starting any Docker containers.

Understanding Validation Errors

act provides detailed error messages that pinpoint exactly where your workflow breaks. For example:

✖ Validation failed for .github/workflows/build.yml
  - jobs.build.steps[2].uses: Must be a string
  - jobs.test.needs: 'build' is not a defined job

Each error line includes:

• The file path and YAML path (e.g., jobs.build.steps[2].uses)
• A description of the constraint violation
• Context for missing references (e.g., undefined job names in needs arrays)

These messages correspond to validation logic found in pkg/model/planner.go, where functions like validateJobName check for duplicates and ValidateWorkflow verifies job dependencies.

Summary

• --validate triggers static analysis of workflow files without executing jobs, implemented in cmd/root.go via the input.validate conditional block.
• Schema validation occurs first using pkg/schema/workflow_schema.json to ensure YAML structure complies with GitHub Actions specifications.
• Model validation follows in pkg/model/planner.go, checking job name uniqueness, needs references, and strategy matrices.
• Usage patterns include single-file validation (-W path), directory-wide scans, and combination with --dryrun for safe CI debugging.

Frequently Asked Questions

Does --validate require Docker to be running?

No. The validation process operates entirely on static YAML and JSON Schema analysis within the Go codebase. Because act checks the workflow structure in pkg/model/workflow.go and pkg/model/planner.go before any container initialization occurs, you can validate workflows offline without a running Docker daemon.

What types of errors does --validate catch compared to --dryrun?

--validate catches syntax errors, missing required fields, type mismatches (e.g., providing a number where a string is expected), and structural logic errors like circular dependencies or undefined job references in needs. --dryrun assumes the workflow is valid and only simulates the execution plan. Use --validate first to ensure the YAML is correct, then --dryrun to preview execution order.

Can I validate workflows that use reusable workflows or composite actions?

Yes. The validation in pkg/model/action.go includes checks for uses syntax, which covers reusable workflows (e.g., uses: ./.github/workflows/reusable.yml) and composite actions. However, --validate checks the syntax and reference structure; it does not fetch or validate the content of external actions hosted in other repositories.

Where does act store the schema used for validation?

The JSON Schema defining valid GitHub Actions workflow structure resides in pkg/schema/workflow_schema.json within the nektos/act repository. This file is embedded into the binary during build time and loaded by the validation logic in pkg/model/workflow.go to check raw YAML before deserialization into Go structs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}