greenwash

Find required CI checks that can go green without doing the work.

A green required check is treated as proof the tests ran. It is not. From GitHub's own documentation:

Required status checks must have a successful, skipped, or neutral status before collaborators can make changes to a protected branch.

Skipped counts as passed. So a job gated behind an if: that evaluated false, a job skipped because the job it needed failed, a workflow filtered out by paths: and backstopped by a same-named always-green twin, or a step wrapped in continue-on-error: true all produce the same green tick as a full passing run. Nothing in the UI tells them apart. The merge succeeds, main breaks, and the pull request still shows all-green months later.

greenwash reads your branch rules and your workflow definitions and tells you which of your gates are real.

Installation

pip install greenwash

Requires Python 3.10+ and a GitHub token, from GITHUB_TOKEN, GH_TOKEN, or gh auth login.

Quick start

greenwash audit                       # the repository you are standing in
greenwash audit --repo owner/name

$ greenwash audit --repo home-assistant/core
home-assistant/core (dev)  8 required checks, 13 workflows, via ruleset

2 hollow, 5 blocked, 2 advisory

[hollow] Check all requirements  (skips-with-upstream)
  where   .github/workflows/ci.yaml:gen-requirements-all
  detail  needs: info, base
  why     if an upstream job fails or is skipped this job is skipped too,
          which satisfies the gate rather than failing it -- the failure
          merges

Three severities:

• hollow — the check can report success without the work running.
• blocked — the check can never report at all, so the gate is stale or the branch is unmergeable.
• advisory — the signal is weakened but not void, or the finding depends on a choice you may have made deliberately.

What it looks for

In CI

greenwash audit --fail-on hollow

Exit 1 when any hollow finding exists, so a repository can gate on its own gates being real. --fail-on any includes advisories. --json gives the same data machine-readable.

What it does not do

It cannot tell you whether a job that ran did any real work. A job whose pytest step collected zero tests looks identical to one that ran the suite. This is a static audit of workflow definitions against branch rules; proving the work happened needs run history and a declared witness, which is not built yet.

It cannot read what your token cannot read. Classic branch protection needs admin. When a branch reports protected: true and no rules come back, greenwash says so and stops rather than reporting a clean bill of health — a tool that called an invisible gate a missing one would be committing the error it exists to find.

It does not resolve reusable workflows. A uses: workflow reports as caller / job, which this version does not follow, so those may show up as required-check-has-no-job. Third-party apps that post check runs will too.

Merge queues change when the gate applies. A job gated on merge_group is skipped on the pull request and runs in the queue. greenwash reports the definition; whether that is a problem depends on where you enforce merging.

Why the name

Greenwashing is presenting something as better than it is on the strength of a symbol rather than the substance behind it. A green tick that certifies nothing is the same trick.

License

MIT