Rules from pull-request reviews

Code review is where most team rules are actually taught, one comment at a time. The Groundrule GitHub App reads review comments on the repositories you choose, so you can do two things:

• Import review history. AI reads the comments from a period you pick and proposes the rules reviewers keep asking for, each citing the comments behind it.
• Propose from a review. A reviewer writes /groundrule rule in a review comment, and the rule arrives in the inbox, linked to the comment.

Note

The GitHub App doesn’t check pull requests yet. Today, checks run where you run the CLI: locally, in a pre-commit hook, or as a CI step. See Run Groundrule in CI.

Install the GitHub App

Admins and platform admins install the app. Other roles see its status.

1. Open Settings → Connections. In the GitHub panel, choose Install the GitHub App.

2. Choose the account and repositories on GitHub. You can give the app all repositories or selected ones. GitHub then asks you to authorize the app.

3. Come back to Groundrule. GitHub sends you back to Settings → Connections.

You should see “GitHub connected. Import review comments from the Inbox → Import a document.” The panel lists the account with Connected, and “All repositories” or “Selected repositories”. Change repositories on GitHub opens the app’s settings on GitHub. Add another account installs it on another GitHub organization or user.

Groundrule saves an installation only when the person who installed it can see it on GitHub. One GitHub installation belongs to one Groundrule workspace.

If it goes wrong:

• “That GitHub installation is already connected to another Groundrule workspace.”
• “That GitHub installation is suspended. Unsuspend it on GitHub, then connect again.”
• “The connection didn’t complete (the request expired or came from elsewhere). Try again.”
• “Access wasn’t granted, so nothing was connected.”
• “Sign in again, then connect.”

To disconnect, choose the bin icon next to the account. You should see “Disconnected. Uninstall the app on GitHub too if you no longer need it.” Uninstalling the app on GitHub also removes it from Connections.

What the app can access

Permission on GitHub	Access
Pull requests	Read-only
Metadata	Read-only

The panel says: “Read-only: pull requests and metadata on the repositories you choose on GitHub.”

• Groundrule reads inline review comments on pull requests: the comments on lines of code in a review.
• With read-only permissions, it can’t push, comment, approve, or set statuses. It never replies on GitHub.
• Comments from bots are ignored.
• It reads only repositories you gave the app on GitHub.

Import review history

You need an authoring role and AI turned on for the workspace.

1. Open Inbox → Import a document, and choose PR reviews.

   “Groundrule reads inline review comments people wrote (not bots) and finds the rules reviewers keep asking for. Each proposal links to the comments behind it.”

2. Choose a Period: Last 30 days, Last 90 days (the default), Last 6 months, or Last year.

3. Choose Repositories, up to 20. With more than 8, a Filter box appears. Private repositories show Private.

4. Choose Continue, review the estimate, then Find rules. See Import documents for the estimate.

You should see an import titled “Review comments in owner/repo” (or “in N repositories”) in the Documents section, marked “From PR reviews”. Its proposals arrive in the inbox.

What becomes a proposal

Before AI reads anything, Groundrule cleans each comment:

• quoted lines (starting with >) are removed;
• suggested-change blocks are replaced with “[suggested change]”;
• each comment is cut to 1,500 characters;
• comments with fewer than 25 characters of their own text are dropped;
• secrets are redacted.

AI proposes a rule when:

• two or more comments ask for the same thing, ideally on different pull requests or from different reviewers; or
• one comment states a standing team convention, such as “we always…” or “please never… in this codebase”.

It ignores one-off bug reports, questions, praise, replies like “done”, and suggestions about a single line with no general point.

Each proposal shows a quote, owner/repo#123 · file:line · @reviewer, View on GitHub, and “Asked for in N review comments on N pull requests by N reviewers”. A rule backed by a single comment gets a confidence below 50%.

If it goes wrong:

• “The GitHub App can’t read any repositories yet. Choose some on GitHub.”: give the app repositories on GitHub.
• “Groundrule’s GitHub App can’t read owner/repo.”: the repository isn’t in the app’s selection.
• “No review comments from people in the last N days in those repositories.”: choose a longer period or other repositories.
• “Too many imports. Wait a while and try again.”: the limit is 10 review imports per person per hour.

Propose a rule from a review comment

When an admin has installed the app, the GitHub panel says reviewers can use /groundrule rule. No AI is involved, and it costs nothing.

Write the rule after the command, in an inline review comment on a pull request:

/groundrule rule Never log tokens or session cookies.

Or reply to a comment with only the command. The comment you replied to becomes the rule:

/groundrule rule

The command can start any line of the comment. Everything after it is the rule.

You should see a proposal in the inbox: “Proposed by @you in a pull-request review”, with the file and line and View on GitHub. Accept it like any instruction. See The review inbox.

Nothing happens when:

• the rule has fewer than 10 characters (and isn’t a reply to a longer comment);
• the comment is in the pull request’s conversation tab rather than on a line in a review;
• the comment was written by a bot;
• the installation isn’t connected to a workspace.

Rules longer than 1,000 characters are cut. Quoted lines and suggestion blocks are left out. Writing the same rule again adds a vote to the existing proposal.

Webhooks

/groundrule rule works through GitHub webhooks. Groundrule verifies every delivery’s signature and refuses one that doesn’t match. Each delivery is handled once, even if GitHub sends it again. When the app is uninstalled on GitHub, Groundrule removes the installation. See How Groundrule protects your code.

Limits

Limit	Value
Repositories per review import	20
Review comments read per import	2,000, newest first
Characters kept per comment	1,500
Review imports per person	10 per hour
/groundrule rule proposals per installation	60 per hour
Rule length for /groundrule rule	10 to 1,000 characters