Build metadata by hosting provider
Build metadata connects a note to the preview revision that received it.
<meta name="gutternote:branch" content="fix-nav" /><meta name="gutternote:commit" content="9f2c1ab000000000000000000000000000000000" /><meta name="gutternote:pr" content="128" />| Tag | What it controls |
|---|---|
gutternote:branch | Gives a built-in agent the branch behind the preview, and lets a connected agent on that branch find the note. |
gutternote:commit | Identifies the code revision the reviewer saw. |
gutternote:pr | Supplies the PR number as metadata and lets a connected agent filter notes by PR. GitHub publication also requires a verified repository and commit. |
Provider variables
| Provider | Branch | Commit | Pull request |
|---|---|---|---|
| Vercel | VERCEL_GIT_COMMIT_REF | VERCEL_GIT_COMMIT_SHA | VERCEL_GIT_PULL_REQUEST_ID |
| Netlify | BRANCH | COMMIT_REF | REVIEW_ID |
| GitHub Actions | GITHUB_HEAD_REF, then GITHUB_REF_NAME | GITHUB_SHA | Parse GITHUB_REF=refs/pull/<number>/... or set GUTTERNOTE_PR |
| GitLab CI | CI_COMMIT_REF_NAME | Set GUTTERNOTE_COMMIT_SHA | CI_MERGE_REQUEST_IID |
| Buildkite | BUILDKITE_BRANCH | Set GUTTERNOTE_COMMIT_SHA | BUILDKITE_PULL_REQUEST |
| Cloudflare Pages | CF_PAGES_BRANCH | Set GUTTERNOTE_COMMIT_SHA | Set GUTTERNOTE_PR |
| Render | Set GUTTERNOTE_BRANCH from RENDER_GIT_BRANCH | Set GUTTERNOTE_COMMIT_SHA from RENDER_GIT_COMMIT | Set GUTTERNOTE_PR |
| Another host | GUTTERNOTE_BRANCH | GUTTERNOTE_COMMIT_SHA | GUTTERNOTE_PR |
The Vite plugin reads these variables and emits the tags. Without Vite, write the same values into the page head during the build.
Rules
- Commit values must contain 7 to 40 hexadecimal characters.
- GitHub preview verification accepts any of these lengths. The value must be the start of one of the pull request’s commits.
- Pull request values must be positive integers.
- Unsubstituted strings such as
${GITHUB_SHA}are ignored. - The browser cannot recover CI variables after deployment. Emit them during the build.
- Explicit
gutternote:*tags win over Vercel-specific fallbacks and hostname inference.
Where it is required
Emit all three tags on every preview and staging build that loads the widget. Production can go without them.
A note still saves without them. But without a pull request number it is not in the pull request summary. Without a branch or pull request, a connected agent working that branch never sees it.
Tags do not establish repository identity. New previews publish to GitHub only after the App verifies the repository, PR and full head commit. Older unbound previews remain readable without GitHub comments or checks. See Connect GitHub.