GitHub Action

Wingbox Pull Request Check

A pull request shows the lines that changed. This check turns them into a review plan: which function or type changed, which modules outside the pull request use it, and which tests to run. One comment for the reviewer, the same plan as a file for a reviewing agent. Computed on your runner without a language model.

Install from the GitHub Marketplace
Example

On a live pull request

This pull request changes one line inside a private function. The comment names the two public functions that call it, and every module that calls those, with the file and the line of each call.

A comment on a GitHub pull request, headed "Wingbox: 2 items touched by this change are used by 5 modules outside this pull request". It names the function load_session_timeline, says that it calls detect_log_format, which calls looks_like_claude_jsonl, which changed, and lists the modules that call it with the file and line of each call. Below: the folded rest, the parts that were not checked, and a folded review plan for an agent.Open the pull request on GitHub

How to read the comment

The heading

How many functions or types the change touches, and how many modules outside the pull request use them. Those modules are not in the diff, so a reviewer would not see them.

"X calls Y, which changed"

The change is inside Y. X is a function other modules use, and it calls Y in the same file. So the change reaches everyone who calls X.

The rows

Each module that uses the item: whether it calls it, imports it or uses it as a type, and where.

Tests that use what changed

The test files to run, by name. When a test changes together with the code it tests, the comment says so: look at what the test no longer checks.

One sentence

When the change is a comment, a test, or something no other module uses, the comment says so in one line and lists nothing.

New boundary findings

When the pull request adds an import that crosses a layer rule of your architecture, that finding leads the comment.

More

Folded under one line: a diagram of the modules around the change, the modules farther away, the tests, and the parts of the repository that could not be checked, said as such.

For agents

The same plan, for a reviewing agent

An agent that reviews a pull request usually gets the diff and searches the repository for what it touches. The check hands it the list instead: every place to open with the file and the line, every test to run, and what could not be checked. The plan is in a folded block of the comment and in a file on the runner (the output plan).

(review-plan :schema 1 :result UNKNOWN :execution ok :base 70939f6 :head cf6d8c8 :wingbox "0.11.0" :hops 2)
(reason "not-checked: . (no-layer-style)")
(changed-item "src/infra/session_detail.rs" load_session_timeline :kind fn :line 97 :how calls :via (detect_log_format looks_like_claude_jsonl))
(look "src/cli/mod.rs" 331 :module src/cli :why call :item load_session_timeline :places 2)
(look "src/infra/opencode.rs" 992 :module src/infra/opencode :why call :item load_session_timeline :places 1)
(look "src/main.rs" 426 :module src/main :why call :item load_session_timeline :places 5)
(not-checked "." :reason no-layer-style)
look
A place outside the pull request that uses what changed. Open it.
run-test
A test that uses what changed. Run it.
changed-item ... :via
The item calls the listed functions, and the last one is where the change is.
not-checked
A part of the repository the boundary rules could not be checked on.

A result that never reads "not checked" as "passed"

The check of the architecture rules ends in one of four results, given as an output of the action. Set fail-on: strict and the job fails on everything but a pass. In the example above the result is UNKNOWN: that repository has no layer rules to check, and the check says so instead of passing.

FAIL

The pull request adds an import or a call that crosses a rule, also one that only its own edit of the rules or of the baseline would accept.

UNKNOWN

A part of the repository was not checked, files of a language were left out, the files checked are not the commit the report names, or the tool ended abnormally. Never shown as a pass.

NOT_APPLICABLE

No source file outside the tests changed.

PASS

Everything was checked and nothing new crosses a rule.

Evidence that the tests ran

The check names the tests that use what changed; it never runs them. When the job runs its tests first and they write JUnit XML reports, hand the reports over: each test in the plan then says what the reports hold about it.

.github/workflows/wingbox.yml
      - id: tests
        run: python -P -m pytest --junitxml=test-results/junit.xml
        continue-on-error: true      # failing tests must not end the job before the check
      - uses: aileron-tech/wingbox-action@v1
        if: ${{ !cancelled() }}
        with:
          test-results: test-results/*.xml
          test-step-outcome: ${{ steps.tests.outcome }}
          require-tests: true     # optional: fail unless every test that uses what changed has a passed record
      - if: ${{ steps.tests.outcome != 'success' }}
        run: exit 1                  # the job fails when the tests did
Per test case

Each test that uses what changed carries what the reports hold about every one of its cases: passed, failed, partial (one case passed, another was skipped or did not run), skipped or no-record. Only passed counts as passed. When no test uses what changed, the test evidence is none-found, never complete.

Where a report comes from

A report is refused, and counts as no evidence, when git tracks it, when it is older than the run, or when it names another commit. A report of this run is written by the test step, not committed.

Required tests

A manifest in the repository, .wingbox/required-tests.yaml, says which tests a change of which paths must pass, whatever the graph finds. It is read from the base commit, so a change cannot drop a requirement it is judged by.

A change cannot accept its own break

When a pull request edits the rules or the baseline, its findings are judged with those files as the base has them. A new baseline entry needs an owner, a reason and an end date. With fail-on: strict, a pull request that edits such a file fails the job.

The commit that was checked

The report names the commit whose files it read, and the SHA-256 of each changed file in that commit. When the checkout is another commit, or holds changed files, the result is UNKNOWN.

wingbox-evidence.json

Every run writes one JSON record, also when the test step fails or the check itself could not run. It keeps the verdicts apart (introduced, there before, baseline, tests, coverage), says what the run analysed and what it left out, and whether the record is eligible as evidence. Its schema, version 2, is in the repository.

Inputs: test-results, test-step-outcome, require-tests, required-tests, test-command, policy-change. Outputs: evidence, eligible, coverage-complete, tests-evidence, tests-passed, tests-failed, tests-without-record, test-reports-refused, policy-changed.

All inputs and outputs

For a team that prepares for an audit: what a run gives as evidence, and where it stops; the three modules.

Add it to a repository

One workflow file. No account, no API key, no configuration.

.github/workflows/wingbox.yml
name: wingbox
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: aileron-tech/wingbox-action@v1
uses: aileron-tech/wingbox-action@v1
Install from the GitHub Marketplace
GitLab

In GitLab CI

The same check for merge requests and for pushes to the default branch, on GitLab.com or your own instance. One include line. The report goes to the job log and to artifacts; with a project access token it is also one note on the merge request, updated on each push.

Runners with the Docker or Kubernetes executor

.gitlab-ci.yml
include:
  - remote: "https://raw.githubusercontent.com/aileron-tech/wingbox-action/v1/gitlab/wingbox.gitlab-ci.yml"

Runners with the shell executor

.gitlab-ci.yml
include:
  - remote: "https://raw.githubusercontent.com/aileron-tech/wingbox-action/v1/gitlab/wingbox-shell.gitlab-ci.yml"

A shell runner runs the commands on its own machine, with whatever Python that machine has. This job runs the check in a container instead: your checkout is mounted read-only, and the only folder written on the runner is wingbox-out/.

A note on a GitLab merge request, headed "Wingbox: 2 items touched by this change are used by 5 modules outside this merge request". It names the function load_session_timeline, says that it calls detect_log_format, which calls looks_like_claude_jsonl, which changed, and lists five modules that call it with the file and line of each call.
The note on a merge request that changes one line inside a private function.

Merge request

The merge request's diff base against its head commit.

Push to the default branch

The commit before the push against the pushed commit. For teams that push without a merge request.

The log of the GitLab job: the same report as text, with the heading and the list of modules that call the changed function.
The same report in the job log. A push to the default branch has no merge request, so the log and the artifacts are where it is read.

What the job leaves

wingbox-out/wingbox-report.md
The full report.
wingbox-out/wingbox-plan.sexp
The review plan for an agent: the places to open and the tests to run.
wingbox-out/wingbox-evidence.json
The evidence record of the run, as JSON.
WINGBOX_RESULT and six more variables
PASS, FAIL, UNKNOWN or NOT_APPLICABLE, the reasons and the counts, handed to the later jobs of the pipeline.
One note on the merge request
When the masked CI/CD variable WINGBOX_GITLAB_TOKEN holds a project access token with the api scope. Without it nothing is posted.
WINGBOX_RESULT=UNKNOWN
WINGBOX_EXECUTION=ok
WINGBOX_REASONS="not-checked: packages/ccbox (no-layer-style); ..."
WINGBOX_UNTOUCHED_DEPENDENTS=15
WINGBOX_INTRODUCED_FINDINGS=0
WINGBOX_NOT_CHECKED_PARTS=3
WINGBOX_TESTS_TO_RUN=0
wingbox:
  variables:
    WINGBOX_FAIL_ON: "strict"     # none (default), violations, not-checked, strict or existing
    WINGBOX_VERSION: "0.14.0"     # the wingbox release from PyPI
    WINGBOX_ACTION_REF: "v1"      # a tag, a branch or a commit of wingbox-action

To pin everything, put a commit in both places: in the address of the include and in WINGBOX_ACTION_REF.

All settings for GitLab CI

What it never does

No language model

The comment is computed: parsers build a graph of the code and the report is read from it. The same pull request gives the same comment.

No code leaves the runner

The graph is built and queried on your own GitHub or GitLab runner. The comment holds module names, file paths and item names; no source lines.

Nothing is written to your repository

No commit, no push, no file in your branch.