Rihpig

Posted on Jun 3 • Originally published at apidog.com

Apidog GitHub GitLab 연동 방법

API 사양은 Apidog에 있고 진실의 근원은 Git에 있다면, 두 위치를 항상 동기화해야 합니다. Apidog Git 통합을 사용하면 GitHub, GitLab, Azure DevOps 저장소를 연결해 OpenAPI 사양을 Git으로 푸시하고, 저장소 변경 사항을 다시 Apidog로 가져올 수 있습니다. 결과적으로 사양 변경 이력, 코드 리뷰, 백업을 Git 워크플로우 안에서 관리할 수 있습니다.

오늘 Apidog를 사용해 보세요

이 가이드는 Apidog Git 통합을 실제로 설정하고 운영하는 방법에 초점을 맞춥니다. 지원되는 공급자, 양방향 동기화와 자동 백업의 차이, 브랜치 전략, 권한 설정, 충돌 처리 방법을 순서대로 다룹니다. GitHub만 집중적으로 보고 싶다면 OpenAPI 사양을 GitHub와 동기화하는 방법을 참고하십시오.

Apidog Git 통합으로 할 수 있는 일

Apidog는 Git과 두 가지 방식으로 연동됩니다.

Spec-First 모드 동기화
- Apidog에서 OpenAPI YAML/JSON을 편집합니다.
- 변경 사항을 커밋하고 Git 브랜치로 푸시합니다.
- 저장소에서 변경된 사양을 다시 Apidog로 가져옵니다.
- 즉, 양방향 동기화입니다.
자동 Git 백업
- Apidog가 각 모듈의 OpenAPI/Swagger 파일을 주기적으로 Git 저장소에 푸시합니다.
- 사용자가 직접 커밋하거나 풀하지 않습니다.
- 즉, Apidog → Git 단방향 백업입니다.

기능	방향	트리거	적합한 경우
Spec-First 모드 동기화	양방향	수동 커밋/푸시, 수동 풀	API 사양을 코드처럼 리뷰하고 관리하려는 팀
자동 Git 백업	단방향	예약된 비피크 시간대	기존 워크플로우를 바꾸지 않고 Git 백업을 남기려는 팀

이후 문맥에서 동기화는 Spec-First 모드의 양방향 흐름을 의미하고, 백업은 예약된 단방향 내보내기를 의미합니다.

지원되는 Git 공급자

Apidog는 다음 공급자를 지원합니다.

공급자	인증 방식	참고
GitHub	OAuth 인증	개인 및 조직 저장소 지원. 조직 저장소는 관리자 승인이 필요할 수 있습니다.
GitLab	OAuth 인증	gitlab.com 및 Apidog에서 접근 가능한 자체 관리형 GitLab 지원
Azure DevOps	일반 Git 연결, HTTPS + 토큰	HTTPS 저장소 URL과 저장소 범위의 PAT로 연결

Azure DevOps는 일반 Git 연결을 사용합니다. GitHub나 GitLab이 아니더라도 HTTPS 기반 Git과 토큰 인증을 지원하는 호스트라면 같은 방식으로 연결할 수 있습니다.

Git 공급자 연결하기

기본 흐름은 다음과 같습니다.

Apidog에서 Git 공급자를 선택합니다.
공급자별 인증을 완료합니다.
저장소를 선택합니다.
사용할 브랜치를 선택합니다.
Apidog 프로젝트 또는 모듈을 해당 저장소 위치에 연결합니다.

GitHub 연결

GitHub는 OAuth로 연결합니다.

Apidog에서 GitHub 연결을 선택합니다.
GitHub 로그인 및 권한 부여 화면으로 이동합니다.
Apidog가 저장소를 읽고 쓸 수 있도록 권한을 승인합니다.
저장소와 브랜치를 선택합니다.

조직 저장소를 사용하는 경우 GitHub 조직 관리자가 서드파티 앱 접근을 승인해야 할 수 있습니다. 인증은 성공했지만 저장소가 보이지 않는다면 조직 승인 상태를 먼저 확인하십시오.

GitLab 연결

GitLab도 OAuth 방식입니다.

Apidog에서 GitLab 연결을 선택합니다.
GitLab 계정으로 로그인합니다.
저장소 접근 권한을 승인합니다.
저장소와 브랜치를 선택합니다.

자체 관리형 GitLab은 Apidog가 네트워크를 통해 해당 인스턴스에 접근할 수 있어야 합니다.

Azure DevOps 연결

Azure DevOps는 일반 Git 연결을 사용합니다.

필요한 값은 다음과 같습니다.

Repository HTTPS URL
Personal Access Token, PAT

PAT는 Azure DevOps에서 생성합니다. 저장소 코드에 대한 읽기/쓰기 권한을 부여하되, 필요한 프로젝트와 저장소로 범위를 제한하십시오.

권장 설정:

전체 계정 범위 토큰을 사용하지 않습니다.
대상 저장소에 필요한 최소 권한만 부여합니다.
토큰은 비밀 값으로 관리합니다.
팀원이 퇴사하거나 역할이 바뀌면 토큰을 취소하고 재발급합니다.

더 넓은 Git 기반 사양 관리 전략이 필요하다면 Git을 사용한 OpenAPI 버전 제어를 참고하십시오.

Spec-First 모드로 양방향 동기화하기

Spec-First 모드는 Apidog를 OpenAPI 사양 편집기이자 Git 클라이언트처럼 사용하게 해줍니다. 자세한 제품 문서는 공식 Apidog 문서에서 확인할 수 있습니다.

실제 작업 흐름은 다음과 같습니다.

Apidog에서 OpenAPI YAML 또는 JSON을 편집합니다.
실시간 유효성 검사로 잘못된 $ref, 누락된 필드 등을 확인합니다.
변경 사항을 커밋합니다.
연결된 Git 브랜치로 푸시합니다.
팀원이 저장소에서 변경한 내용이 있다면 Apidog로 풀합니다.

예를 들어 새 엔드포인트를 추가하려면 다음처럼 OpenAPI 문서를 수정합니다.

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

수정 후에는 다음 순서로 처리합니다.

edit spec → validate → commit → push

팀원이 Git 저장소에서 같은 사양을 수정했다면 다음 순서로 최신 상태를 가져옵니다.

pull from Git → review changes → continue editing

유지하고 싶지 않은 변경 사항은 커밋하기 전에 푸시되지 않은 편집을 버려 마지막 동기화 상태로 되돌릴 수 있습니다.

이 방식은 Git 네이티브 API 워크플로우의 핵심입니다. API 사양 변경도 코드 변경처럼 리뷰, 승인, 병합, 롤백 과정을 거치게 됩니다.

자동 Git 백업 설정하기

자동 Git 백업은 일상적인 편집 흐름을 바꾸지 않고 OpenAPI 사양의 버전 관리된 사본을 Git에 남기는 기능입니다.

동작 방식은 다음과 같습니다.

Apidog 모듈을 Git 저장소에 연결합니다.
백업 저장소와 브랜치를 지정합니다.
Apidog가 각 모듈의 OpenAPI/Swagger 파일을 내보냅니다.
시스템이 야간의 무작위 비피크 시간대에 Git으로 푸시합니다.

백업으로 저장되는 것은 해당 모듈의 현재 API 계약 스냅샷입니다. 각 백업은 Git 커밋으로 남기 때문에 다음 작업이 가능합니다.

지난주 사양과 오늘 사양 비교
특정 필드가 언제 변경되었는지 추적
필요한 경우 저장소에서 이전 버전 복원

주의할 점은 백업이 단방향이라는 것입니다.

Apidog → Git

Git 저장소에서 수정한 내용을 Apidog로 다시 가져오려면 자동 백업이 아니라 Spec-First 모드 동기화를 사용해야 합니다.

브랜치 전략 선택하기

Git 통합을 설정하기 전에 브랜치 전략을 정하십시오.

옵션 1: main 브랜치에 직접 동기화

간단한 팀이나 위험이 낮은 변경에 적합합니다.

Apidog → main

장점:

설정이 단순합니다.
별도 병합 과정이 없습니다.

단점:

리뷰 없이 사양이 바로 반영될 수 있습니다.
변경 통제가 약해질 수 있습니다.

옵션 2: 작업 브랜치에 동기화 후 PR 병합

대부분의 팀에는 이 방식이 더 안전합니다.

Apidog → api-spec/change-order-schema → Pull Request → main

장점:

사양 변경을 리뷰할 수 있습니다.
코드 변경과 같은 승인 프로세스를 적용할 수 있습니다.
충돌과 변경 이력을 더 명확하게 관리할 수 있습니다.

권장 패턴:

main
feature/api-orders-v2
feature/add-payment-schema
fix/order-response-required-field

저장소 구조 선택하기

저장소 구조는 팀 소유권과 API 개수에 따라 선택합니다.

API별 저장소

orders-api-spec/
payments-api-spec/
users-api-spec/

적합한 경우:

API마다 소유 팀이 다릅니다.
접근 권한을 좁게 관리해야 합니다.
사양 변경 이력을 API별로 분리하고 싶습니다.

모노레포

api-specs/
  orders/openapi.yaml
  payments/openapi.yaml
  users/openapi.yaml

적합한 경우:

플랫폼 팀이 여러 API를 함께 관리합니다.
API 간 검색과 리뷰를 한 저장소에서 처리하고 싶습니다.
공통 스키마나 표준을 함께 관리합니다.

모노레포를 사용할 때는 모듈별 경로를 명확히 분리하십시오. 자동 백업과 수동 동기화가 같은 파일을 덮어쓰지 않도록 디렉터리 구조를 예측 가능하게 유지하는 것이 중요합니다.

팀 권한 설정하기

Git 통합에서는 권한을 두 곳에서 관리해야 합니다.

Apidog 내부 권한
Git 공급자 권한

Apidog 권한

Apidog 프로젝트 설정에서 누가 동기화하고 푸시할 수 있는지 제한하십시오.

권장 정책:

사양 소유자: 편집 및 푸시 가능
리뷰어: 읽기 및 검토
일반 기여자: 필요 시 제한적 편집
외부 참여자: 읽기 전용

실수로 잘못된 사양을 푸시하지 않도록 푸시 권한은 최소 인원에게만 부여하는 것이 좋습니다.

Git 공급자 권한

GitHub와 GitLab은 OAuth를 승인한 사용자의 권한을 사용합니다. Azure DevOps와 일반 Git 연결은 PAT가 권한의 기준이 됩니다.

PAT 관리 원칙:

공유 문서나 채팅에 붙여넣지 않습니다.
대상 저장소로 범위를 제한합니다.
정기적으로 교체합니다.
퇴사자나 역할 변경이 있으면 즉시 취소합니다.
가능하면 개인 계정보다 관리 가능한 서비스 계정을 사용합니다.

병합 충돌과 드리프트 처리하기

Apidog는 실제 Git 커밋을 사용하므로 충돌도 일반적인 Git 충돌과 동일하게 처리합니다.

예를 들어 다음 상황을 생각해 볼 수 있습니다.

당신이 Apidog에서 Order 스키마를 수정합니다.
팀원이 Git 저장소에서 같은 Order 스키마를 수정하고 먼저 푸시합니다.
당신이 푸시하거나 풀할 때 같은 YAML 라인에서 충돌이 발생합니다.

이 경우 해결 방식은 일반 Git 충돌과 같습니다.

pull → resolve YAML conflict → validate OpenAPI → commit → push

충돌을 줄이는 방법:

푸시하기 전에 항상 최신 변경 사항을 풀합니다.
큰 사양 변경은 작은 단위로 나눕니다.
같은 스키마를 여러 명이 동시에 수정하지 않도록 작업 범위를 공유합니다.
PR 리뷰에서 YAML diff를 확인합니다.
Apidog의 실시간 유효성 검사로 병합 후 OpenAPI 구조가 깨지지 않았는지 확인합니다.

드리프트는 Apidog와 Git 저장소가 서로 다른 상태로 오래 유지되는 상황입니다. 동기화 표시기가 최신 상태가 아니라면 다음 중 하나일 가능성이 높습니다.

Apidog에 푸시되지 않은 변경 사항이 있음
Git 저장소에 풀하지 않은 변경 사항이 있음
연결된 브랜치가 예상과 다름

이 상태를 오래 방치하지 말고 바로 풀 또는 푸시로 정리하십시오.

문제 해결 체크리스트

증상	가능한 원인	해결 방법
권한 부여 실패 또는 저장소가 보이지 않음	조직이 타사 접근을 승인하지 않았거나 토큰 범위가 부족함	GitHub/GitLab 조직 관리자에게 앱 승인을 요청합니다. Azure DevOps는 읽기/쓰기 코드 범위로 PAT를 재발급합니다.
푸시가 거부됨	토큰 취소, 만료, 쓰기 권한 부족	공급자를 다시 인증하거나 새 PAT를 생성해 Apidog에 업데이트합니다.
푸시했지만 변경 사항이 보이지 않음	잘못된 브랜치에 연결됨	Apidog 프로젝트 설정에서 연결된 브랜치를 확인합니다.
“방금 동기화됨” 상태가 표시되지 않음	로컬 편집이 남아 있거나 풀할 변경 사항이 있음	보류 중인 편집을 커밋/푸시하거나 먼저 풀한 뒤 다시 동기화합니다.
병합 충돌 발생	같은 YAML 라인을 여러 명이 수정함	충돌을 해결하고 OpenAPI 문서가 유효한지 확인한 뒤 다시 동기화합니다.
백업이 실행되지 않음	예약된 비피크 시간대가 아직 도달하지 않음	다음 백업 주기를 기다리거나 저장소/브랜치 구성을 확인합니다.
원하지 않는 편집이 있음	커밋 전 실험 변경 사항	푸시되지 않은 편집을 버려 마지막 동기화 상태로 되돌립니다.

대부분의 문제는 인증과 권한에서 시작됩니다. 먼저 토큰이 활성 상태인지, 저장소 쓰기 권한이 있는지, 조직 승인이 완료되었는지 확인하십시오.

FAQ

동기화는 단방향인가요, 양방향인가요?

기능에 따라 다릅니다.

Spec-First 모드: 양방향
자동 Git 백업: 단방향

Spec-First 모드에서는 Apidog에서 Git으로 푸시하고 Git 변경 사항을 Apidog로 가져올 수 있습니다. 자동 백업은 Apidog가 사양을 Git으로 내보내기만 합니다.

내 사양은 어디에 저장되나요?

연결한 Git 저장소에 저장됩니다.

Spec-First 모드에서는 OpenAPI 문서가 연결된 브랜치에 커밋됩니다. 자동 백업에서는 각 모듈의 OpenAPI/Swagger 파일이 지정한 저장소와 브랜치에 커밋됩니다.

어떤 브랜치로 동기화해야 하나요?

일반적으로 다음 구성을 권장합니다.

main: 검토 완료된 표준 사양
feature/*: 진행 중인 사양 변경

사양 변경도 코드처럼 리뷰하려면 작업 브랜치에 동기화하고 PR을 통해 main에 병합하십시오.

토큰이 취소되면 어떻게 되나요?

Apidog가 Git 저장소에 쓸 수 없으므로 푸시와 백업이 실패합니다. 공급자를 다시 인증하거나 Azure DevOps 및 일반 Git 연결에서는 새 PAT를 생성해 Apidog에 업데이트하십시오.

결론

Apidog Git 통합은 두 가지 워크플로우를 제공합니다.

API 사양을 코드처럼 관리하려면 Spec-First 모드 양방향 동기화를 사용합니다.
기존 작업 방식을 유지하면서 Git 이력과 백업을 남기려면 자동 Git 백업을 사용합니다.

실무에서는 두 기능을 함께 사용하는 경우가 많습니다. Spec-First 모드로 리뷰 가능한 사양 변경 흐름을 만들고, 자동 백업으로 모듈별 스냅샷을 Git에 계속 남기면 됩니다.

시작 순서는 간단합니다.

Git 공급자 연결 → 저장소 선택 → 브랜치 선택 → 권한 설정 → 동기화 또는 백업 활성화

이렇게 하면 API 사양도 코드와 같은 위치에서 버전 관리, 리뷰, 복구할 수 있습니다.

DEV Community