본문으로 이동

GIT DOCUMENT SYNC

Git에 Push하면
내부 API 문서가 따라옵니다.

저장소와 브랜치를 연결하고 OpenAPI 파일 또는 AI 코드 분석을 선택하세요. 새 API를 추가하고 기존 문서의 ID와 버전 이력을 이어서 갱신합니다.

  • GitHub · Bitbucket
  • YAML · JSON
  • AI 코드 분석

실제 제품 화면

연결 상태와 반영 결과를 한곳에서 확인하세요.

각 연결 카드에서 저장소·브랜치·파일 경로·대상 문서·최근 커밋과 처리 결과를 함께 확인하고, 실패한 작업은 원인을 확인한 뒤 다시 동기화할 수 있습니다.

연결된 Git 브랜치와 OpenAPI 문서 동기화 상태를 보여주는 SpecBridge 실제 제품 화면
실제 제품 UI안내용 예시 저장소와 데이터이미지를 누르면 원본 크기로 볼 수 있습니다.

동작 원리

Push 한 번이 문서 버전이 되기까지.

웹훅 요청에 바로 문서 작업을 몰아넣지 않습니다. 요청을 검증하고 작업을 대기열에 남긴 뒤, 서버 작업기가 최신 커밋만 순서대로 처리합니다.

  1. 01

    Push 수신

    연결한 저장소의 Push 웹훅을 서버가 받습니다.

  2. 02

    요청 검증

    HMAC-SHA256 서명, 저장소와 브랜치, 중복 Delivery를 확인합니다.

  3. 03

    명세 조회

    최신 Head와 일치하는 커밋에서 지정한 OpenAPI 파일만 읽습니다.

  4. 04

    문서 반영

    유효성 검사 후 신규·변경 API를 공식 문서와 버전 이력에 반영합니다.

  5. 05

    팀 알림

    실제 변경이 있을 때만 승인 알림과 동기화 결과를 남깁니다.

중복·역순 반영 방지

같은 Delivery와 같은 SHA의 중복 작업을 걸러내고, 작업 시점의 원격 Head가 다르면 과거 Push를 건너뜁니다.

부분 반영 없이 전체 검증

문법 오류, 지원하지 않는 스키마, 외부 $ref 또는 진행 중인 수동 수정 충돌이 있으면 일부 문서만 반영하지 않고 작업 전체를 중단합니다.

메서드·경로 기준 이어쓰기

기존 문서 연결을 선택하면 HTTP 메서드와 경로가 같은 API는 기존 문서 ID를 유지하고, 새로운 API만 추가합니다.

  1. 1

    Git 메뉴에서 저장소 연결을 시작하세요

    데스크톱 앱에서 팀 워크스페이스를 선택하고 Git 메뉴의 ‘저장소 연결’을 누릅니다. 연결과 해제는 워크스페이스 관리자만 할 수 있습니다.

  2. 2

    저장소 URL을 입력하고 브라우저에서 인증하세요

    GitHub 또는 Bitbucket 저장소 주소를 입력합니다. 공급자가 자동으로 판별되며, 브라우저에서 해당 저장소를 읽을 수 있는 계정으로 권한을 승인합니다.

  3. 3

    기준 브랜치와 문서 생성 방식을 선택하세요

    기준 브랜치를 고르고 OpenAPI 파일 동기화 또는 AI 코드 분석을 선택합니다. OpenAPI는 YAML·JSON 경로를, AI는 분석할 소스 폴더와 사용할 Codex·Claude Code를 지정합니다. 외부 공유 API만 문서화하려면 API 경로를 /openapi/처럼 지정하세요.

  4. 4

    새 문서 또는 기존 문서 연결 방식을 정하세요

    처음 가져오는 명세는 새 카테고리를 만들 수 있습니다. 이전에 연결했던 문서를 이어가려면 기존 카테고리를 선택해 문서 ID와 버전 이력을 유지합니다.

  5. 5

    최초 동기화 결과를 확인하세요

    OpenAPI는 최초 명세를 자동 반영합니다. AI는 커밋을 분석해 신규·기존 문서 변경을 비교하고, 문서에 반영을 누르면 같은 문서 ID의 새 버전으로 저장합니다.

공급자별 권한

필요한 범위만 승인합니다.

연동에 필요한 권한은 저장소 내용 읽기와 Push 감지입니다. SpecBridge는 저장소에 코드를 쓰거나 브랜치를 변경하지 않습니다.

공급자연동 방식필요 권한Push 감지
GitHubGitHub App 설치 후 사용자 인증Contents read · Metadata readApp의 서명된 Push 웹훅
BitbucketOAuth Consumer 인증Repository read · Webhook저장소별 HMAC 웹훅

SECURITY BY SCOPE

원본 코드를 가져오지 않고,
지정한 명세만 처리합니다.

저장소를 clone하거나 checkout하지 않습니다. OpenAPI 방식은 지정한 명세를, AI 방식은 선택한 폴더의 소스를 정확한 커밋에서 메모리로 읽습니다. AI 분석은 지정한 PC의 AI 연결을 사용합니다.

전체 보안 기준 보기
방식에 맞게 처리
OpenAPI는 서버가 자동 처리합니다. AI는 앱에서 분석·반영하며, PC가 꺼져 있으면 새 커밋을 분석 대기로 유지합니다.
인증정보 암호화
Git 인증정보와 웹훅 Secret은 서버 전용 키로 암호화해 보관합니다.
원본 명세 비저장
원본 YAML·JSON, 웹훅 원문과 전체 diff는 DB나 파일 저장소에 보관하지 않습니다.
외부 배포 분리
Git 반영은 내부 문서를 최신화하며 외부 공유 버전을 자동 배포하지 않습니다.

결과 읽기

상태 메시지는 이렇게 보면 됩니다.

자동 승인 완료
명세 검사를 통과했고 신규 또는 변경 문서가 버전 이력과 함께 반영됐습니다.
커밋 분석 대기
AI 방식에서 새 커밋을 감지했습니다. 앱에서 분석하고 변경 내용을 확인해 기존 문서에 반영하세요.
최신 상태
명세 내용이 기존 문서와 같아 새 버전이나 알림을 만들지 않았습니다.
이전 Push 건너뜀
더 최신 Push가 이미 도착해 과거 커밋을 덮어쓰지 않았습니다.
확인 필요
경로, 권한, YAML·JSON 문법, 외부 참조 또는 수동 수정 충돌을 확인해야 합니다.

자주 묻는 질문

연결하기 전에 확인하세요.

Git에 Push하면 고객사가 보는 문서도 바로 바뀌나요?

아닙니다. Git 동기화는 내부 공식 문서와 버전 이력을 최신화합니다. 외부 공유 문서는 배포 관리자가 새 버전을 선택해 배포한 뒤에 바뀝니다.

저장소 전체 소스코드를 가져가나요?

OpenAPI 방식은 지정한 명세 한 개만 읽습니다. AI 방식은 선택한 폴더의 소스만 읽어 지정한 AI에 전달합니다. 원본 소스와 명세는 서버 DB·디스크·로그에 저장하지 않습니다. AI는 소스 80개·16만 자까지 지원합니다.

여러 파일로 나뉜 OpenAPI도 연결할 수 있나요?

현재 자동 동기화는 하나의 YAML 또는 JSON 문서를 기준으로 합니다. 파일 내부 참조는 지원하지만 외부 파일 $ref가 있으면 안전을 위해 반영하지 않습니다.

브랜치 연결을 해제하면 문서도 삭제되나요?

아닙니다. 연결을 해제해도 생성된 카테고리, 문서와 버전 이력은 유지됩니다. 나중에 기존 문서 연결을 선택해 같은 이력을 이어갈 수 있습니다.

코드는 Git에, 문서는 항상 최신으로.

첫 저장소를 연결해 보세요.

무료 플랜으로 시작