중복·역순 반영 방지
같은 Delivery와 같은 SHA의 중복 작업을 걸러내고, 작업 시점의 원격 Head가 다르면 과거 Push를 건너뜁니다.
GIT DOCUMENT SYNC
Git에 Push하면
내부 API 문서가 따라옵니다.
저장소, 브랜치와 OpenAPI 파일을 한 번 연결하세요. PC가 꺼져 있어도 서버가 새 커밋을 검증하고 내부 공식 문서와 버전 이력을 최신 상태로 유지합니다.
- GitHub · Bitbucket
- YAML · JSON
- 서버 자동 처리
실제 제품 화면
연결 상태와 반영 결과를 한곳에서 확인하세요.
각 연결 카드에서 저장소·브랜치·파일 경로·대상 문서·최근 커밋과 처리 결과를 함께 확인하고, 실패한 작업은 원인을 확인한 뒤 다시 동기화할 수 있습니다.
동작 원리
Push 한 번이 문서 버전이 되기까지.
웹훅 요청에 바로 문서 작업을 몰아넣지 않습니다. 요청을 검증하고 작업을 대기열에 남긴 뒤, 서버 작업기가 최신 커밋만 순서대로 처리합니다.
- 01
Push 수신
연결한 저장소의 Push 웹훅을 서버가 받습니다.
- 02
요청 검증
HMAC-SHA256 서명, 저장소와 브랜치, 중복 Delivery를 확인합니다.
- 03
명세 조회
최신 Head와 일치하는 커밋에서 지정한 OpenAPI 파일만 읽습니다.
- 04
문서 반영
유효성 검사 후 신규·변경 API를 공식 문서와 버전 이력에 반영합니다.
- 05
팀 알림
실제 변경이 있을 때만 승인 알림과 동기화 결과를 남깁니다.
부분 반영 없이 전체 검증
문법 오류, 지원하지 않는 스키마, 외부 $ref 또는 진행 중인 수동 수정 충돌이 있으면 일부 문서만 반영하지 않고 작업 전체를 중단합니다.
메서드·경로 기준 이어쓰기
기존 문서 연결을 선택하면 HTTP 메서드와 경로가 같은 API는 기존 문서 ID를 유지하고, 새로운 API만 추가합니다.
- 1
Git 메뉴에서 저장소 연결을 시작하세요
데스크톱 앱에서 팀 워크스페이스를 선택하고 Git 메뉴의 ‘저장소 연결’을 누릅니다. 연결과 해제는 워크스페이스 관리자만 할 수 있습니다.
- 2
저장소 URL을 입력하고 브라우저에서 인증하세요
GitHub 또는 Bitbucket 저장소 주소를 입력합니다. 공급자가 자동으로 판별되며, 브라우저에서 해당 저장소를 읽을 수 있는 계정으로 권한을 승인합니다.
- 3
기준 브랜치와 OpenAPI 경로를 선택하세요
main, release 같은 기준 브랜치를 고르고 저장소 루트 기준 파일 경로를 입력합니다. 예: docs/openapi.yaml 또는 openapi.json.
- 4
새 문서 또는 기존 문서 연결 방식을 정하세요
처음 가져오는 명세는 새 카테고리를 만들 수 있습니다. 이전에 연결했던 문서를 이어가려면 기존 카테고리를 선택해 문서 ID와 버전 이력을 유지합니다.
- 5
최초 동기화 결과를 확인하세요
연결 직후 현재 브랜치의 명세를 한 번 동기화합니다. 연결 카드에서 반영 커밋, 신규·변경 문서 수, 실패 사유를 확인할 수 있습니다.
공급자별 권한
필요한 범위만 승인합니다.
연동에 필요한 권한은 저장소 내용 읽기와 Push 감지입니다. SpecBridge는 저장소에 코드를 쓰거나 브랜치를 변경하지 않습니다.
공급자연동 방식필요 권한Push 감지
GitHubGitHub App 설치 후 사용자 인증Contents read · Metadata readApp의 서명된 Push 웹훅
BitbucketOAuth Consumer 인증Repository read · Webhook저장소별 HMAC 웹훅
SECURITY BY SCOPE
원본 코드를 가져오지 않고,
지정한 명세만 처리합니다.
저장소를 clone하거나 checkout하지 않습니다. 지정한 커밋의 OpenAPI 파일만 공급자 API에서 메모리로 읽고, 변환이 끝나면 원문을 저장하지 않습니다.
전체 보안 기준 보기- 서버에서만 처리
- 사용자 PC가 꺼져 있어도 서버 작업기가 동기화를 이어갑니다.
- 인증정보 암호화
- Git 인증정보와 웹훅 Secret은 서버 전용 키로 암호화해 보관합니다.
- 원본 명세 비저장
- 원본 YAML·JSON, 웹훅 원문과 전체 diff는 DB나 파일 저장소에 보관하지 않습니다.
- 외부 배포 분리
- Git 반영은 내부 문서를 최신화하며 외부 공유 버전을 자동 배포하지 않습니다.
결과 읽기
상태 메시지는 이렇게 보면 됩니다.
- 자동 승인 완료
- 명세 검사를 통과했고 신규 또는 변경 문서가 버전 이력과 함께 반영됐습니다.
- 최신 상태
- 명세 내용이 기존 문서와 같아 새 버전이나 알림을 만들지 않았습니다.
- 이전 Push 건너뜀
- 더 최신 Push가 이미 도착해 과거 커밋을 덮어쓰지 않았습니다.
- 확인 필요
- 경로, 권한, YAML·JSON 문법, 외부 참조 또는 수동 수정 충돌을 확인해야 합니다.
자주 묻는 질문
연결하기 전에 확인하세요.
Git에 Push하면 고객사가 보는 문서도 바로 바뀌나요?
아닙니다. Git 동기화는 내부 공식 문서와 버전 이력을 최신화합니다. 외부 공유 문서는 배포 관리자가 새 버전을 선택해 배포한 뒤에 바뀝니다.
저장소 전체 소스코드를 가져가나요?
아닙니다. 저장소를 clone하지 않고 지정한 커밋의 OpenAPI 파일 한 개만 공급자 API로 읽습니다. 원본 파일은 메모리에서 처리하며 DB·디스크·로그에 저장하지 않습니다.
여러 파일로 나뉜 OpenAPI도 연결할 수 있나요?
현재 자동 동기화는 하나의 YAML 또는 JSON 문서를 기준으로 합니다. 파일 내부 참조는 지원하지만 외부 파일 $ref가 있으면 안전을 위해 반영하지 않습니다.
브랜치 연결을 해제하면 문서도 삭제되나요?
아닙니다. 연결을 해제해도 생성된 카테고리, 문서와 버전 이력은 유지됩니다. 나중에 기존 문서 연결을 선택해 같은 이력을 이어갈 수 있습니다.
코드는 Git에, 문서는 항상 최신으로.