What happens on GitHub
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.
Four setups
Section titled “Four setups”| 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 configuration comes from main
Section titled “The configuration comes from main”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.
The sealed room
Section titled “The sealed room”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.
- 0 sA fresh room is built
A new sandbox for this one check. No network, not even DNS. Two minutes, at most.
- 1 sThe code goes in; the token stays out
The pull request's files, as an archive. The GitHub token never enters.
- 2 sThe check runs
The same engine as the CLI, against main's configuration and the rulebook.
- 7 sThe room is demolished
Code deleted. The timestamp is written only once deletion succeeded.
- 8 sOnly the result leaves
Rule, file and line per finding. No snippets. Signed, so it cannot be edited later.
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.
Make the check count
Section titled “Make the check count”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.