Rihpig

Posted on Aug 31 Originally published at apidog.com

GHE.com 레포지토리를 Apidog에 연결하는 방법

Apidog는 전용 *.ghe.com 도메인에서 호스팅되는 GitHub Enterprise Cloud 데이터 상주 테넌트에 연결할 수 있습니다. 조직 관리자가 테넌트와 OAuth 앱을 구성하면, 권한이 있는 프로젝트 사용자가 저장소를 연결하고 OpenAPI 가져오기, 백업, 동기화 워크플로를 사용할 수 있습니다.

지금 Apidog를 사용해 보세요

이 통합은 GitHub Enterprise Cloud 데이터 상주 SaaS 테넌트용입니다. GitHub Enterprise Server와 사용자 지정 GitHub 도메인은 지원하지 않습니다.

시작하기 전에

다음을 준비합니다.

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 앱 자격 증명을 구성합니다.

저장 후 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으로 백업 설정

프로젝트 설정에서 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는 자체 저장 및 배포 모델을 사용하는 별도의 연결된 서비스입니다. 데이터 상주 또는 규정 준수를 평가할 때는 두 공급업체의 최신 문서를 모두 검토하십시오.

DEV Community