빠른 시작
MergeGate는 문서가 말하는 값(기본값, 한도, 가격, 기간)을 코드에 고정해 두고, PR이 그 값을 바꾸면 GitHub 체크를 🔴로 만듭니다. 판정은 결정적이며 LLM을 쓰지 않습니다.
설치 전에 보기: 공개 데모 저장소 bb4rjfl/mergegate-demo의 PR #2는 환불 기간을 7일에서 14일로 바꾸고, MergeGate 체크가 README·기획서가 말하는 7일과 어긋난다며 실패합니다.
무엇을 하고, 무엇을 하지 않나
| 합니다 | 하지 않습니다 |
|---|---|
| 스펙에 선언한 값과 코드의 값을 비교 (상수, 문자열, 배열, enum, 설정 객체, 라우트, 환경변수 기본값, 스키마 필드) | 문서 전체를 의미로 대조 |
| TypeScript · JavaScript(ES 모듈) | Python · Go · Java 등 (아직 지원 안 함) |
| 이 PR이 새로 만든 🔴만 실패 | 동작 · 권한 규칙 · 화면 흐름 검증 |
| 값을 확실히 읽지 못하면 🟡 (절대 막지 않음) | 추측으로 🔴 |
1. 가입하고 앱 설치
- 가입하기 — GitHub 또는 Google 계정.
- 안내에 따라 GitHub App MergeGate Checks를 설치합니다. 처음엔 "Only select repositories"로 저장소 하나만 고르는 걸 권합니다. 이용권 금액은 설치된 비공개 저장소 수로 정해집니다.
- 계정 · 플랜에서 14일 체험 시작을 누릅니다(카드 등록 없음, GitHub 가입 30일 이상, 한 사람·한 계정에 한 번).
앱을 설치하면 체험 전에도 한 번은 무료로(계정당 1회, 저장소 3개까지, 저장소마다 200MB 이하) 다음이 열립니다. 체험을 시작하면 나머지 저장소에도 열립니다.
- 이슈 1개 — 문서(README 등)에서 코드 값을 말하는 줄을 찾아 코드와 대조한 결과. 이미 틀린 줄은 그 값을 바꾼 커밋과 함께 보입니다.
- 스펙 초안 PR 1개 — 지금 맞는 줄의 값을 지키는
specs/파일. 검토하고 머지하면 다음 PR부터 지켜집니다.
2. 스펙 하나 써 보기
specs/features/F-001-refund.md:
---
schema: mergegate/feature@1
id: F-001
title: 환불 정책
status: active
assertions:
- id: A-F001-001
claim: "구매 후 7일 이내에만 환불할 수 있다"
type: const.equals
source: src/refund.ts#REFUND_WINDOW_DAYS
expect: 7
---
구매 후 7일 이내에만 환불할 수 있다. (산문은 사람이 읽습니다)
src/refund.ts의 export const REFUND_WINDOW_DAYS = 7;이 14로 바뀌는 PR에는 🔴와 함께 이 문장이 뜹니다. 문법 전체는 스펙 문법 레퍼런스에 있습니다.
3. 머지를 막으려면
specs/_config.yml에mode: block.- 브랜치 보호(또는 ruleset)에서
mergegate/spec-drift를 필수 체크로. specs/를 CODEOWNERS로 보호 — 같은 PR에서 스펙을 고치는 건 정상 흐름이라 막지 않고 체크에 따로 표시합니다.- 판정을 못 한 변경(시간 초과·일일 한도)도 막으려면
on_incomplete: fail.
설정은 PR의 base에서 읽습니다. PR이 스스로 체크를 끌 수 없습니다.
4. 터미널과 AI 에이전트
계정 · 플랜에서 API 토큰을 발급하면 같은 판정을 터미널·CI와 MCP(Claude Code, Cursor)에서 씁니다. → CLI · MCP
이용권이 끝나거나 서버가 멈추면
- 이용권이 없으면 판정하지 않고 neutral로 끝납니다. GitHub은 neutral을 통과로 봅니다(검사 없이 머지).
- MergeGate 서버가 응답하지 않으면 체크가 만들어지지 않아 필수 체크가 대기로 남습니다. 저장소 관리자가 우회 머지할 수 있습니다.
자주 걸리는 것
| 증상 | 원인 · 해결 |
|---|---|
| 🟡 "could not resolve" | 값이 함수 호출 · 환경 변수 · 다른 패키지에서 옵니다. 값을 이름 있는 상수로 꺼내 그걸 가리키세요. |
CommonJS(module.exports) 파일 |
ES 모듈 export만 읽습니다. |
| 모노레포 | source는 저장소 루트 기준 경로입니다(packages/api/src/x.ts#NAME). 상대 import는 깊이 3까지 따라갑니다. |
process.env.X ?? 기본값 |
env.default 타입으로 기본값을 고정할 수 있습니다. |
| 체크가 안 뜸 | 체험이나 이용권이 있는지, 저장소가 앱 설치 대상인지 확인하세요. 이용권 저장소 수를 넘은 비공개 저장소는 "not covered"로 뜹니다. |
보안·데이터 처리는 보안, 문의는 계정 페이지의 연락처로.