Reviews
Install the GitHub App
Two paths. Use the hosted service, or register your own App against a self-hosted install.
Hosted
Install the Garboard App from GitHub and choose which repositories it covers. Garboard is currently in early access on staging.winchlabs.io — that is an early-access environment, described honestly, with no uptime commitment attached to it.
Pick repositories deliberately. Installing on “all repositories” is the most common cause of a confusing first week: Garboard is quiet on repositories with no infrastructure, so a broad install mostly produces silence you then have to interpret.
Self-hosted
Register your own GitHub App pointing at your instance. The one-step manifest flow is documented under self-hosting; it creates the App and its credentials together rather than walking you through six screens.
Whichever way you create it:
| Setting | Value |
|---|---|
| Webhook URL | <GARBOARD_BASE_URL>/webhook |
| Subscribe to | Pull request |
| App ID | → GARBOARD_GITHUB_APP_ID |
Private key (.pem) |
→ GARBOARD_GITHUB_PRIVATE_KEY_FILE |
| Webhook secret | → GARBOARD_WEBHOOK_SECRET |
GARBOARD_BASE_URL must be a publicly reachable URL, because GitHub has to call it. Locally, that means a tunnel.
If the App is not configured on the server, /webhook returns 503 and says which provider is unconfigured. That is a useful signal rather than a failure: see nothing happened.
Permissions
Two sets. Compare them against GitHub’s consent screen — if a page and a consent screen disagree, believe the consent screen and tell us.
Review only
| Permission | Access | Why |
|---|---|---|
| Pull requests | Read & write | Post and update the review comment. |
| Contents | Read | Read the changed files at the head SHA. |
| Metadata | Read | Mandatory for every GitHub App. |
With this set you get reviews, findings and evidence. You do not get the merge-gate check run, and you do not get Fix or Forge.
Adding the merge gate, Fix and Forge
| Permission | Access | What it buys |
|---|---|---|
| Checks | Read & write | The check run that can gate a merge. |
| Contents | Read & write | Fix commits a corrected file to your PR branch; Forge opens a PR. |
What declining costs you. Without Checks-write, Garboard still comments but cannot post a check run, so it cannot block a merge — it becomes advice rather than a gate. Without Contents-write, Fix and Forge are unavailable; findings and the gate are unaffected.
Contents-write is the grant people hesitate over, and rightly. It is what lets Garboard commit to a branch. It never merges, and it holds no cloud credentials — see what Garboard writes.
Then scan the repository
A review loads conventions derived by an earlier scan. Connect the repository and scan it once; until then reviews have your repo’s rules but not your repo’s conventions, and will say much less than you expect.
Verify it works
Open a pull request that changes an infrastructure file. Within a minute you should see a check run, and a comment if there is something to say. If you get neither, work through nothing happened — and read when Garboard says nothing before concluding it is broken.