Build context

Every preview and staging build that loads the widget needs three meta tags:

<meta name="gutternote:branch" content="fix-nav" />
<meta name="gutternote:commit" content="9f2c1ab000000000000000000000000000000000000" />
<meta name="gutternote:pr" content="128" />

Without them, a note still saves, but it never reaches the pull request, the GitHub check or a coding agent working on that branch. Production doesn’t need them.

The tags identify build metadata, not a repository grant. GitHub feedback needs the App to verify the repository, PR and commit. The commit can be the full SHA or a short one of at least 7 characters, and must be one of the pull request’s commits. An unverified preview is verified again on its next note. See Connect GitHub.

Use the Vite plugin

Install it:

pnpm add -D @gutternote-devs/vite-plugin

Add it to vite.config.ts:

import { defineConfig } from 'vite'
import { gutternote } from '@gutternote-devs/vite-plugin'

export default defineConfig({
  plugins: [gutternote({ enabled: 'auto' })],
})

The plugin reads your CI variables and writes the tags at build time. For its options, see the Vite plugin reference.

Or write the tags yourself

Add the tags to the page layout your preview build uses. Fill the values at build time, because the browser can’t read CI variables after the page ships.

Host	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	GITHUB_SHA	parse GITHUB_REF

For other hosts, see Build metadata.

Check the page

Fetch a deployed preview and look for the tags:

curl -s https://your-preview.example.com/ | grep 'gutternote:'

Each tag should hold a real value, not an unfilled ${...}.

Source stamps

The Vite plugin can also stamp each element with the file and line that rendered it. A coding agent then knows where to start. Stamps are optional. enabled: 'auto' turns them on for the dev server and previews, never for production.

If notes land on the wrong build

Check the tags in the HTML the browser received, not in your template:

• Notes from another pull request show up: check gutternote:pr. It must be the pull request number, not a URL or branch name.
• Notes sit under an earlier build: check gutternote:commit.
• An agent picks the wrong branch: check all three.

Common causes are cached HTML from an earlier deploy, and CI variables that the deploy step can read but the app build can’t. Fix the source and rebuild. Notes left before the fix keep the values they were given.