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

> Validate GitHub Actions workflows locally using act's --validate flag. Catch syntax errors and structural issues before running containers for faster development.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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:

```bash
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/`:

```bash
act --validate

```

### Combining Validation with Dry Run

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

```bash
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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/cmd/root.go) via the `input.validate` conditional block.
- **Schema validation** occurs first using [`pkg/schema/workflow_schema.json`](https://github.com/nektos/act/blob/main/pkg/schema/workflow_schema.json) to ensure YAML structure complies with GitHub Actions specifications.
- **Model validation** follows in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/pkg/model/workflow.go) and [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/pkg/model/workflow.go) to check raw YAML before deserialization into Go structs.