MergeGate

빠른 시작

MergeGate는 문서가 말하는 값(기본값, 한도, 가격, 기간)을 코드에 고정해 두고, PR이 그 값을 바꾸면 GitHub 체크를 🔴로 만듭니다. 판정은 결정적이며 LLM을 쓰지 않습니다.

설치 전에 보기: 공개 데모 저장소 bb4rjfl/mergegate-demo의 PR #2는 환불 기간을 7일에서 14일로 바꾸고, MergeGate 체크가 README·기획서가 말하는 7일과 어긋난다며 실패합니다.

무엇을 하고, 무엇을 하지 않나

합니다 하지 않습니다
스펙에 선언한 값과 코드의 값을 비교 (상수, 문자열, 배열, enum, 설정 객체, 라우트, 환경변수 기본값, 스키마 필드) 문서 전체를 의미로 대조
TypeScript · JavaScript(ES 모듈) Python · Go · Java 등 (아직 지원 안 함)
이 PR이 새로 만든 🔴만 실패 동작 · 권한 규칙 · 화면 흐름 검증
값을 확실히 읽지 못하면 🟡 (절대 막지 않음) 추측으로 🔴

1. 가입하고 앱 설치

  1. 가입하기 — GitHub 또는 Google 계정.
  2. 안내에 따라 GitHub App MergeGate Checks를 설치합니다. 처음엔 "Only select repositories"로 저장소 하나만 고르는 걸 권합니다. 이용권 금액은 설치된 비공개 저장소 수로 정해집니다.
  3. 계정 · 플랜에서 14일 체험 시작을 누릅니다(카드 등록 없음, GitHub 가입 30일 이상, 한 사람·한 계정에 한 번).

앱을 설치하면 체험 전에도 한 번은 무료로(계정당 1회, 저장소 3개까지, 저장소마다 200MB 이하) 다음이 열립니다. 체험을 시작하면 나머지 저장소에도 열립니다.

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. 머지를 막으려면

  1. specs/_config.yml에 mode: block.
  2. 브랜치 보호(또는 ruleset)에서 mergegate/spec-drift를 필수 체크로.
  3. specs/를 CODEOWNERS로 보호 — 같은 PR에서 스펙을 고치는 건 정상 흐름이라 막지 않고 체크에 따로 표시합니다.
  4. 판정을 못 한 변경(시간 초과·일일 한도)도 막으려면 on_incomplete: fail.

설정은 PR의 base에서 읽습니다. PR이 스스로 체크를 끌 수 없습니다.

4. 터미널과 AI 에이전트

계정 · 플랜에서 API 토큰을 발급하면 같은 판정을 터미널·CI와 MCP(Claude Code, Cursor)에서 씁니다. → CLI · MCP

이용권이 끝나거나 서버가 멈추면

자주 걸리는 것

증상 원인 · 해결
🟡 "could not resolve" 값이 함수 호출 · 환경 변수 · 다른 패키지에서 옵니다. 값을 이름 있는 상수로 꺼내 그걸 가리키세요.
CommonJS(module.exports) 파일 ES 모듈 export만 읽습니다.
모노레포 source는 저장소 루트 기준 경로입니다(packages/api/src/x.ts#NAME). 상대 import는 깊이 3까지 따라갑니다.
process.env.X ?? 기본값 env.default 타입으로 기본값을 고정할 수 있습니다.
체크가 안 뜸 체험이나 이용권이 있는지, 저장소가 앱 설치 대상인지 확인하세요. 이용권 저장소 수를 넘은 비공개 저장소는 "not covered"로 뜹니다.

보안·데이터 처리는 보안, 문의는 계정 페이지의 연락처로.