GitHub Enterprise(온프레미스)를 활용한 서비스 아키텍처 인텔리전스

GitHub 앱을 생성하고 구성하세요

GHE 인스턴스에서 Settings → Developer Settings → GitHub Apps → New GitHub App 으로 이동합니다. GitHub 앱 생성에 대한 자세한 지침은 GitHub 앱 등록 관련 GitHub 문서를 참조하세요.

권한 설정

초기 동기화 시 원활한 데이터 가져오기와 이후 웹훅 이벤트의 효율적인 수신을 위해 앱 권한을 정확하게 구성하십시오. 앱 권한은 애플리케이션이 GitHub의 다양한 저장소 및 조직 리소스에 액세스할 수 있는 범위를 정의합니다. 이러한 권한을 맞춤 설정하면 보안을 강화하고 애플리케이션이 필요한 데이터에만 액세스하도록 보장하는 동시에 노출을 최소화할 수 있습니다. 적절한 설정을 통해 초기 데이터 동기화가 원활하게 이루어지고 이벤트 처리가 안정적으로 진행되어 애플리케이션이 GitHub 생태계와 최적으로 통합될 수 있습니다.

GitHub 앱 권한에 대한 자세한 지침은 GitHub 앱 권한 설정에 대한 GitHub 문서를 참조하세요.

필수 저장소 권한

데이터 동기화를 활성화하려면 아래에 표시된 대로 저장소 수준 권한을 정확하게 구성하십시오.

• 관리자 권한: 읽기 전용 ✓

• 확인: 읽기 전용 ✓

• 커밋 상태: 선택됨 ✓

• 내용: 선택됨 ✓

• 사용자 지정 속성: 선택됨 ✓

• 구현, 배치: 읽기 전용 ✓

• 메타데이터: 읽기 전용(필수) ✓

• 당겨주세요: 선택됨 ✓

• 웹훅: 읽기 전용 ✓

  필수 조직 권한

  다음과 같이 조직 수준 권한을 구성하십시오.

• 관리자 권한: 읽기 전용 ✓

• 사용자 지정 조직 역할: 읽기 전용 ✓

• 사용자 지정 속성: 읽기 전용 ✓

• 사용자 지정 저장소 역할: 읽기 전용 ✓

• 이벤트: 읽기 전용 ✓

• 회원: 읽기 전용 ✓

• 웹훅: 읽기 전용 ✓

  웹훅 이벤트 구독

  실시간 동기화 및 모니터링을 위해 아래 웹훅 이벤트를 표시된 대로 정확하게 선택하십시오.

  ✓ 다음 이벤트를 선택하세요:

• check_run - 실행 상태 업데이트를 확인하세요

• check_suite - 전체 구성 여부를 확인하세요

• commit_comment - 커밋에 대한 댓글

• create - 브랜치 또는 태그 생성

• custom_property - 팀 배정을 위한 사용자 지정 속성 변경

• custom_property_values - 사용자 지정 속성 값 변경

• delete - 브랜치 또는 태그 삭제

• deployment - 구현, 배포 활동

• deployment_review - 구현, 배포 검토 프로세스

• deployment_status - 구현, 배포 상태 업데이트

• fork - 저장소 포크 이벤트

• installation_target - GitHub 앱 설치 변경 사항

• label - 이슈 및 풀 리퀘스트의 레이블 변경

• member - 회원 프로필 변경

• membership - 회원 추가 및 삭제

• meta - GitHub 앱 메타데이터 변경 사항

• milestone - 주요 변경 사항

• organization - 조직 차원의 변화

• public - 저장소 가시성 변경 사항

• pull_request - 활동을 당겨주세요

• pull_request_review - 풀 요청 검토 활동

• pull_request_review_comment - 댓글 활동 검토

• pull_request_review_thread - 풀 요청 검토 스레드 활동

• push - 코드 푸시 및 커밋

• release - 발행물 및 업데이트

• repository - 저장소 생성, 삭제 및 수정

• star - 저장소 스타 이벤트

• status - 커밋 상태 업데이트

• team - 팀 생성 및 수정

• team_add - 팀원 추가

• watch - 저장소 감시 이벤트

  팁

  보안 모범 사례: 보안 위험을 줄이려면 최소 권한 접근 원칙을 따르고 통합 요구 사항에 필요한 최소한의 권한만 부여하십시오.

  웹훅 설정

  Webhook URL을 구성하고 보안 통신을 위한 맞춤형 대시보드 비밀을 생성하세요.

• Webhook URL: 수집기 서비스 구현, 배포에 따라 다음 형식을 사용합니다.

  • HTTP의 경우: http://your-domain-name/github/sync/webhook
  • HTTPS의 경우: https://your-domain-name/github/sync/webhook

  예: 수집기 서비스가 구현하다, 배포하다 at collector.yourcompany.com 인 경우 웹훅 URL은 다음과 같습니다. https://collector.yourcompany.com/github/sync/webhook

• 이벤트 시크릿: 웹훅 인증을 위한 안전한 임의 문자열(32자 이상)을 생성합니다. 이 값은 GITHUB_APP_WEBHOOK_SECRET 환경 변수에 필요하므로 저장해 두세요.

  키 생성 및 변환

1. GitHub 앱을 생성한 후에는 개인 키를 생성해야 합니다. GitHub 앱 설정에서 Generate a private key [개인 키 생성]을 클릭하세요. 앱은 자동으로 고유한 앱 ID와 개인 키 파일(.pem 형식)을 생성하고 다운로드합니다. 이 정보는 수집기 서비스 설정에 필요하므로 안전하게 보관하십시오.

2. 다운로드한 개인 키 파일을 DER 형식으로 변환한 다음 Base64로 인코딩하세요.

   1단계: .pem 파일을 DER 형식으로 변환합니다.

   bash

   카피

   $
   openssl rsa -outform der -in private-key.pem -out output.der

   2단계: DER 파일을 Base64로 인코딩합니다.

   bash

   카피

   $
   # For Linux/macOS
   $
   base64 -i output.der -o outputBase64
   $
   cat outputBase64  # Copy this output
   $
   
   $
   # For Windows (using PowerShell)
   $
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("output.der"))
   $
   
   $
   # Alternative for Windows (using certutil)
   $
   certutil -encode output.der temp.b64 && findstr /v /c:- temp.b64

   결과로 생성된 Base64 문자열을 복사하여 수집기 설정에서 GITHUB_APP_PRIVATE_KEY 환경 변수의 값으로 사용하십시오.

   ✓ 성공 지표:

• GitHub 앱이 성공적으로 생성되었습니다.
• 앱 ID와 개인 키는 안전하게 저장됩니다.
• 웹훅 URL이 구성되어 있고 접근 가능합니다.

환경 변수를 준비합니다.

수집기 서비스를 구현하거나 배포하기 전에 다음 정보를 수집합니다.

필수 환경 변수

선택적 SSL 환경 변수

다음은 API를 HTTPS로 만들기 위한 선택적 환경 변수입니다.

SSL 인증서 설정 지침

HTTPS 설정을 위해 신뢰할 수 있는 인증 기관(CA)으로부터 SSL 인증서를 받으려면 다음 단계를 따르십시오.

1. 개인 키와 인증서 서명 요청(CSR)을 생성합니다.

   bash

   카피

   $
   openssl req -new -newkey rsa:2048 -nodes -keyout mycert.key -out mycert.csr

2. 선택한 CA에 CSR 제출: mycert.csr 파일을 선택한 인증 기관(예: DigiCert, Let's Encrypt, GoDaddy)에 제출하세요.

3. 도메인 유효성 검사 완료: CA(인증 기관)의 지시에 따라 필요한 도메인 유효성 검사 단계를 모두 완료하십시오.

4. 인증서 다운로드: CA에서 발급된 인증서 파일(일반적으로 .crt 또는 .pem 파일)을 다운로드합니다.

5. PKCS12 키 저장소 생성: 인증서와 개인 키를 PKCS12 키 저장소로 결합합니다.

   bash

   카피

   $
   openssl pkcs12 -export -in mycert.crt -inkey mycert.key -out keystore.p12 -name mycert

6. 키스토어 사용: 생성된 keystore.p12 파일을 도커 설정의 SERVER_SSL_KEY_STORE 값으로 사용합니다.

수집기 서비스를 구현하다, 배포하다

수집기 서비스는 도커 이미지로 제공됩니다. 구현, 배포는 다음 두 가지 방법 중 하나로 수행될 수 있습니다.

옵션 A: 도커 컴포즈 사용 (권장)

서비스의 다운로드 및 구현, 배포를 자동화하는 도커 Compose 파일을 만듭니다.

1. 다음 내용을 포함하는 docker-compose.yml 파일을 생성하세요:

   version: '3.9'
   
   services:
     nr-ghe-collector:
       image: newrelic/nr-ghe-collector:tag # use latest tag available in dockerhub starting with v*
       container_name: nr-ghe-collector
       restart: unless-stopped
       ports:
         - "8080:8080"     # HTTP port, make 8443 in case of HTTPS
       environment:
         # Required environment variables
         - NR_API_KEY=${NR_API_KEY:-DEFAULT_VALUE}
         - NR_LICENSE_KEY=${NR_LICENSE_KEY:-DEFAULT_VALUE}
         - GHE_BASE_URL=${GHE_BASE_URL:-DEFAULT_VALUE}
         - GITHUB_APP_ID=${GITHUB_APP_ID:-DEFAULT_VALUE}
         - GITHUB_APP_PRIVATE_KEY=${GITHUB_APP_PRIVATE_KEY:-DEFAULT_VALUE}
         - GITHUB_APP_WEBHOOK_SECRET=${GITHUB_APP_WEBHOOK_SECRET:-DEFAULT_VALUE}
   
         # Optional SSL environment variables (uncomment and configure if using HTTPS)
         # - SERVER_SSL_KEY_STORE=${SERVER_SSL_KEY_STORE}
         # - SERVER_SSL_KEY_STORE_PASSWORD=${SERVER_SSL_KEY_STORE_PASSWORD}
         # - SERVER_SSL_KEY_STORE_TYPE=${SERVER_SSL_KEY_STORE_TYPE}
         # - SERVER_SSL_KEY_ALIAS=${SERVER_SSL_KEY_ALIAS}
         # - SERVER_PORT=8443
       #volumes: # Uncomment the line below if using SSL keystore
       #  - ./keystore.p12:/app/keystore.p12 # path to your keystore file
       network_mode: bridge
   
   networks:
     nr-network:
       driver: bridge

   카피

2. 도커 Compose 파일에서 DEFAULT_VALUE 플레이스홀더를 실제 값으로 바꿔 환경 변수를 설정하거나, 명령어를 실행하기 전에 시스템에 환경 변수를 생성하세요.

   주의

   비밀 정보가 포함된 환경 변수 파일은 절대로 버전 관리 시스템에 커밋하지 마십시오. 실제 운영 환경에서는 안전한 비밀 키 관리 방식을 사용하십시오.

3. 서비스를 시작하려면 다음 명령을 실행하십시오.

   bash

   카피

   $
   docker-compose up -d

   옵션 B: 도커 이미지 직접 실행

   도커 허브 레지스트리 에서 직접 도커 이미지를 다운로드하고 조직이 선호하는 CI/CD 파이프라인 또는 구현, 배포 방법을 사용하여 실행할 수 있습니다. 참고로 고객은 수집기 서비스를 시작할 때 위에 나열된 모든 환경 변수를 전달해야 합니다.

   ✓ 성공 지표:

• Collector 서비스가 실행 중이며 구성된 포트에서 접근 가능합니다.
• 도커 컨테이너 로그인은 오류 없이 성공적인 시작을 표시합니다.
• 서비스는 (설정된 경우) 상태 점검에 응답합니다.

조직에 GitHub 앱을 설치하세요

수집기 서비스가 실행된 후에는 통합하려는 특정 조직에 GitHub 앱을 설치해야 합니다.

1. GitHub Enterprise 인스턴스로 이동합니다.

2. Settings → Developer Settings → GitHub Apps 으로 이동하세요.

3. 1단계에서 생성한 GitHub 앱을 찾아서 클릭하세요.

4. 왼쪽 사이드바에서 Install App [앱 설치]를 클릭하세요.

5. 앱을 설치할 조직을 선택하세요.

6. 모든 저장소에 설치할지, 아니면 특정 저장소만 선택할지 결정하세요.

7. 설치를 완료하려면 Install [설치]를 클릭하십시오.

   ✓ 성공 지표:

• 웹훅 전달 내역은 GitHub 앱 설정에 표시됩니다.
• 수집기 서비스 로그에 인증 오류가 없습니다.

뉴렐릭 UI에서 통합 설정 완료

수집기 서비스가 실행되고 GitHub 앱이 GHE 조직에 설치되면 뉴럴릭 UI 의 안내에 따라 통합 설정을 완료하십시오.

1. 해당 GHE 조직이 뉴렐릭 UI 에 표시됩니다.

2. 초기 데이터 동기화를 시작하려면 First time sync [최초 동기화]를 클릭하세요.

3. (선택 사항) 수동으로 데이터를 동기화하려면 On-demand sync [주문형 동기화를] 클릭합니다.

   팁

   4시간마다 수동으로 데이터를 동기화할 수 있습니다. 동기화가 지난 4시간 이내에 발생한 경우 On-demand sync [주문형 동기화] 버튼은 비활성화됩니다.

4. 동기화 시작 메시지가 표시되면 Continue [계속을] 클릭하십시오. GitHub Enterprise Integration [GitHub Enterprise 통합] 화면에는 팀 수와 저장소 수가 표시되며 5초마다 새로 고쳐집니다. 모든 데이터를 완전히 가져오는 데 15-30분이 소요됩니다(소식 저장소 수에 따라 소요 시간이 달라질 수 있습니다).

   

   데이터 보기

   GitHub Enterprise Integration [GitHub Enterprise 통합] 화면에서:

• 가져온 팀 정보를 Teams 에서 보려면 Go to Teams [Teams로 이동]을 클릭하세요.
• Catalogs 에서 가져온 가져온 정보를 보려면, Go to Repositories [다음으로 이동] 을 클릭하세요.

팀 배정을 구성합니다(선택 사항).

GitHub Enterprise에서 teamOwningRepo 사용자 지정 속성으로 추가하면 GitHub 저장소를 팀에 자동으로 할당할 수 있습니다.

1. 조직 수준에서 사용자 정의 속성을 만들고 저장소 수준에서 사용자 정의 속성에 대한 값을 할당합니다. 또한, 조직 수준에서 여러 저장소에 대한 사용자 정의 속성을 동시에 설정할 수 있습니다.

2. 그런 다음 뉴렐릭 Teams에서 자동 소유권 기능을 활성화하고 태그 키로 team 사용해야 합니다.

   이 설정이 완료되면 뉴렐릭은 각 리포지터리를 해당 팀과 자동으로 매칭합니다.

   사용자 지정 속성을 만드는 방법에 대한 자세한 내용은 GitHub 문서를 참조하세요.