Writing team rules heyGRC can check

heyGRC reviews pull requests for compliance. If your team has its own rules (for example "say whether you regenerated the API client"), you can write them into a .heygrc.md file and heyGRC will use them when it reviews pull requests. How you phrase the rule decides whether it gets raised.

What .heygrc.md is

• A Markdown file at the root of the repository, named exactly .heygrc.md.
• heyGRC reads it on every review of that repository. If it cannot use the file (over the size limit below, or a GitHub read error), the review still runs, without your rules, and heyGRC does not warn you on the pull request.
• It is read from the pull request's base branch, not from the pull request itself. A pull request cannot change the rules it is reviewed against. A new or edited .heygrc.md applies once it is merged.
• Size: heyGRC uses the first 8,000 characters. A file over 64,000 characters is skipped entirely. Keep the important rules near the top.
• Secret-shaped values are redacted before review. Even so, do not put secrets, customer data, ePHI or CUI in the file.
• The file is context, not a switch. heyGRC is built so it cannot turn off, waive or downgrade a finding: it is told to ignore text such as "exempt" or "do not report" and to report what the diff requires.

The file is optional. A repository without one gets the normal review.

Why plain team conventions get ignored

heyGRC looks for changes that affect a control: access, data, logging, change management, vendors, and so on. A rule written as a coding convention reads like code style, and heyGRC does not review code style. In our tests on the current review model, this phrasing was raised 0 times out of 17:

If the language is C# and the change modifies an existing API endpoint,
add a comment asking whether the API client was regenerated.

The same rule written as a compliance control was raised 4 times out of 4.

The pattern that works

Write each rule in four parts:

1. Name the control and the framework clause. For example ISO 27001 A.8.32 (change management) or SOC 2 CC8.1.
2. State the trigger. What kind of change the rule is about, in terms heyGRC can see in a diff (a file path, a kind of code, a kind of change).
3. State the evidence the pull request must carry. What the description or the diff must say or contain.
4. State the gap to report. What heyGRC should call out when the evidence is missing.

One rule per paragraph. Short is fine.

Worked example: client regeneration

Company context: Example Co runs an Orders API in C#. The main web app calls it through a generated client.

# Example Co

Example Co runs a C# Orders API. The web app calls it through a generated API client.

## Change-management control (ISO 27001 A.8.32, SOC 2 CC8.1)

A change to an existing C# API endpoint (route, signature, request or response
shape) is an interface change. The web app consumes this API through a
generated client, so an unregenerated client is an untested production change.
Any pull request that modifies an existing C# endpoint must state whether the
web app API client was regenerated. If the pull request does not say so, that
is a change-management gap to report.

Why it works: it names the control (A.8.32, CC8.1), the trigger (an existing C# endpoint changes), the evidence (the description says whether the client was regenerated) and the gap (the statement is missing).

Two more examples

Database migrations need a rollback note.

## Change-management control (ISO 27001 A.8.32, SOC 2 CC8.1)

A pull request that adds or changes a database migration changes production
data structures. It must describe how to roll the migration back (a down
migration or a written rollback step). If a migration has no rollback note,
that is a change-management gap to report.

Infrastructure changes need a platform-team reviewer.

## Segregation of duties (ISO 27001 A.5.3 and A.8.32, SOC 2 CC8.1)

Files under infra/ define production infrastructure. A pull request that
changes anything under infra/ must name a reviewer from the platform team in
its description. If no platform-team reviewer is named, that is a
change-approval gap to report.

What heyGRC does not do

• It does not run linters, tests or formatters.
• It does not enforce naming, formatting or code-style rules. Keep those in your linter.
• It does not request reviewers or edit your pull request. It reports the gap and your team acts on it.

Rules stay advisory

A team rule raises a finding like any other: a comment on the pull request. heyGRC does not block merges on its own. See Does heyGRC block merges?.

The model reads your rules as guidance, so expect strong but not perfect recall. Check a rule on a test pull request after you add it, and sharpen the trigger or the evidence if it is not raised.

For policies you already keep elsewhere (a DPA, a security policy), use linked documents instead of copying them into .heygrc.md.