Skip to content
Open the dashboard
Documentation

What happens on GitHub

Engineering leadsDevelopersSecurity7 min read

Pushing to GitHub does nothing by itself. A pull request is where a rule shows up on GitHub, and only if something is set up to run the check there. Here is what you get in each setup, for one example: a literal password in application.yml, with JAVA-008 at Advise.

Setup On the pull request In the workspace What you give up
Nothing No check. The password can be merged by anyone. Nothing GitHub is blind; protection depends on each developer’s laptop
A workflow file An Actions job, green at Advise with the finding in its summary; red at Enforce. Can be a required check. Also fails if AGENTS.md is stale. Nothing, unless the step adds --upload and a token The result never reaches the dashboard
Workflow with token, plus the GitHub App The same, and the result is posted on the pull request as the Groundrule check with findings inline Every run on the Pull requests page; the dashboard counts what was stopped A one-time token and a workflow file
Groundrule Code Checks A Groundrule check appears with nothing in the repository, green at Advise, red at Enforce Same as above Groundrule reads the code, in a sandbox; sync --check does not run; pull requests only

The two GitHub apps are separate on purpose. The GitHub App never reads code: it posts results and reads review comments to find rules reviewers keep repeating. Groundrule Code Checks is the only app that reads code, and it is off until you switch each repository on.

The hosted check and the CI check read .groundrule/config.yaml from the base branch, never from the pull request. Otherwise a pull request could edit the configuration to switch off the rules it is about to break.

This has one practical consequence. If you connect a repository to the workspace on a branch, the pull request from that branch is still checked with whatever main has, which may be the local packs, where a blocker has no stage. Connect on main first, then open the demo pull request.

When Groundrule Code Checks runs, the check page shows a line like: “Code read at 21:15:02 in a sealed sandbox and deleted at 21:15:09. No code was kept.” Here is what that means.

a hosted check, second by secondwhat the "code read at … deleted at …" line means
  1. 0 sA fresh room is built

    A new sandbox for this one check. No network, not even DNS. Two minutes, at most.

  2. 1 sThe code goes in; the token stays out

    The pull request's files, as an archive. The GitHub token never enters.

  3. 2 sThe check runs

    The same engine as the CLI, against main's configuration and the rulebook.

  4. 7 sThe room is demolished

    Code deleted. The timestamp is written only once deletion succeeded.

  5. 8 sOnly the result leaves

    Rule, file and line per finding. No snippets. Signed, so it cannot be edited later.

What Groundrule keeps: a list of rule results and line numbers, and the two timestamps. What it never keeps: your code.

Think of it as a locked room with no windows, used for seven seconds, then demolished. The GitHub token that fetched the code stays outside the room; the room has no way to call GitHub or anywhere else. The result that leaves is signed, so groundrule verify can later prove nobody edited it, and it carries a digest of the rulebook at that moment, so an audit can tell exactly which rules a pull request was judged against.

A red check is advice until it is required. In the repository’s branch protection on GitHub, add Groundrule as a required status check. From then on, a pull request with a blocker at Enforce cannot be merged until the line is fixed.