kryptorious-wfguard 1.0.0

Lint GitHub Actions workflows for CI-breaking and supply-chain issues — no Go install required.

kryptorious-wfguard

Lint GitHub Actions workflows for CI-breaking and supply-chain issues — no Go install required.

wfguard is a native Python CLI that catches the workflow mistakes that break CI or weaken your supply-chain posture before they merge. It parses .github/workflows/*.yml — no actionlint (Golang) dependency, runs anywhere Python runs, offline.

Pairs naturally with the 15 Kryptorious GitHub Actions you can drop in.

Install

pip install kryptorious-wfguard

Usage

# Lint all workflows under the current repo
wfguard check

# In CI — fail the build on any error-severity issue
wfguard check --fail-on error

# Machine-readable output
wfguard check --json
wfguard check --sarif > wfguard.sarif

# Catch warnings too (moving refs, missing shell, duplicate names)
wfguard check --fail-on warning

# Just enumerate discovered workflow files
wfguard list

What it catches

Rule	Severity	Catches
WF-002	error	Missing or empty on: trigger
WF-003	error	Missing or empty jobs:
JOB-001	error	Job is not a mapping
JOB-002	error	Job missing runs-on:
JOB-003	warning	Job has no permissions: (GITHUB_TOKEN defaults to write-all)
JOB-004	error	needs: references an undefined job
JOB-005	error	Job missing steps:
STEP-001	error	Malformed uses: reference
STEP-002	warning	uses: pins a moving tag/branch (main, master, develop, .x)
STEP-003	warning	uses: uses a non-standard ref (not semver or SHA)
STEP-004	warning	run: without shell:
STEP-005	warning	Duplicate step name
ENV-001	warning	References env.X that is never defined
YAML-001	error	YAML parse failure

Why not just use actionlint?

actionlint is excellent but ships as a Go binary — another toolchain to install and pin in CI, and it doesn't run on every platform out of the box in a Python shop. wfguard is one pip install, drops into a Python project's existing test/CI flow, and emits JSON or SARIF so you can gate on it directly.

CI example

# .github/workflows/wf-lint.yml
name: Workflow Lint
on: [pull_request]
jobs:
  wfguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install kryptorious-wfguard
      - run: wfguard check --fail-on error

License

MIT — free for any use. Part of the 31-tool Kryptorious Developer Suite ($9 lifetime, DevFlow Premium included).