Connect GitHub

One project connects to one GitHub repository. Gutternote can publish feedback from verified previews and report open notes as a check.

Your previews need the gutternote:pr tag and the commit SHA. See Build context.

Before connecting

When the GitHub App is available on the deployment but this project has no saved GitHub settings and is not connected, the GitHub repo page offers Save disabled settings. It saves pull-request summaries, checks, merge blocking, and agent pushes as off in Gutternote. It does not connect the App or choose a repository. You can change these choices after connecting.

1. Connect the GitHub App

1. In the dashboard, open the project’s GitHub repo page.
2. Select Connect GitHub.
3. In GitHub, choose the account and only the repositories Gutternote needs. For an organization, an organization owner must approve the App.
4. Back on GitHub repo, choose the repository this project’s previews come from, then save. GitHub verifies the repository identity when you save.

If the App is already installed, select Use an existing installation instead. Gutternote lists the installations you own. An organization GitHub won’t confirm you own is named below the list, with the fix: an owner approves the App’s Members: Read-only permission or connects it, or you accept your invitation or sign in through the organization’s single sign-on. Then select Cancel and try again.

Which previews can publish feedback

For a new preview, Gutternote verifies that its pull request belongs to the selected repository and that its commit SHA is one of the pull request’s commits. A short SHA of at least 7 characters works, and so does a preview a push or two behind the head. The PR tag is build metadata; it cannot verify a repository on its own. The App needs access to read that pull request. A personal or server access token cannot publish preview summaries or checks.

The binding stays with that preview. Changing the project’s repository cannot move old notes to another repository’s pull request with the same number. A preview that was not verified when it was first seen is verified again on its next note, and its earlier notes are published with it once it is. Existing unverified previews stay readable in Gutternote and show Repository not verified. Saving a repository does not bind those older previews. If a preview URL is reused for a conflicting repository or PR, its new notes remain in the project’s note list without a GitHub destination.

The review destination can show a pull request’s open, closed, or merged status from a signed GitHub event when every visible note is bound to that same verified repository and pull request. Unbound or mixed-repository notes, and unknown or ambiguous events, show an unavailable status. Counts stay separate: merging a pull request never resolves its notes or starts an agent. When GitHub publishing is enabled, an existing GitHub comment or check can show the same lifecycle status. While publishing is paused, those existing GitHub outputs do not refresh.

If the page says GitHub publishing is paused in this release, your notes, repository settings and feedback choices stay saved. Older running versions may still send comments or checks until they stop. Changing the repository does not resume publication.

2. Choose what GitHub shows

Under Pull request feedback, turn on what you want, then select Save repository settings. Unless you saved the disabled settings before connecting, the summary comment and the check start on; failing the check starts off.

• Post a summary comment on the pull request. One comment per reviewer’s sitting, with a link to each pin. It updates as notes change. See Pull request feedback.
• Report the unresolved count as a check. A check on the pull request that shows how many notes are open. It needs the summary comment on.
• Fail the check while comments are unresolved. The check fails until every note is resolved.

The check

The check is named Gutternote comments. It runs when a pull request is opened, reopened or pushed to. A pull request with no notes gets a passing check. One that was already open when you turned the check on gets it on its next push. If GitHub turns the check away for a moment, during a rate limit or an outage, Gutternote tries again.

If more than one project reports the check on the same repository, a pull request gets it only once it has a note. Each project posts its own Gutternote comments check, and GitHub keeps the latest, so a project with nothing to say would turn another project’s failing check green. To get the check on every pull request, leave it on in one of those projects and turn it off in the rest.

Notes on the preview	Fail setting off	Fail setting on
None	Success	Success
All resolved	Success	Success
One or more open	Neutral	Failure

The title shows the count, such as No comments on this preview, 3 unresolved comments or All 5 comments resolved. The details link opens the widget’s list of every comment on the preview.

Block merges until notes are resolved

Gutternote reports the result. GitHub decides whether it blocks a merge.

1. Turn on Fail the check while comments are unresolved.
2. Let Gutternote comments report at least once.
3. In GitHub, open the repository’s Settings and edit the ruleset for the target branch.
4. Turn on Require status checks to pass before merging.
5. Type the full name Gutternote comments and choose the gutternote app as its source.
6. Save the ruleset.

Accept the Checks permission

If the GitHub repo page says GitHub hasn’t let Gutternote write checks, the App was installed before it asked for them. An owner of the GitHub account must approve the updated permissions. Until then the check never appears, so don’t make it required.

Reload the GitHub repo page a minute or so after approving and the notice is gone. When publishing is running, open pull requests pick up the check within moments. Push to any open pull request that still has no check before you make it required.

If the comment or check is missing

• GitHub publishing is paused in this release: your project settings stay saved; changing them does not resume publication. Older running versions may still send comments or checks until they stop.
• No summary comment: check that the App repository is verified, the summary switch is on, and the new preview has the correct PR number and full head commit SHA. Repository not verified previews keep their notes in Gutternote; changing the project connection does not bind them retroactively.
• No check: check that the check and summary switches are on and the App can still reach the repository. If the page says GitHub hasn’t let Gutternote write checks, see Accept the Checks permission. If more than one project reports the check on the repository, see The check. If the App’s updated permissions are waiting in the account’s GitHub Apps settings, an owner must accept them first; until then GitHub sends Gutternote no pull request events, so a pull request with no notes gets no check.
• The check stays on an old commit after a push: an organization owner must accept the App’s updated permissions. Find the request in the organization’s Settings → GitHub Apps → Gutternote.
• A ticked note in the summary comment does not resolve: the same fix. An owner must accept the App’s updated permissions. Until then, GitHub does not tell Gutternote about the tick.

Disconnect

A workspace owner selects Disconnect on the GitHub repo page. New comments and checks stop. Old ones stay in GitHub.