Connect CI for automatic verification

What this is

Think of it as running an automatic rehearsal once before you ship. Until now, you ran verification by pressing a button yourself. Set up CI integration, and every time your code changes (for example, when you push new code or open a review request), Specnote verifies your scenarios on its own.

CI here means the thing that automatically runs a set of checks every time you push code. If you use GitHub, GitHub Actions plays that role. Specnote slips "scenario verification" into one of those automatic checks.

One thing you can rest easy about: Specnote's server is what actually runs the verification. The place where your code runs (CI) doesn't open a browser or do any heavy lifting. CI just pulls the trigger — "verify now" — waits for the result, and picks it up. So your side stays light, and there's no chance of production passwords or keys being handed over.

When verification finishes, the results land in two places.

• The review request (PR) screen — a pass/fail summary is attached in plain language, so you can see what broke before merging.
• The test-run tab — this verification is stacked as one run group, so you can look back on it later.

Let AI do it (recommended)

This is the easiest way. Copy the text below and paste it into the AI coding tool you usually use (Claude Code, Cursor, and the like), and AI handles what's needed to connect — issuing the token, creating the workflow file, and committing, all of it.

Connect Specnote's automatic verification to this repository's GitHub Actions. 1) Use the specnote_get_ci_workflow tool to get the workflow file contents and save them to .github/workflows/specnote-verify.yml (specId is ""; use standard mode if there's a deploy/staging address, or local mode if there's only a local dev server). 2) Use the specnote_issue_ci_token tool to issue a CI-only token. 3) Register the issued token as the GitHub repository secret SPECNOTE_TOKEN — if the gh CLI is available, use gh secret set SPECNOTE_TOKEN; if not, guide me to the repository → Settings → Secrets and variables → Actions path. 4) If a verification target address (staging/preview) is needed, ask me, then register it with gh variable set SPECNOTE_TARGET_URL. 5) Commit and push the workflow file, and tell me what you connected.

Replace <my project ID> with this project's ID. If AI asks, just tell it. (If you copy from the "CI integration" card on the test-run tab, the project ID is already filled in.)

Connect it by hand

If you'd rather connect it yourself, here are the steps.

1. Issue a token — issue a CI-only token from My Page → MCP connection. This token is the key that starts verification.
2. Create the workflow file — create a .github/workflows/specnote-verify.yml file in your repository. Its contents come straight from the specnote_get_ci_workflow tool in the AI prompt above, already filled with your project's values.
3. Register the secret — in GitHub repository → Settings → Secrets and variables → Actions, register the token you just issued as a secret named SPECNOTE_TOKEN.
4. Register the target address — on the Variables tab of the same screen, put the address of the site to verify (a staging or preview address) into a variable named SPECNOTE_TARGET_URL.

Once these four are done, the workflow runs on its own every time you push code and starts verification.

Report mode ↔ Blocking mode

When you connect it, it starts in report mode. Even if verification fails, it doesn't block your code from merging — it just tells you the result. The single line continue-on-error: true in the workflow file does this.

Once you're used to it and your pass rate is stable, you can delete that line to switch to blocking mode. In blocking mode, a failed verification blocks the merge. Leaving it in blocking mode from the start can tie you up over a momentary false alarm, so we recommend switching to blocking mode only after your pass rate is stable.

Frequently asked questions

Does it work if the app only runs locally? Yes. You don't need a deployed address. In that case, CI briefly starts the app and opens a temporary passage (a tunnel) to verify. Tell the AI prompt to use "local mode" and it'll build it that way. That said, the temporary passage isn't guaranteed for speed or lifespan, so if you have a deploy or preview address, that one is more stable.

Does it cost anything? It's free for now. Verifications that run through CI don't use AI — they just replay in a fixed order — so no credits are spent.

What happens if I re-issue the token? The CI token has a single fixed name, so re-issuing it automatically retires the previous token and keeps only the new one alive. Feel free to re-issue whenever you've lost the token or want to rotate it. (After re-issuing, update the GitHub secret SPECNOTE_TOKEN to the new value too.)

Verification isn't running. The most common cause is the target address. Check that the site address you put in the SPECNOTE_TARGET_URL variable is one that's reachable right now. If the address has changed, just update that value to the new address.

For the basic way of running verification by pressing a button, see Running verification and reading results; if you haven't connected your code yet, see Connect your code first.