GitHub Enterprise Cloud 리포지토리를 Azure SRE 에이전트에 연결

Important

Azure SRE 에이전트의 이 기능은 현재 미리 보기로 제공됩니다. 베타, 미리 보기로 제공되거나 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 약관은 Microsoft Azure 미리 보기에 대한 추가 사용 약관을 참조하세요.

BYO(Bring Your Own) GitHub 앱을 사용하여 GitHub Enterprise Cloud(<TENANT>.ghe.com) 또는 github.com 호스팅되는 리포지토리를 Azure SRE 에이전트에 연결합니다. 에이전트는 Azure Key Vault 저장되고 복사되지 않는 앱의 프라이빗 키에서 단기 설치 토큰을 발행합니다.

메모

BYO GitHub 앱은 github.com 및 *.ghe.com 호스트 모두에서 작동합니다. OAuth 또는 PAT를 사용한 github.comGitHub 커넥터 설정을 참조하세요.

BYO GitHub 앱 인증을 사용하는 경우

다음과 같은 경우 BYO 앱을 사용합니다.

• 조직에는 앱 기반 인증 및 키 양육권 제어가 필요합니다.
• *.ghe.com 리포지토리를 연결하고 있습니다(GHE 호스트에서는 OAuth 및 PAT를 사용할 수 없으므로 필요함).
• 사용자 토큰 대신 설치 토큰 기반 액세스를 원합니다.

사전 요구 사항

요구 사항	세부 정보
Azure SRE 에이전트	관리자 또는 표준 사용자 역할이 있는 실행 중인 상태의 에이전트
GitHub 앱	대상 호스트에서 만든 GitHub 앱(github.com 또는 <TENANT>.ghe.com)
GitHub 관리자 액세스	조직 또는 리포지토리 관리자 액세스로 GitHub 앱 범위 만들기, 설치 또는 확인
Azure Key Vault (애저 키 볼트)	GitHub 앱의 개인 키를 저장할 수 있는 보관소
관리형 아이덴티티	가져온 키에 대해 에이전트가 사용하는 신원에 대해 Key Vault Crypto User를 할당할 수 있는 기능

GitHub 앱 만들기

이미 올바른 권한이 있는 GitHub 앱이 있다면 Azure Key Vault에 개인 키 저장으로 이동하세요.

1. GitHub 호스트로 이동합니다.
   • github.com: 조직 >설정>개발자 설정>GitHub 앱>새 GitHub 앱으로 이동합니다
   • <TENANT>.ghe.com: GHE 인스턴스에서 동일한 경로
2. 앱 세부 정보를 입력합니다.
   • GitHub 앱 이름: 예: sre-agent-reader
   • 홈페이지 URL: https://sre.azure.com
   • 웹후크: 활성 선택 취소(에이전트가 웹후크를 사용하지 않음)
3. 사용 권한에서 다음을 설정합니다.
   • 리포지토리 권한 > 내용: 읽기 전용 (필수)
   • 리포지토리 권한 > 메타데이터: 읽기 전용 (자동 선택)
   • 선택적으로 Issues 및 Pull requests 읽기 권한을 추가합니다
4. 이 GitHub 앱을 설치할 수 있는 위치는 어디인가요? 아래에서 이 계정에서만을 선택합니다.
5. GitHub 앱 만들기를 선택합니다.
6. 앱 설정 페이지에 표시된 클라이언트 ID 를 확인합니다.

GitHub 앱 설치

1. GitHub 앱 설정 페이지의 왼쪽 사이드바에서 앱 설치를 선택합니다.
2. 조직을 선택합니다.
3. 모든 리포지토리를 선택하거나 특정 리포지토리를 선택합니다.
4. 설치를 선택합니다.

GitHub 앱 프라이빗 키 생성

1. GitHub 앱 설정 페이지에서 Private keys까지 스크롤합니다.
2. 프라이빗 키 생성을 선택합니다.
3. .pem 파일이 다운로드됩니다. 이 파일은 에이전트가 인증하는 데 사용하는 RSA 프라이빗 키입니다.

Caution

PEM을 안전하게 유지합니다. 다음 단계에서 이를 Key Vault에 업로드합니다. 리포지토리에 커밋하지 말고 공유하지 마세요.

프라이빗 키를 Azure Key Vault 저장

GitHub 앱의 개인 키를 비밀 키가 아닌 RSA 키로 불러오고, Sign 작업을 활성화하세요. 가져오기 전에 GitHub에서 다운로드한 PEM을 PKCS#8로 변환한 후, 성공적으로 가져오기 후에는 로컬 PEM 파일을 영구적으로 삭제하세요. 명령어에 대해서는 Key Vault에 개인 키 저장을(를) 참조하세요.

가져온 키의 키 식별자 URI를 복사합니다:

https://myvault.vault.azure.net/keys/my-github-app-key/<VERSION>

Tip

버전이 지정된 URI와 변환되지 않은 URI: 버전이 지정된 URI( /<VERSION> 접미사 포함)를 사용하여 특정 키 버전에 고정하거나 항상 최신 버전을 사용하도록 버전을 생략할 수 있습니다. 키를 회전할 때 에이전트가 URI를 업데이트하지 않고 새 버전을 자동으로 선택할 수 있도록 언버전되지 않은 URI를 사용합니다.

에이전트 ID에 대한 Key Vault 액세스 권한 부여

1. Azure 포털에서 Key Vault>AAM(액세스 제어) 엽니다.
2. Key Vault 접근을 위해 선택한 신원에 Key Vault Crypto User를 할당하세요. 할당 범위를 가져온 키로 지정하거나, 해당 앱에 전용인 경우에만 자격 증명 모음으로 지정합니다.
3. 역할 할당이 적용되기를 기다립니다.

코드 액세스에서 BYO 앱 구성

1. 포털에서 에이전트를 엽니다.
2. 빌드 + 설정>컨텍스트>코드 접근로 이동하세요.
3. 리포지토리 추가를 선택합니다.
4. 연결 단계에서 GitHub를 선택하고 예: 와 같은 전체 https://<TENANT>.ghe.com/owner/repo을 입력하세요.
5. 일치하는 자격 증명이 있다면, 다른 자격 증명을 설정하려면 다음을 사용하여 저장소 추가에서 새 연결을 선택하세요.
6. 연결 방법 아래에서 'GitHub 앱 사용'을 선택하세요.
7. 입력
   • 클라이언트 ID
   • 개인 키 URI (Key Vault): /keys/ URI이며 /secrets/ URI가 아닙니다
   • 선택적 Key Vault ID(또는 시스템 할당 유지)
8. 연결을 선택합니다.

마법사에서 자격 증명의 유효성을 검사합니다. 성공하면 GitHub 앱으로 연결됨 녹색 확인 표시가 표시됩니다.

메모

저장소 URL이 *.ghe.com 호스트를 사용하는 경우, 마법사는 'Use your GitHub App'을 선택합니다. OAuth 및 PAT는 GHE 호스트에 사용할 수 없습니다.

리포지토리 추가 및 연결 확인

1. 다음을 선택해 저장소 추가 화면을 열고, 저장소 항목과 표시 이름을 검토한 후 저장을 선택하세요.
2. 저장소가 코드 액세스 목록에 나타나고 Connection 열에 해당 연결이 표시되는지 확인하세요.
3. 채팅에서 테스트:

Get me recent issues from owner/repo.

여러 GitHub 앱에 대한 앱별 관리 ID

기본적으로 에이전트는 Key Vault 서명 작업을 위해 시스템 할당 관리 ID를 사용합니다. 여러 GitHub 앱을 관리하는 경우(예: GHE 인스턴스당 하나씩) 각 앱에 다른 사용자 할당 관리 ID 할당할 수 있습니다. 각 신원은 자신의 Key Vault 키에만 액세스가 필요합니다.

구성 단계 중 Key Vault ID 드롭다운에서 ID를 선택합니다.

GitHub 연결에 대한 다중 호스트 지원

여러 GitHub 호스트를 동일한 에이전트에 연결할 수 있습니다. 각 호스트에는 독립적인 인증이 있습니다.

• github.com OAuth, PAT 또는 BYO 앱 →
• contoso.ghe.com BYO 앱 →
• engineering.ghe.com → BYO 앱(다른 GitHub 앱 사용)

한 호스트의 연결을 끊는 것은 다른 호스트에 영향을 주지 않습니다.

Troubleshooting

증상	가능한 원인	수정
인증 유효성 검사 실패	잘못된 클라이언트 ID 또는 잘못된 호스트	코드 액세스에 입력된 동일한 호스트에서 앱이 만들어졌는지 확인합니다.
Key Vault 서명에 실패함	잘못된 키 URI 또는 누락된 키 권한	Sign이 활성화된 RSA /keys/ URI를 사용하여 선택한 ID에 Key Vault Crypto User를 부여합니다.
리포지토리가 코드 액세스에 실패로 표시됨	앱 사용 권한 누락 또는 설치 범위	메타데이터: 읽기 + 콘텐츠: 읽기 및 설치 범위를 확인합니다.
채팅 문제가 작동하지만 코드 액세스가 실패함	엔드포인트/경로 검사가 다릅니다.	연결 테스트를 다시 실행하고 메타데이터 권한을 확인합니다.

다음 단계:

GitHub 커넥터

관련 콘텐츠

• GitHub 커넥터
• GitHub 커넥터(OAuth 또는 PAT)
• MCP 커넥터 설정