Quick start
MergeGate pins the values your docs state (defaults, limits, prices, windows) to the code and turns the GitHub check 🔴 when a pull request changes one. The verdict is deterministic; no LLM is involved.
See it before installing: in the public demo repository bb4rjfl/mergegate-demo, PR #2 changes the refund window from 7 to 14 days and the MergeGate check fails it, because the README and the PRD still say 7.
What it does and does not do
| Does | Does not |
|---|---|
| Compare the values you declare in a spec with the code (constants, strings, arrays, enums, config objects, routes, env defaults, schema fields) | Compare whole documents by meaning |
| TypeScript · JavaScript (ES modules) | Python, Go, Java… (not yet) |
| Fail only 🔴 that this pull request introduced | Check behaviour, permission rules or flows |
| Say 🟡 when a value cannot be read with certainty (never blocks) | Guess a 🔴 |
1. Sign up and install the app
- Sign up with GitHub or Google. (The sign-up, account and checkout pages are in Korean for now.)
- Install the GitHub App MergeGate Checks when asked. Start with "Only select repositories" and one repository: a pass is priced by the private repositories installed.
- On your account page, press 14일 체험 시작 ("start 14-day trial"; no card; GitHub account at least 30 days old; once per person and per account).
Installing the app gets this once for free, even before the trial (per account, up to three repositories of 200 MB or less); starting the trial covers the rest. Each repository gets:
- One issue — the doc lines (README and friends) that state a value from the code, compared with it. Lines already wrong come with the commit that moved the value.
- One draft spec PR —
specs/files pinning the lines that hold today. Review and merge it, and the next PR is checked.
2. Write one spec
specs/features/F-001-refund.md:
---
schema: mergegate/feature@1
id: F-001
title: Refund policy
status: active
assertions:
- id: A-F001-001
claim: "Refunds are allowed for 7 days after purchase"
type: const.equals
source: src/refund.ts#REFUND_WINDOW_DAYS
expect: 7
---
Refunds are allowed for 7 days after purchase. (Humans read the prose.)
A PR that changes export const REFUND_WINDOW_DAYS = 7; to 14 shows 🔴 with this sentence. The full syntax is in the spec reference.
3. To block the merge
mode: blockinspecs/_config.yml.- Make
mergegate/spec-drifta required status check (branch protection or a ruleset). - Protect
specs/with CODEOWNERS — updating a spec in the same PR is normal, so it is listed on the check, not blocked. - To also stop changes MergeGate could not judge (timeout, daily limit):
on_incomplete: fail.
Settings are read from the PR's base; a PR cannot switch its own check off.
4. Terminal and AI agents
Issue an API token on your account page and use the same verdict in your terminal, CI and over MCP (Claude Code, Cursor). → CLI · MCP
When the pass ends or the server is down
- Without a pass MergeGate does not judge and concludes neutral; GitHub treats neutral as passing (merges go through unchecked).
- If the MergeGate server does not answer, no check run is created and a required check stays pending; a repository admin can bypass it.
Common snags
| Symptom | Cause · fix |
|---|---|
| 🟡 "could not resolve" | The value comes from a call, an env read or another package. Give it a named constant and point at that. |
CommonJS (module.exports) file |
Only ES module exports are read. |
| Monorepo | source paths are from the repository root (packages/api/src/x.ts#NAME); relative imports are followed three levels deep. |
process.env.X ?? default |
Pin the default with the env.default type. |
| No check appears | Check that the account has a trial or a pass and the repository is installed. A private repository beyond the pass's count shows "not covered". |
Security and data handling: Security.