gh-actionlint

GH Actionlint

Purpose

Use actionlint to catch GitHub Actions workflow mistakes before CI does: YAML syntax errors, invalid workflow keys, expression mistakes, bad needs references, invalid triggers, and other common Actions-specific issues.

Generic YAML linters are useful for indentation, but they do not understand GitHub Actions semantics. Prefer this skill whenever the file is a GitHub Actions workflow.

When To Use

Use this skill when:

• The user asks to check, lint, validate, or debug GitHub Actions workflows.
• You modify files under .github/workflows/.
• CI fails with workflow parsing, expression, trigger, needs, matrix, or Actions schema errors.
• The user asks whether a workflow step shape is valid, such as an unnamed run: step.

Workflow

1. Work from the repository root when possible.
2. Identify the workflow targets:
   • If the user named specific files, check those files.
   • Otherwise, check .github/workflows/.
3. Choose the runner:
   • If bun is available, use bunx github-actionlint.
   • Otherwise, if npx is available, use npx --yes github-actionlint.
   • If neither exists, tell the user that bun or npx is needed.
4. Run actionlint.
5. Report whether the workflows passed. If there are failures, quote the relevant actionlint messages and suggest the smallest fix.

Commands

Check all workflows:

if command -v bun >/dev/null 2>&1; then
  bunx github-actionlint .github/workflows/
elif command -v npx >/dev/null 2>&1; then
  npx --yes github-actionlint .github/workflows/
else
  echo "need bun or npx on PATH" >&2
  exit 1
fi

Check specific workflow files:

if command -v bun >/dev/null 2>&1; then
  bunx github-actionlint .github/workflows/tests.yaml
elif command -v npx >/dev/null 2>&1; then
  npx --yes github-actionlint .github/workflows/tests.yaml
else
  echo "need bun or npx on PATH" >&2
  exit 1
fi

Use -color -verbose when extra diagnostics are helpful:

bunx github-actionlint -color -verbose .github/workflows/