heygrc
Engineeringthe heygrc team

Why heygrc is a GitHub App, not a CI YAML step

A compliance check that lives in a workflow file is a file in the repo it is checking. The pull request under deadline pressure can edit it in the same breath it ships the feature.

Plenty of security and compliance tooling installs as a line in your CI pipeline: a step in a workflow file that runs a scan and reports back. It is the easy way to add a check, and for a lot of checks that is fine.

heygrc installs as a GitHub App instead, and the reason is not preference. It is about where a gate's logic lives relative to the thing it is gating.

A workflow step is a file in the repo it gates

A CI step lives in `.github/workflows/`, inside the same repository as the code it checks, under the same permission model as every other file in it. When a workflow runs on `pull_request`, the version of that file the run actually executes is the one on the PR's own branch, so a pull request that edits the step can also be the pull request the edited step then reviews. The author does not need a second system or a second set of permissions to change what the check does. Committing to the branch is enough.

This rarely looks adversarial. Under a deadline, a required step gets a `continue-on-error: true`, or an `if:` condition that skips it for this release, with a ticket referenced in the commit message to revert it later. The ticket is real when it is written. Whether anyone comes back to it depends on whether the feature that just shipped reminds them to.

An app's logic was never a file you could edit

A GitHub App's review runs from the app's own backend, triggered by a webhook, not from a file checked into the repository it reviews. There is no workflow step to comment out, no `if:` condition to add, no line in the diff that turns the check off. The clearest case is uninstalling heygrc: that is an action on the app installation itself, which belongs to whoever administers the organization or the repositories it covers, not to whoever opened the pull request. Reconfiguring it, like changing how often it reviews, goes through heygrc's own API rather than through a commit in the repository being reviewed. Either way, the path to turning it off does not run through the pull request it is reading.

heygrc's check itself is advisory, not a hard merge gate on its own: it posts a neutral or passing status plus comments, and findings never fail the check by themselves. Whether a repository requires that status before merging is the repository's own branch-protection choice, and that choice, like uninstalling the app, sits with whoever administers the repository, not with the author of the pull request under review. What installing heygrc as an app changes is not whether a reading can eventually be turned off. It is whether the pull request shipping past it can turn it off by itself, with no separate access and no separate action.

This is not a claim that CI checks are unsafe

A workflow step can get the same property: put `.github/workflows/` behind CODEOWNERS with required review from code owners turned on, or mark the workflow required through an organization-level ruleset, and a PR author can no longer change it unilaterally. That is one more piece of repo configuration to set up on top of the check itself, and it is easy to skip, especially when the check is new and nobody has decided yet who should be allowed to turn it off.

heygrc does not need that extra step, not because workflow files are inherently unsafe, but because the review never lived in one to begin with. The gate and the code it gates sit in different places by construction, which is one less thing a team has to remember to lock down.

github-apparchitecturecicode-review