중복·역순 반영 방지
같은 Delivery와 같은 SHA의 중복 작업을 걸러내고, 작업 시점의 원격 Head가 다르면 과거 Push를 건너뜁니다.
GIT DOCUMENT SYNC
저장소와 브랜치를 연결하고 OpenAPI 파일 또는 AI 코드 분석을 선택하세요. 새 API를 추가하고 기존 문서의 ID와 버전 이력을 이어서 갱신합니다.
동작 원리
웹훅 요청에 바로 문서 작업을 몰아넣지 않습니다. 요청을 검증하고 작업을 대기열에 남긴 뒤, 서버 작업기가 최신 커밋만 순서대로 처리합니다.
연결한 저장소의 Push 웹훅을 서버가 받습니다.
HMAC-SHA256 서명, 저장소와 브랜치, 중복 Delivery를 확인합니다.
최신 Head와 일치하는 커밋에서 지정한 OpenAPI 파일만 읽습니다.
유효성 검사 후 신규·변경 API를 공식 문서와 버전 이력에 반영합니다.
실제 변경이 있을 때만 승인 알림과 동기화 결과를 남깁니다.
같은 Delivery와 같은 SHA의 중복 작업을 걸러내고, 작업 시점의 원격 Head가 다르면 과거 Push를 건너뜁니다.
문법 오류, 지원하지 않는 스키마, 외부 $ref 또는 진행 중인 수동 수정 충돌이 있으면 일부 문서만 반영하지 않고 작업 전체를 중단합니다.
기존 문서 연결을 선택하면 HTTP 메서드와 경로가 같은 API는 기존 문서 ID를 유지하고, 새로운 API만 추가합니다.
데스크톱 앱에서 팀 워크스페이스를 선택하고 Git 메뉴의 ‘저장소 연결’을 누릅니다. 연결과 해제는 워크스페이스 관리자만 할 수 있습니다.
GitHub 또는 Bitbucket 저장소 주소를 입력합니다. 공급자가 자동으로 판별되며, 브라우저에서 해당 저장소를 읽을 수 있는 계정으로 권한을 승인합니다.
기준 브랜치를 고르고 OpenAPI 파일 동기화 또는 AI 코드 분석을 선택합니다. OpenAPI는 YAML·JSON 경로를, AI는 분석할 소스 폴더와 사용할 Codex·Claude Code를 지정합니다. 외부 공유 API만 문서화하려면 API 경로를 /openapi/처럼 지정하세요.
처음 가져오는 명세는 새 카테고리를 만들 수 있습니다. 이전에 연결했던 문서를 이어가려면 기존 카테고리를 선택해 문서 ID와 버전 이력을 유지합니다.
OpenAPI는 최초 명세를 자동 반영합니다. AI는 커밋을 분석해 신규·기존 문서 변경을 비교하고, 문서에 반영을 누르면 같은 문서 ID의 새 버전으로 저장합니다.
공급자별 권한
연동에 필요한 권한은 저장소 내용 읽기와 Push 감지입니다. SpecBridge는 저장소에 코드를 쓰거나 브랜치를 변경하지 않습니다.
SECURITY BY SCOPE
저장소를 clone하거나 checkout하지 않습니다. OpenAPI 방식은 지정한 명세를, AI 방식은 선택한 폴더의 소스를 정확한 커밋에서 메모리로 읽습니다. AI 분석은 지정한 PC의 AI 연결을 사용합니다.
전체 보안 기준 보기결과 읽기
자주 묻는 질문
아닙니다. Git 동기화는 내부 공식 문서와 버전 이력을 최신화합니다. 외부 공유 문서는 배포 관리자가 새 버전을 선택해 배포한 뒤에 바뀝니다.
OpenAPI 방식은 지정한 명세 한 개만 읽습니다. AI 방식은 선택한 폴더의 소스만 읽어 지정한 AI에 전달합니다. 원본 소스와 명세는 서버 DB·디스크·로그에 저장하지 않습니다. AI는 소스 80개·16만 자까지 지원합니다.
현재 자동 동기화는 하나의 YAML 또는 JSON 문서를 기준으로 합니다. 파일 내부 참조는 지원하지만 외부 파일 $ref가 있으면 안전을 위해 반영하지 않습니다.
아닙니다. 연결을 해제해도 생성된 카테고리, 문서와 버전 이력은 유지됩니다. 나중에 기존 문서 연결을 선택해 같은 이력을 이어갈 수 있습니다.
코드는 Git에, 문서는 항상 최신으로.