阅读中文版本

GitHub Actions Invalid Workflow — YAML Syntax Error

Fix invalid workflow files by locating the YAML error, quoting special values, and validating locally before pushing.

grep -n "" .github/workflows/ci.yml | sed -n '<line>p'

python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo OK

Symptoms

When you hit “GitHub Actions Invalid Workflow — YAML Syntax Error”, guessing wastes time. The guide below follows evidence: reproduce the symptom, run targeted diagnostics, identify the root cause, apply the fix, and verify it with concrete checks.

Observed symptoms include:

• GitHub reports “Invalid workflow file” with a line and column
• A value like on: or if: with a colon breaks parsing
• The workflow worked until a special character was added

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Read the reported line and column

grep -n "" .github/workflows/ci.yml | sed -n '<line>p'

The column points at the exact character that broke parsing, usually an unquoted colon.

Step 2: Validate the YAML locally

python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo OK

A local parse error mirrors the Actions failure and lets you iterate fast.

Likely contributors, in order of frequency:

• Unquoted values contain characters YAML treats specially (: @ * [ ])
• Inconsistent indentation confuses the mapping structure
• A boolean-looking string (on, yes, off) is parsed as a boolean

Root Cause

GitHub Actions workflows are YAML. Unquoted colons, special characters, tab indentation, or boolean-like keys make the document invalid, so Actions rejects the file before scheduling any job.

The Fix

Quote values containing special characters, use spaces (never tabs), quote strings like “on” and “true” when literal, and validate the file with a YAML parser in a pre-commit hook.

Watch out: A YAML linter may accept documents Actions rejects for schema reasons; validate both syntax and structure.

# ❌ unquoted colon inside a value
# - name: Build: app

# ✅ quoted value
steps:
  - name: "Build: app"
    run: make build
  - name: Run if literal string
    if: github.ref == 'refs/heads/main'
    env:
      FLAG: "true"   # quoted to stay a string

Verify and Prevent

Push and confirm the workflow is accepted and jobs run; keep the local YAML check in CI to prevent regressions.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.