CI 자동 검증 연결하기

이게 뭔가요

배포하기 전에 자동으로 리허설을 한 번 돌리는 것이라고 생각하면 쉬워요. 지금까지는 검증을 사람이 직접 눌러서 돌렸어요. CI 연동을 해 두면, 코드가 바뀔 때마다(예: 새 코드를 올리거나 검토 요청을 열 때) Specnote가 알아서 시나리오를 한 번 검증해요.

여기서 CI란 코드를 올릴 때마다 정해진 검사를 자동으로 돌려 주는 장치예요. GitHub를 쓰신다면 GitHub Actions가 그 역할을 해요. Specnote는 그 자동 검사 한 자리에 "시나리오 검증"을 끼워 넣는 거예요.

한 가지 안심하셔도 되는 점이 있어요. 검증을 실제로 돌리는 건 Specnote 서버예요. 여러분의 코드가 도는 자리(CI)에서는 브라우저를 띄우거나 무거운 일을 하지 않아요. CI는 그저 "지금 검증해 줘" 하고 방아쇠만 당기고, 결과가 나올 때까지 기다렸다가 받아 오는 역할만 해요. 그래서 여러분 쪽 설정은 가볍고, 운영 비밀번호나 키가 넘어갈 일도 없어요.

검증이 끝나면 결과는 두 곳에 남아요.

• 검토 요청(PR) 화면 — 통과·실패 요약이 한국어로 붙어서, 코드를 합치기 전에 무엇이 깨졌는지 바로 보여요.
• 테스트 실행 탭 — 이번 검증이 하나의 실행 묶음으로 쌓여, 나중에 되짚어 볼 수 있어요.

AI에게 맡기기 (권장)

가장 쉬운 방법이에요. 아래 내용을 복사해서 평소 쓰는 AI 코딩 도구(Claude Code·Cursor 등)에 붙여넣기만 하면, AI가 연결에 필요한 일을 대신해요. 토큰 발급, 워크플로우 파일 만들기, 커밋까지 전부요.

Specnote 자동 검증을 이 저장소의 GitHub Actions에 연결해줘. 1) specnote_get_ci_workflow 도구로 워크플로우 파일 내용을 받아 .github/workflows/specnote-verify.yml 로 저장해줘 (specId 는 "<내 프로젝트 ID>", 배포/스테이징 주소가 있으면 standard, 로컬 개발 서버만 있으면 local 모드). 2) specnote_issue_ci_token 도구로 CI 전용 토큰을 발급해줘. 3) 발급된 토큰을 GitHub 저장소 비밀값 SPECNOTE_TOKEN 으로 등록해줘 — gh CLI 가 있으면 gh secret set SPECNOTE_TOKEN, 없으면 GitHub 저장소 → Settings → Secrets and variables → Actions 경로를 나에게 안내해줘. 4) 검증 대상 주소(스테이징/프리뷰)가 필요하면 나에게 물어보고 gh variable set SPECNOTE_TARGET_URL 로 등록해줘. 5) 워크플로우 파일을 커밋·푸시하고, 무엇을 연결했는지 알려줘.

<내 프로젝트 ID>는 지금 이 프로젝트의 ID로 바꿔 주세요. AI가 물어보면 그대로 알려 주면 돼요. (테스트 실행 탭의 "CI 연동" 카드에서 복사하면 프로젝트 ID가 이미 채워져 있어요.)

직접 연결하기

손수 연결하고 싶다면 절차는 이래요.

1. 토큰 발급 — 마이페이지 → MCP 연결에서 CI 전용 토큰을 발급해요. 이 토큰은 검증을 시작하는 열쇠예요.
2. 워크플로우 파일 만들기 — 저장소에 .github/workflows/specnote-verify.yml 파일을 만들어요. 내용은 위 AI 프롬프트의 specnote_get_ci_workflow 도구가 프로젝트 값이 채워진 상태로 그대로 내려줘요.
3. 비밀값 등록 — GitHub 저장소 → Settings → Secrets and variables → Actions 에서, 방금 발급한 토큰을 SPECNOTE_TOKEN 이라는 이름의 비밀값(secret)으로 등록해요.
4. 검증 주소 등록 — 같은 화면의 Variables 탭에서 SPECNOTE_TARGET_URL 이라는 변수(variable)에, 검증할 사이트 주소(스테이징이나 미리보기 주소)를 넣어요.

이 네 가지가 끝나면, 코드를 올릴 때마다 워크플로우가 저절로 돌면서 검증을 시작해요.

보고 모드 ↔ 차단 모드

연결하면 처음에는 보고 모드로 시작해요. 검증이 실패하더라도 코드를 합치는 걸 막지는 않고, 결과만 알려 주는 방식이에요. 워크플로우 파일 안의 continue-on-error: true 한 줄이 이 역할을 해요.

익숙해지고 통과율이 안정된 뒤에는, 그 한 줄을 지워서 차단 모드로 바꿀 수 있어요. 차단 모드에서는 검증이 실패하면 코드 합치기가 막혀요. 처음부터 차단 모드로 두면 잠깐의 오탐에도 발이 묶일 수 있으니, 통과율이 안정된 뒤에 차단 모드로 전환하는 것을 권해요.

자주 묻는 질문

로컬에서만 앱이 도는데도 되나요? 네. 배포된 주소가 없어도 돼요. 이 경우 CI가 잠깐 앱을 띄우고 임시 통로(터널)를 열어 검증해요. AI 프롬프트에서 "local 모드"라고 알려 주면 그 방식으로 만들어 줘요. 다만 임시 통로는 속도·수명이 보장되지 않아서, 배포나 미리보기 주소가 있다면 그쪽이 더 안정적이에요.

비용이 드나요? 지금은 무료예요. CI로 도는 검증은 AI를 쓰지 않고 정해진 순서대로 재생만 하기 때문에 크레딧이 빠지지 않아요.

토큰을 다시 발급하면 어떻게 되나요? CI 토큰은 이름이 하나로 고정돼 있어서, 다시 발급하면 이전 토큰은 자동으로 폐기되고 새 토큰만 살아 있어요. 토큰을 잃어버렸거나 새로 돌리고 싶을 때 부담 없이 재발급하면 돼요. (재발급하면 GitHub 비밀값 SPECNOTE_TOKEN도 새 값으로 바꿔 주세요.)

검증이 안 돌아요. 가장 흔한 원인은 검증 대상 주소예요. SPECNOTE_TARGET_URL 변수에 넣은 사이트 주소가 지금 접속되는 주소인지 확인해 주세요. 주소가 바뀌었다면 그 값을 새 주소로 고쳐 주면 돼요.

검증을 직접 눌러 돌리는 기본 방법은 검증 돌리고 결과 읽기에서, 코드 연결이 아직이라면 내 코드와 연결하기를 먼저 봐 주세요.