Apidog는 전용 *.ghe.com 도메인에서 호스팅되는 GitHub Enterprise Cloud 데이터 상주 테넌트에 연결할 수 있습니다. 조직 관리자가 테넌트 및 OAuth 앱을 구성하면, 승인된 프로젝트 사용자는 저장소를 연결하고 지원되는 OpenAPI 가져오기, 백업 및 동기화 워크플로를 사용할 수 있습니다.
이 통합은 GitHub Enterprise Cloud 데이터 상주 SaaS 테넌트용입니다. GitHub Enterprise Server 또는 임의의 사용자 지정 GitHub 도메인은 지원하지 않습니다.
시작하기 전에
다음이 필요합니다:
- 통합에 액세스할 수 있는 Apidog Enterprise 조직
- Apidog의 조직 관리자 권한
https://company.ghe.com과 같은 루트*.ghe.com도메인에 있는 GitHub Enterprise Cloud 데이터 상주 테넌트- 해당 테넌트에서 OAuth 앱을 생성할 수 있는 권한
- 연결하려는 GitHub 조직, 저장소 및 브랜치에 대한 액세스 권한
저장소를 연결하는 사용자는 Apidog에서 관련 프로젝트 수준 Git 연결 권한도 가지고 있어야 합니다.
1단계: GHE.com 테넌트에서 OAuth 앱 생성
- 조직의 GHE.com 테넌트에 로그인합니다.
- OAuth 앱 설정을 엽니다.
- 새 OAuth 앱을 생성합니다.
- 식별 가능한 애플리케이션 이름을 입력합니다.
- 홈페이지 URL을 다음으로 설정합니다:
https://apidog.com - 인증 콜백 URL을 다음으로 설정합니다:
https://api.apidog.com/passport/github/callback - OAuth 앱을 등록합니다.
- 클라이언트 ID를 복사합니다.
- 클라이언트 시크릿을 생성하고 안전하게 복사합니다.
콜백 URL은 문서에 명시된 Apidog URL과 정확히 일치해야 합니다.
클라이언트 시크릿은 승인된 비밀 관리 시스템에 보관하십시오. 스크린샷, 티켓 또는 공유 문서에 넣지 마십시오.
2단계: Apidog에서 GHE.com 테넌트 구성
조직 관리자만 이 통합을 구성하거나 지울 수 있습니다.
- Apidog 조직을 엽니다.
- 조직 설정으로 이동합니다.
- GitHub 통합을 엽니다.
- GitHub Enterprise Cloud 데이터 상주를 찾아 구성을 선택합니다.
- GHE.com 호스트 URL을 입력합니다(예:
https://company.ghe.com). - 인증 방법으로 OAuth 앱을 선택합니다.
- OAuth 앱 클라이언트 ID를 입력합니다.
- OAuth 앱 클라이언트 시크릿을 입력합니다.
- 구성을 저장합니다.
조직 수준에서 테넌트 호스트 및 OAuth 앱 자격 증명을 구성합니다.
저장 후 Apidog는 구성된 호스트 URL을 표시합니다. 클라이언트 시크릿은 다시 표시되거나 미리 채워지지 않습니다.
나중에 구성을 편집할 때, 클라이언트 시크릿 필드를 비워두면 기존 비밀이 유지됩니다. 비밀을 교체할 때만 새 값을 입력하십시오.
3단계: Apidog 프로젝트에서 저장소 연결
조직 수준 구성이 완료된 후:
- 필요한 Apidog 프로젝트를 엽니다.
- Git 연결 또는 Git 가져오기 워크플로를 시작합니다.
- GitHub Enterprise Cloud를 선택합니다.
- 구성된 GHE.com 테넌트의 승인 페이지로 이동합니다.
- 로그인하고 OAuth 앱을 승인합니다.
- GitHub 조직을 선택합니다.
- 저장소와 브랜치를 선택합니다.
- 연결을 완료합니다.
승인은 표준 github.com이 아닌 구성된 GHE.com 테넌트에서 수행됩니다.
예상되는 조직 또는 저장소가 없는 경우, Apidog 조직 설정을 변경하기 전에 GitHub 계정의 액세스 권한과 OAuth 앱 승인을 확인하십시오.
4단계: OpenAPI 파일 가져오기
연결된 저장소에서 OpenAPI 또는 Swagger 파일을 가져오려면:
- Apidog 프로젝트에서 가져오기 워크플로를 시작합니다.
- OpenAPI/Swagger를 선택합니다.
- Git 저장소를 선택합니다.
- GitHub 조직, 저장소, 브랜치 및 파일을 선택합니다.
- 계속을 선택합니다.
- 기존 대상 모듈을 선택하거나 새 모듈을 생성합니다.
- 가져오기를 완료합니다.
- 결과를 수락하기 전에 가져온 엔드포인트와 스키마를 검토합니다.
프로젝트에 필요한 저장소, 브랜치 및 스펙 파일을 선택합니다.
특히 대상 모듈에 이미 API 정의가 포함되어 있는 경우, 첫 번째 가져오기에는 비프로덕션 프로젝트를 사용하십시오.
5단계: 지속적인 동기화 워크플로 선택
저장소 연결은 다양한 워크플로를 지원할 수 있습니다. 하나의 진실의 원천을 선택하고 팀을 위해 문서화하십시오.
| 워크플로 | 사용 시기 | 중요 동작 |
|---|---|---|
| 수동 가져오기 | 요청 시에만 변경 사항이 Apidog로 가져와집니다. | 각 가져오기 및 대상 모듈을 검토합니다. |
| 예약된 가져오기 | Git 파일이 소스로 유지되고 Apidog는 일정 간격으로 이를 새로 고쳐야 합니다. | 구성된 실행 모드에 따라 로컬 클라이언트 또는 자체 호스팅 러너를 통해 실행됩니다. |
| Git으로 백업 | Apidog 콘텐츠가 저장소 파일에 기록되어야 합니다. | 저장소, 브랜치 및 대상 파일 경로를 구성합니다. 자동 백업은 야간의 무작위로 예약된 비피크 시간대에 실행됩니다. |
| 스펙 우선 모드 | 스펙 파일이 진실의 원천이며 팀은 Git 중심 워크플로를 통해 편집합니다. | 이 모드는 현재 베타입니다. 웹훅 설치에는 일반적으로 저장소 관리자 권한이 필요합니다. |
명확한 충돌 해결 규칙 없이 동일한 파일에 대해 두 개의 상반되는 자동화된 워크플로를 구성하지 마십시오.
백업용:
- 프로젝트 설정에서 Git 연결을 생성하거나 선택합니다.
- 모듈의 개요 > API 스펙을 엽니다.
- OpenAPI 스펙을 추가하거나 선택합니다.
- Git 저장소로 백업을 활성화합니다.
- 저장소 연결, 브랜치 및 대상 파일 경로를 선택합니다.
- 구성을 저장합니다.
저장소 중심의 진실의 원천을 위해서는 예약된 가져오기를 사용하거나 스펙 우선 모드를 검토하십시오.
6단계: 통합 확인
작은 종단 간 테스트를 실행하십시오:
- 승인이 구성된 GHE.com 테넌트를 여는지 확인합니다.
- 예상되는 조직 및 저장소만 사용 가능한지 확인합니다.
- 알려진 OpenAPI 파일을 가져오고 결과를 원본과 비교합니다.
- 일회용 브랜치에서 선택된 백업 또는 동기화 방향을 테스트합니다.
- 브랜치 보호 및 저장소 권한이 예상대로 작동하는지 확인합니다.
- 동기화 로그 또는 오류를 검토합니다.
- OAuth 앱 클라이언트 시크릿을 교체하고 문서화된 업데이트 프로세스가 작동하는지 확인합니다.
웹훅 동기화를 사용하는 경우, 설치자가 저장소 관리자 권한을 가지고 있으며 예상되는 푸시 이벤트가 동기화를 트리거하는지 확인하십시오.
조직 설정 업데이트 또는 지우기
조직 관리자는 호스트 URL 또는 클라이언트 ID를 편집할 수 있으며, 새 값을 입력하여 클라이언트 시크릿을 교체할 수 있습니다.
조직 수준 구성을 제거하려면 조직 설정 > GitHub 통합을 열고 데이터 상주 통합을 찾아 설정 지우기를 선택합니다.
설정이 지워지면, 통합이 다시 구성될 때까지 사용자는 새 GitHub Enterprise Cloud 연결을 생성할 수 없습니다. 기존 연결은 토큰 상태 및 조직 설정에 따라 재구성 또는 재승인이 필요할 수 있습니다.
문제 해결
| 문제 | 확인할 사항 |
|---|---|
| 통합 옵션을 사용할 수 없습니다. | 조직이 엔터프라이즈 기능에 액세스할 수 있는지, 그리고 본인이 조직 관리자인지 확인하십시오. |
| OAuth에서 콜백 오류가 반환됩니다. | OAuth 앱 콜백이 https://api.apidog.com/passport/github/callback과 정확히 일치하는지 확인하십시오. |
| 승인 시 github.com이 열립니다. | 조직 수준 호스트가 의도된 루트 *.ghe.com 테넌트인지 확인하십시오. |
| 저장소가 누락되었습니다. | 승인된 GitHub 사용자의 조직 및 저장소 액세스 권한과 OAuth 제한 사항을 확인하십시오. |
| 프로젝트 사용자가 연결을 생성할 수 없습니다. | 사용자가 필요한 프로젝트 수준 Git 연결 권한을 가지고 있는지 확인하십시오. |
| 가져오기 또는 동기화 실패 | 선택한 브랜치, 파일 경로, 파일 형식, 저장소 권한 및 동기화 로그를 확인하십시오. |
보안 및 데이터 상주 경계
- 조직 관리자만 GHE.com 통합을 구성하거나 지울 수 있습니다.
- 클라이언트 시크릿은 구성 후 표시되지 않습니다.
- 프로젝트 권한은 여전히 누가 Git 연결을 생성하거나 업데이트할 수 있는지 제어합니다.
- OAuth 승인은 구성된 GHE.com 테넌트를 통해 발생합니다.
- 요청된 OAuth 권한에는 조직, 저장소, 브랜치를 읽고, 파일을 가져오고, 백업을 작성하고, 동기화 워크플로에 필요한 경우 저장소 훅을 관리하는 데 필요한 액세스 권한이 포함될 수 있습니다.
데이터 상주 테넌트를 연결한다고 해서 GitHub 또는 Apidog 관련 데이터의 모든 범주가 한 지역에 남아 있다고 단독으로 증명할 수는 없습니다. GitHub는 상주 서비스로 커버되는 데이터와 관련 예외 사항을 문서화합니다. Apidog는 자체 저장 및 배포 모델을 가진 별도의 연결된 서비스입니다. 데이터 상주 또는 규정 준수 평가의 일환으로 두 공급업체의 현재 문서를 검토하십시오.
관련 API 거버넌스 튜토리얼:
이 튜토리얼은 엔터프라이즈 API 워크스페이스를 거버넌스하기 위한 보완 제어 기능을 다룹니다:
- API 거버넌스 프레임워크 — 소유권, 제어, 증거 및 수명 주기 결정을 연결합니다.
- Microsoft Entra ID를 사용한 SAML 그룹 매핑 — ID 공급자 그룹에서 팀 액세스를 할당합니다.
- 시크릿 스캐너 — 지원되는 Apidog 자산에서 노출될 수 있는 자격 증명을 검토합니다.
- 감사 로그 — 관리 조직 활동을 조사하고 내보냅니다.
- SCIM 프로비저닝 — ID 수명 주기를 통해 조직 사용자를 관리합니다.
- 엔터프라이즈 정책 — 자격 증명, 멤버십, SSO 세션 및 초대 제어를 구성합니다.
- 셀프 서비스 API 팀 — 소유권 감독을 유지하면서 멤버가 생성한 팀을 허용합니다.
- GitHub Enterprise Cloud 통합 — OpenAPI 워크플로를 위해 지원되는 GHE.com 저장소를 연결합니다.
관련 공식 문서: