GitHub Enterprise Server
설계·설치부터 Entra 연동·CI/CD·운영까지

전체 흐름과 적용 경계

구조도 읽기: SAML은 브라우저 로그인, SCIM은 Entra 서비스의 계정 생성·변경, 라이선스 파일은 서버의 한도·만료, Connect는 서버 사용량 보고입니다. Runner는 GHES 밖에서 작업을 실행하고 Blob에 작업 로그·artifact를 저장합니다. 화살표가 연결돼 있어도 해당 기능의 인증·권한·실제 통신이 자동으로 완료되는 것은 아닙니다.

먼저 구분해야 하는 제품과 계정

단계별 통과 기준

작업을 했다는 기억이나 체크 표시가 아니라 아래 증거로 판단합니다. 미사용 기능은 사유와 승인자를 남겨 N/A로 처리합니다.

작업 분류와 문서 동작

삽화는 설명용 개념도이며 실제 구축 화면이 아닙니다. 공식 화면 이미지는 해당 문서의 예시로 별도 출처를 표시합니다. UI·명령·라이선스 조건은 설치 버전과 계약에 따라 달라질 수 있으므로 변경 전 해당 버전 원문을 재확인합니다.

명령 복사와 체크리스트는 문서 보조 기능입니다. 실제 고객 환경의 실행 결과가 아닙니다.

순서대로 따라 하는 12단계

아래 순서는 VMware 기반 GHES + Entra SAML/SCIM을 기준으로 합니다. Cloud 병용·Actions·Packages·Copilot은 계약과 사용 목적에 따라 선택합니다. 기존 환경에서는 처음부터 재설치하지 말고 현재 단계의 설정·증거를 읽은 뒤 필요한 변경만 승인받습니다.

STEP 04 / 12 · 기본 순서 · 조작 전 승인 확인

04. GHES 설치와 관리 접근

담당

가상화·GHES 운영자

준비값

승인 이미지·라이선스·DNS/TLS·Console/SSH 복구 준비

작업 위치

vSphere → GHES Management Console → 관리 SSH

1. 지원 이미지로 VM 생성

   공식 OVA의 버전·무결성을 확인하고 Deploy OVF Template으로 배포합니다. 전원 투입 전 승인 자원·root 용량·별도 빈 data 디스크·네트워크 매핑을 대조합니다. OS를 따로 설치하지 않습니다.

2. 최초 설정 보호·초기화

   설치 담당자만 접근하도록 제한한 뒤 전원을 켭니다. https://github.example.com/setup의 최초 설정에서 라이선스를 올리고 Console root 암호를 정합니다. FQDN·Time·TLS를 구성하고 승인된 Save settings → 적용 완료 후 첫 웹 관리자 계정을 즉시 생성합니다.

3. 관리 접근 확인

   관리 SSH 공개키를 등록하고 ssh -p 122 admin@HOSTNAME으로 버전·시각·라이선스를 조회합니다. 웹 관리자, Console 자격, SSH admin을 서로 다른 접근으로 확인합니다. 기본 서비스·HTTPS·비상 로그인을 시험합니다.

4. 기존 서버의 라이선스 갱신은 별도 경로

   재설치하지 않습니다. 아래 L1/L2처럼 Update license → License file → Upload를 사용하고 백그라운드 반영 후 한도·유효성을 재조회합니다. 전체 OS 재부팅을 자동 후속 단계로 추가하지 않습니다.

L1 · User licenses → Update license

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 상태부터 읽습니다. GHES Enterprise settings → Settings → License에서 현재 좌석·만료일을 확인하고, 승인된 갱신 때만 Update license로 이동합니다.

② 입력 / 대조할 값 · Input

대상 GHES는 https://github.example.com 같은 승인된 호스트입니다. 발급 대상·좌석 수·유효기간을 계약 및 새 라이선스 파일과 대조합니다.

③ 확인할 결과 · Expected

같은 GHES의 라이선스 업로드 화면으로 이동합니다. 링크를 여는 것만으로 라이선스가 갱신되지는 않습니다.

예시 범위·주의: 진입 링크만 표시한 공식 예제입니다. Unlimited Licenses·소비 좌석·2024년 만료일은 예시이며 실제 사용 권한이나 현재 상태가 아닙니다.

L2 · License file 선택·업로드

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 라이선스를 먼저 확인합니다. 신규 설치·갱신 승인 후 License file을 선택하고 발급받은 .ghl 파일을 지정한 다음 Upload합니다.

② 입력 / 대조할 값 · Input

승인된 GHES용 라이선스 파일만 사용합니다. 파일 내용·계약 식별자·키는 문서나 공유 화면에 복사하지 않습니다.

③ 확인할 결과 · Expected

업로드 후 적용된 좌석·유효기간을 다시 확인합니다. 파일 선택 화면이나 버튼만으로 적용 성공을 판단하지 않습니다.

예시 범위·주의: 공식 예제의 Running version 3.17.3, No seat restrictions, Clustering enabled, 2026년 만료일은 설치 권장값이 아닙니다. 출처는 GHES 3.21 문서이나 원 캡처의 UI는 다를 수 있습니다.

다음 단계로 넘어갈 조건: 실제 버전·유효 키·HTTPS·관리 접근·비상 복구가 확인됐습니다. PAYG 등 계약상 Connect 선행 조건이 있으면 STEP 08의 연결을 이 시점에 먼저 확인합니다.

상세 설정·명령 보기 → 다음: STEP 05 →순서 목록으로 ↑

STEP 05 / 12 · 기본 순서 · 조작 전 승인 확인

05. Entra 앱·SAML 구성

담당

Entra 관리자 + GHES 관리자

준비값

비상 계정·앱 Object ID·파일럿·GHES FQDN

작업 위치

Entra Enterprise apps / GHES Authentication

1. GHES 비상 계정부터 준비

   기존 계정 전환 영향을 검토하고 Phase 4의 절차로 built-in scim-admin·Console·SSH 복구 접근을 확보합니다. 기존 SAML에서 필요한 setup 옵션은 선택만 하지 말고 승인된 Save settings와 적용 성공까지 확인합니다.

2. Entra의 대상 테넌트·앱 식별

   Enterprise applications에서 신규 승인 시 GitHub Enterprise Server 갤러리 앱을 추가합니다. (Legacy)는 사용하지 않습니다. 기존 앱이면 새로 복제하지 말고 정확한 Object ID와 목적지를 확인합니다. GHES SAML과 SCIM에는 동일한 GHES 앱을 사용하고 Cloud EMU 앱은 별개로 유지합니다.

S1 · Entra ID → Enterprise applications

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Entra 관리 센터에서 디렉터리를 확인한 뒤 Entra ID → Enterprise apps(Enterprise applications)를 엽니다.

② 입력 / 대조할 값 · Input

이번 GHES 인증·프로비저닝용 테넌트를 읽기 확인합니다. App registrations 목록과 구분합니다.

③ 확인할 결과 · Expected

대상 테넌트의 Enterprise application 목록으로 이동합니다.

예시 범위·주의: 메뉴 진입용 공식 캡처입니다. 신규 앱 생성이나 GHES 연결 완료를 보여주지 않습니다.

S2 · All applications에서 기존 GHES 앱 찾기

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Search by application name or object ID에서 승인된 기존 GHES 앱을 검색합니다. 신규 구축 승인이 있을 때만 New application으로 별도 진행합니다.

② 입력 / 대조할 값 · Input

앱 이름·Object ID와 SAML/SCIM 목적지를 대조합니다. Cloud EMU·Copilot 앱을 GHES 앱 대신 선택하지 않습니다.

③ 확인할 결과 · Expected

첫 검색 결과가 아니라, 대상 GHES와 연결된 앱의 Overview를 확인합니다.

예시 범위·주의: 목록·검색 위치 예시입니다. 화면의 앱명은 공식 fixture이며 운영 대상이 아닙니다. 조회 실패를 이유로 기존 앱을 복제하지 않습니다.

S3 · Overview: Application ID와 service principal Object ID

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

선택한 Enterprise application → Overview에서 ID를 읽습니다.

② 입력 / 대조할 값 · Input

Application ID는 client ID입니다. 이 화면의 Object ID는 해당 테넌트의 service principal ID이며 App registrations의 Object ID와 다릅니다.

③ 확인할 결과 · Expected

SAML·SCIM용 앱과 조회한 service principal이 같은 대상임을 확인합니다.

예시 범위·주의: Exchange 공식 문서의 Room Booking Tool(RoomBookingTool) 앱 예시입니다. ID 위치 설명용 구형 Azure AD 화면이며 GHES 앱 또는 현재 테넌트의 캡처가 아닙니다.

1. 인증 전환 전 일반 파일럿 할당

   Users and groups에서 승인된 일반 파일럿을 할당합니다. 기존 환경 전환이면 필요한 기존 사용자 범위도 검토합니다. 일반 사용자 생성 문제를 Owner 부여로 우회하지 않습니다.

F1 · Users and groups: 할당·Role 읽기

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 Users and groups 목록을 먼저 읽습니다. 승인된 신규 할당만 Add user/group → 대상 선택 → Select → Select a role(제공될 때) → Assign으로 진행합니다.

② 입력 / 대조할 값 · Input

사용자/그룹 Object ID·직접 할당·그룹 직접 멤버·현재 Role을 대조합니다. Entra 앱 Owners와 GHES enterprise owner 앱 역할은 다릅니다.

③ 확인할 결과 · Expected

필요한 파일럿만 의도한 역할로 할당됩니다. 앱 할당만으로 GHES 사용자 생성이나 저장소 접근 완료를 선언하지 않습니다.

예시 범위·주의: Microsoft Entra SAML Toolkit 1 공식 fixture입니다. 할당 진입 화면만 보이며 사용자 선택창·확장된 Role 목록·최종 Assign 화면은 없습니다. 전원 Owner 부여나 임의 app role 생성은 하지 않습니다.

1. SP URL과 claim 입력

   Single sign-on → SAML에서 아래 기본 URL·claim을 구성합니다. objectidentifier와 SCIM externalId는 같은 사용자 객체여야 하며 NameID와는 별도 필드입니다.

S4 · Basic SAML Configuration: GHES URL

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

같은 GHES 앱 → Single sign-on → SAML에서 기존 값을 읽습니다. 신규 구축 또는 승인된 수정 때만 Basic SAML Configuration → Edit → Save합니다.

② 입력 / 대조할 값 · Input

Identifier (Entity ID): https://github.example.com | Reply URL (ACS): https://github.example.com/saml/consume | Sign on URL: https://github.example.com/sso. example.com은 설명용이며 실제 승인 호스트로 모두 일치시킵니다.

③ 확인할 결과 · Expected

Entity ID·ACS·Sign-on URL이 같은 GHES를 가리킵니다. Cloud의 /enterprises/slug나 Entra tenant ID를 GHES Entity ID로 넣지 않습니다.

예시 범위·주의: 공식 기본 설정 예시이며 현재 대상의 저장 결과가 아닙니다. 기존 인증을 변경하기 전에 비상 접근과 파일럿·되돌리기 절차를 준비합니다.

S5 · Attributes & Claims: NameID와 objectidentifier

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Attributes & Claims → Edit에서 기존 매핑을 읽습니다. 변경·저장은 승인된 신규 구성 또는 수정일 때만 수행합니다.

② 입력 / 대조할 값 · Input

Unique User Identifier(NameID)·UPN과 별개로 http://schemas.microsoft.com/identity/claims/objectidentifier → Entra 사용자 Object ID → SCIM externalId의 일치를 대조합니다.

③ 확인할 결과 · Expected

같은 사용자 객체가 SAML과 SCIM에서 연결됩니다. 표시 이름·메일·NameID가 같다는 이유만으로 externalId가 맞다고 판단하지 않습니다.

예시 범위·주의: 기본 claim 일부만 표시한 공식 예시입니다. objectidentifier가 안 보인다고 없다고 단정하지 말고 상세 설정을 읽으세요. administrator=true 예제를 무조건 적용하거나 Owner를 강제 부여하지 않습니다.

1. IdP 인증서·URL을 GHES에 연결

   Base64 공개 인증서, Login URL, Microsoft Entra Identifier를 수집해 GHES Management Console → Authentication → SAML의 Verification certificate·Single sign-on URL·Issuer에 연결합니다. 변경 승인 후 저장·적용 완료를 확인합니다. 아래 캡처는 Entra 값 위치이며 GHES 화면을 재구성한 것이 아닙니다.

S6 · SAML Signing Certificate: Base64 공개 인증서

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 활성 인증서·만료일을 읽고 SAML Signing Certificate → Certificate (Base64) → Download를 선택합니다.

② 입력 / 대조할 값 · Input

Thumbprint·유효기간·활성 서명키를 대조합니다. GHES SAML verification certificate용 공개 인증서이며 TLS 서버 인증서나 Federation Metadata XML과 다릅니다.

③ 확인할 결과 · Expected

승인된 구성에 사용할 공개 인증서를 준비합니다. 다운로드만으로 GHES 인증서가 교체되지는 않습니다.

예시 범위·주의: 인증서 다운로드 위치의 공식 예시입니다. 표시된 ID·만료일은 fixture입니다. 교체는 별도 승인 후 IdP 활성 키·GHES 신뢰·비상 접근을 함께 검증합니다.

S7 · IdP Login URL·Identifier → GHES SAML 설정

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

SAML 하단 Set up [앱명]에서 기존 Login URL과 Microsoft Entra Identifier를 읽습니다. 승인된 구성 때만 해당 값을 GHES에 입력·저장합니다.

② 입력 / 대조할 값 · Input

Entra Login URL → GHES Single sign-on URL. Microsoft Entra Identifier → GHES Issuer. 이 IdP issuer는 https://github.example.com이라는 GHES Entity ID와 다릅니다.

③ 확인할 결과 · Expected

IdP URL·issuer·공개 인증서가 같은 테넌트/앱 설정과 맞습니다. 승인된 저장 후 SCIM 대상 사용자의 프로비저닝을 먼저 확인하고 별도 브라우저로 파일럿 SSO를 시험합니다.

예시 범위·주의: 공식 fixture의 tenant GUID·URL을 복사하지 않습니다. 이 캡처는 Entra 값 위치이며 GHES Save settings 또는 실제 SSO 성공 화면이 아닙니다.

다음 단계로 넘어갈 조건: SAML URL·issuer·인증서·파일럿 할당·복구 접근이 일치합니다. SCIM 활성 환경의 실제 SSO 완료는 STEP 06의 계정 생성 후 확인합니다.

상세 설정·명령 보기 → 다음: STEP 06 →순서 목록으로 ↑

STEP 06 / 12 · 기본 순서 · 조작 전 승인 확인

06. SCIM 파일럿·자동 동기화

담당

Entra 앱 운영자 + GHES 관리자

준비값

동일 GHES 앱·SCIM PAT·파일럿 Object ID·정확한 UTC

작업 위치

Entra Provisioning / GHES 계정·관리 SSH

1. SCIM 자격·대상 설정

   승인된 GHES setup 계정의 classic PAT에 scim:enterprise를 사용합니다. 공식 절차대로 SCIM을 활성화하고 같은 Entra GHES 앱의 Automatic configuration에 GHES Tenant URL과 토큰을 입력합니다. 토큰은 금고에서 전달하며 문서·로그·캡처에 넣지 않습니다.

F2 · Provisioning: 기존 configuration 확인

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

GHES 앱 → Provisioning에서 기존 configuration을 먼저 선택합니다. 신규 구축 승인 때만 New configuration을 사용합니다.

② 입력 / 대조할 값 · Input

앱·대상 URL·job 상태·마지막 주기와 Attribute mapping, Provisioning logs, Provision on demand 진입 위치를 확인합니다.

③ 확인할 결과 · Expected

SAML과 동일한 GHES 앱의 configuration을 식별합니다. 오류 진단을 위해 Start/Restart 또는 중복 configuration 생성을 하지 않습니다.

예시 범위·주의: 새 configuration 진입을 보여주는 Preview UI 예시입니다. 기존 job 실행 증거가 아닙니다. 구형 UI에서는 Automatic → Admin Credentials가 바로 보일 수 있습니다.

S8 · Admin Credentials: Tenant URL·Test Connection

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 configuration → Admin Credentials를 읽습니다. 승인된 연결 시험만 Test Connection으로 실행하고, 신규/변경 승인 때만 Create 또는 Save합니다.

② 입력 / 대조할 값 · Input

Tenant URL: https://github.example.com/api/v3/scim/v2. Secret Token: •••••••• (마스킹 유지·복사 금지). 신규 입력은 승인된 GHES setup user의 classic PAT(scim:enterprise)를 보안 경로로 취급하며 문서에 붙여넣지 않습니다.

③ 확인할 결과 · Expected

연결 시험의 UTC·결과를 기록합니다. 성공은 연결/인증 확인이지 사용자 생성·역할 반영 성공이 아닙니다.

예시 범위·주의: 빈 입력란의 공식 예시이며 실제 토큰은 없습니다. GHES 3.21의 /api/v3/scim/v2를 기준으로 하며 Learn의 축약 표기 /api/v3/scim, Cloud api.github.com/scim/v2/enterprises/…, 8443 콘솔 URL과 혼동하지 않습니다.

1. 연결 시험 후 파일럿 범위·매핑 저장

   Test Connection 성공과 실제 GHES 수신 로그를 확인한 뒤 신규 구성의 Save/Create를 진행합니다. 사용자 externalId/userName/active/roles, 직접 할당·보안그룹 직접 멤버와 Scope를 확인하고 Sync only assigned users and groups 및 승인된 소규모 파일럿으로 제한합니다.

F3 · Properties: Scope·알림·삭제 방지

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 Properties/Settings와 Attribute mapping을 읽습니다. 신규 또는 승인된 수정 때만 편집·Apply/Save합니다.

② 입력 / 대조할 값 · Input

Provisioning scope: Sync only assigned users and groups. 알림·accidental deletion threshold를 승인 정책과 대조합니다. 별도 매핑 상세에서 externalId, userName, active, roles 및 필터를 확인합니다.

③ 확인할 결과 · Expected

의도한 소규모 파일럿만 범위에 포함되고 역할·활성 상태·삭제 방지 조건이 설명됩니다. Scope 전체 확대나 전체 Restart를 기본 해결책으로 사용하지 않습니다.

예시 범위·주의: 공식 예제의 threshold 500과 Preview 상태는 권장값이 아닙니다. roles/externalId 상세 매핑 화면은 없으므로 재구성하지 않았습니다. 실제 앱이 제공하는 매핑·역할을 별도로 읽습니다.

1. 일반 파일럿 한 명 온디맨드

   정확한 사용자 Object ID를 확인해 한 번 실행합니다. 계정 생성·수정·비활성화가 가능한 변경 작업입니다. 장기 bearer PAT 방식은 이를 위해 정상 자동 job을 Stop할 필요가 없습니다. 새 할당 전파에는 수 분 걸릴 수 있으며 통상 30초 미만 안내는 완료 SLA가 아닙니다.

F6 · Provision on demand: 승인된 파일럿 선택

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 GHES 앱 → Provision on demand에서 대상 한 명을 검색하고 Object ID·할당·범위·예상 작업을 읽습니다. 승인 후에만 Provision을 실행합니다.

② 입력 / 대조할 값 · Input

동명이인을 피하기 위해 사용자 Object ID로 대조합니다. 변경 전 active·역할과 예상 Create/Update/Disable 등 작업을 확인합니다.

③ 확인할 결과 · Expected

승인된 한 명의 실제 작업 결과를 열어 확인할 수 있어야 합니다. 온디맨드는 읽기 시험이 아니라 실제 계정 변경입니다.

예시 범위·주의: AHCustom 공식 fixture의 그룹 멤버 2명 선택 예시입니다. 단일 사용자 생성 화면이 아니며 두 명을 그대로 선택하라는 지시도 아닙니다. 메뉴·선택 흐름만 참고합니다.

F7 · Perform action·View details: 실제 작업 판정

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

실제 파일럿의 온디맨드 결과에서 Perform action → View details를 읽습니다. 결과 확인만을 위해 다시 Provision하지 않습니다.

② 입력 / 대조할 값 · Input

Action·Status·Target ID·변경 속성·UTC를 대조하고 GHES SCIM identity, active, 역할을 별도로 확인합니다.

③ 확인할 결과 · Expected

실제 사용자 작업의 성공 후 파일럿 SAML 로그인·Org/저장소 권한을 따로 검증합니다. Skip이나 Test Connection 성공을 사용자 생성으로 해석하지 않습니다.

예시 범위·주의: AHCustom의 Group membership operations에서 두 멤버 추가를 보여주는 공식 fixture입니다. GHES 단일 사용자 생성 또는 Role 강제 반영 성공 캡처가 아닙니다.

1. 프로비저닝 로그와 GHES를 대조

   해당 앱·사용자·실행 UTC의 Action/Status/Steps/Target ID를 읽습니다. Success/Create, Update, Disable/Delete, Skipped를 구분하고 GHES identity·active·SSO와 대조합니다. Entra Change ID를 GHES request ID로 간주하지 않습니다.

F4 · Provisioning logs: 대상·시각·Action·Status

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Provisioning logs에서 실제 GHES 앱·사용자·할당 이후 시각으로 필터링하고 Status 전체를 읽습니다.

② 입력 / 대조할 값 · Input

사용자 Object ID·UTC·Create/Update/Disable/Delete/Skipped·오류 detail을 구분합니다. 성공만 필터링해 누락을 숨기지 않습니다.

③ 확인할 결과 · Expected

해당 사용자의 이벤트 유무와 작업 종류를 설명하고 같은 시각의 GHES 기록과 연결합니다. 로그가 없다고 재생성이나 Restart부터 하지 않습니다.

예시 범위·주의: Salesforce·Google 등 여러 앱의 공식 예제입니다. 보이는 이름·성공 건수는 fixture이며 실제 GHES 결과가 아닙니다.

F5 · Steps: 범위·매칭·대상 작업

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

대상 provisioning 이벤트를 열고 Steps와 세부 속성을 읽습니다.

② 입력 / 대조할 값 · Input

범위 판정·매칭·실패 단계·Target ID·변경 속성·오류 detail을 대조합니다. Change ID와 GHES request ID가 같다고 가정하지 않습니다.

③ 확인할 결과 · Expected

동일 사용자의 동일 UTC 작업으로 원인을 좁힙니다. 읽기 진단과 승인된 복구 변경을 분리합니다.

예시 범위·주의: Box 대상의 성공 Steps 공식 예시입니다. GHES 성공 증거 또는 현재 장애 원인 캡처가 아닙니다.

1. Owner·자동 동기화 검증 후 확대

   운영 Owner가 필요하면 비상 접근을 유지한 채 Disable administrator demotion/promotion 제어·역할 매핑을 상세 절차대로 조정·적용합니다. 승인된 파일럿 범위로 Start provisioning하고 정기 동기화의 실제 roles·GHES Owner·로그인을 확인합니다. 온디맨드 성공만으로 역할 동기화 완료를 판단하지 않습니다. 이미 Running이면 전체 Restart하지 않습니다.

다음 단계로 넘어갈 조건: 파일럿의 계정 생성·활성·SSO, 필요한 운영 Owner와 비상 접근이 확인됐고 자동 job 상태·오류 분기가 기록됐습니다.

상세 설정·명령 보기 → 다음: STEP 07 →순서 목록으로 ↑

STEP 08 / 12 · 선택·조건부 · 조작 전 승인 확인

08. GitHub Connect·사용량 동기화

담당

GHES·Cloud enterprise 관리자

준비값

연결 자격·올바른 Cloud enterprise·개인정보/egress 승인

작업 위치

GHES GitHub Connect / GHEC Licensing

1. 연결 자격·목적지부터 확인

   양쪽 enterprise 관리 권한·계약 자격·동일 사용자 매칭 방식을 확인합니다. GHES의 실제 egress·프록시·Cloud IP allowlist와 필요한 목적지 443을 검증합니다. 해당 계약에서 Connect를 요구하면 STEP 04 직후부터 이 조건을 충족시킵니다.

2. Connect 연결 후 필요한 기능만

   GHES 프로필 → Enterprise settings → GitHub Connect → Enable GitHub Connect에서 올바른 Cloud enterprise와 연결합니다. 별도로 License sync → Enable을 선택합니다. 사용자 ID·이메일 등 데이터 전송 범위·수신지를 승인받습니다.

C1 · GitHub Connect: License sync → Enable

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Enterprise settings → GitHub Connect에서 기존 연결 대상과 License sync 상태를 읽습니다. Connect 연결·변경 승인 후에만 Enable을 선택합니다.

② 입력 / 대조할 값 · Input

같은 계약의 GHES와 Cloud enterprise 연결을 대조합니다. 주간 자동 사용량 보고와 GHES .ghl 파일 적용은 별개입니다.

③ 확인할 결과 · Expected

활성화 후 주간 GHES → Cloud 라이선스 사용량 보고를 Cloud 측 보고서에서 확인합니다. 활성화 버튼만으로 보고 완료를 판단하지 않습니다.

예시 범위·주의: 공식 원본은 License sync의 Enable 버튼만 보여줍니다. Sync now는 이 그림에 없습니다. 주간 사용량 동기화는 라이선스 키 갱신·좌석 증설·사용자 프로비저닝이 아닙니다.

1. 사용량 전송과 키 적용을 각각 확인

   자동 사용량 전송은 주 1회입니다. 필요하면 Enterprise settings → Settings → License/Licensing → License sync → Sync now를 승인 후 실행합니다. Cloud Licensing의 해당 Server source·마지막 성공·중복 제거 결과를 확인합니다. 키의 한도·만료는 STEP 02/04와 별개입니다.

다음 단계로 넘어갈 조건: Enabled뿐 아니라 실제 사용량 전송·수신·중복 제거 증거가 있습니다. 미사용이면 계약·요구사항 확인 후 N/A로 기록합니다.

상세 설정·명령 보기 → 다음: STEP 09 →순서 목록으로 ↑

STEP 09 / 12 · 선택·조건부 · 조작 전 승인 확인

09. Actions·외부 Storage

담당

Azure Storage·Entra 앱 담당 + GHES 관리자

준비값

선택 인증 모드·계정 endpoint·네트워크·RBAC/federation

작업 위치

Azure Portal / Entra App registrations / GHES Actions

1. 저장소·인증 방식 선택

   지원되는 Azure Blob 계정·실제 endpoint·네트워크 경로를 준비합니다. OIDC와 Credentials-based를 혼용하지 않습니다. Private Endpoint면 GHES와 Runner 각각 DNS·라우팅을 확인합니다. 기존 Shared Key 오류에 RBAC 역할 추가만으로 해결됐다고 판단하지 않습니다.

2. OIDC 선택 시 앱·federation 구성

   Storage 인증용 Entra 앱을 등록해 client/tenant ID를 기록합니다. GHES 사용자 SAML/SCIM 앱과 목적을 구분하고 아래 값을 입력합니다.

A1 · Storage OIDC 앱: Client ID·Tenant ID

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

현재 Actions Storage 인증 방식부터 확인합니다. OIDC를 사용하는 경우 Storage용 App registrations → Overview의 기존 값을 읽습니다. 신규 앱 생성은 별도 승인입니다.

② 입력 / 대조할 값 · Input

Application (client) ID와 Directory (tenant) ID를 GHES OIDC 설정과 대조합니다. App registration Object ID·service principal Object ID·Client ID를 구분합니다.

③ 확인할 결과 · Expected

사용자 SAML/SCIM 앱과 별도의 Storage 인증 앱을 정확히 식별합니다. Shared Key 방식 오류에 OIDC 앱 설정을 무조건 적용하지 않습니다.

예시 범위·주의: GitHub 공식 Azure 앱 예시이며 이름·ID는 fixture입니다. Azure 구독/Billing과 인증 테넌트는 별도 확인 대상입니다. 이 화면은 Storage IAM 권한 부여 결과가 아닙니다.

Storage OIDC 입력	형식 / 조건
Issuer	https://github.example.com/_services/token
Subject	github.example.com — 프로토콜 없음
Audience	api://AzureADTokenExchange — 실제 클라우드·federation 조건과 대조
RBAC	Storage account scope의 해당 앱 service principal에 Storage Blob Data Owner
외부 검증 접근	https://github.example.com/_services/token/.well-known/openid-configuration https://github.example.com/_services/token/.well-known/jwks 두 주소 모두 외부 인증 서비스에서 도달 가능해야 함

A2 · Storage 앱: Federated credentials 진입

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

Storage 앱 → Certificates & secrets → Federated credentials에서 기존 신뢰를 읽습니다. 신규 또는 변경 승인 때만 Add credential을 사용합니다.

② 입력 / 대조할 값 · Input

GHES Storage issuer: https://github.example.com/_services/token. Subject: github.example.com. Audience: api://AzureADTokenExchange를 실제 구성과 대조합니다. workflow의 repo:ORG/REPO subject와 다릅니다.

③ 확인할 결과 · Expected

연합 신뢰와 외부 metadata/JWKS 도달성을 확인합니다. Storage account → Access control (IAM) → Role assignments에서 해당 SP의 Storage Blob Data Owner와 scope를 별도로 대조합니다.

예시 범위·주의: ghes-actions-test는 공식 fixture입니다. Federated credentials 탭·Add credential 진입만 보이며 펼친 입력값·완료된 신뢰·Storage IAM 역할 화면은 없습니다. 역할 추가는 별도 승인입니다.

1. GHES Actions 연결·검사

   Management Console → Actions → Enable GitHub Actions → Azure Blob Storage Setup에서 선택한 인증 방식의 입력값을 넣습니다. OIDC는 tenant/client/account/endpoint suffix, Credentials는 승인된 connection string입니다. Test storage settings는 실제 쓰기이므로 승인 후 실행합니다.

2. 저장·적용 완료 확인

   container 확인뿐 아니라 쓰기 성공까지 확인하고, 승인된 Save settings의 서비스 재시작 영향을 고려해 구성 완료를 기다립니다. 실패하면 Storage 오류 코드·현재 인증 모드·실제 출구 IP를 대조합니다.

다음 단계로 넘어갈 조건: Storage 연결·쓰기·구성 적용이 성공했습니다. OIDC 사용 시 외부 discovery/JWKS도 확인합니다.

상세 설정·명령 보기 → 다음: STEP 10 →순서 목록으로 ↑

STEP 10 / 12 · 선택·조건부 · 조작 전 승인 확인

10. Runner·워크플로 실행

담당

DevOps·Runner 운영자

준비값

Actions/Storage 완료·시험 저장소·runner group·label·OS

작업 위치

GHES Runner 등록 UI → 별도 Runner 호스트

1. 별도 Runner 호스트 준비

   GHES appliance가 아닌 승인된 OS의 전용 호스트·계정을 사용합니다. GHES HTTPS·필요 Blob·공개 action/패키지 경로, 인증서 신뢰와 runner group의 허용 저장소를 준비합니다.

2. 등록 범위·OS 선택

   조직용은 Organization → Settings → Actions → Runners → New runner에서 OS·architecture를 선택합니다. 저장소용과 조직용 URL·권한을 혼동하지 않습니다. 아래는 공식 선택 화면 예시입니다.

R1 · Self-hosted runner 추가: OS·아키텍처 선택

공식 문서 원본 PNG · 확대 후 Esc로 축소원본 크기로 확대

① 클릭할 위치 · Click

기존 runner·group·허용 저장소를 먼저 읽습니다. 승인된 신규 등록은 조직 Settings → Actions → Runners → New runner로 진행합니다. 저장소 범위에서는 Repository Settings → Actions → Runners → New self-hosted runner입니다.

② 입력 / 대조할 값 · Input

실제 runner 머신의 OS·아키텍처와 조직/저장소 등록 범위를 선택합니다. 예시 호스트는 https://github.example.com입니다. 등록 토큰은 ••••••••로 취급하고 문서·로그에 복사하지 않습니다.

③ 확인할 결과 · Expected

실제 GHES 화면이 제공하는 명령을 승인된 runner 머신에서 실행한 뒤 Online/Idle·허용 저장소·파일럿 job 결과를 확인합니다. 선택 화면만으로 등록 성공을 판단하지 않습니다.

예시 범위·주의: 공식 문서가 조직·저장소·enterprise 절차에 공통으로 사용하는 OS/Architecture 원본 PNG입니다. New self-hosted runner/New runner 버튼 자체·등록 토큰·완료 상태는 이 그림에 없습니다. Linux/x64 선택은 예시이며 OS 지원 범위와 실제 머신을 별도 확인합니다.

1. 화면이 생성한 설치 명령으로 등록

   해당 GHES가 제공한 다운로드·검증·config 명령을 Runner 호스트에서 순서대로 실행합니다. 등록 토큰은 비밀이며 문서에 옮기지 않습니다. 정상 Listening/Idle을 확인하고 필요한 서비스 구성은 승인된 권한으로 수행합니다.

2. 작은 워크플로로 왕복 검증

   Phase 9의 합성 데이터 workflow를 승인된 시험 저장소에 적용합니다. checkout → artifact upload → download → 내용 비교를 확인합니다. GHES 호환 action ref를 사용하며 GitHub.com의 artifact v4+ 예제를 무조건 가져오지 않습니다.

다음 단계로 넘어갈 조건: Runner online만이 아니라 실제 job과 artifact 왕복이 성공했습니다. 미사용이면 STEP 09와 함께 N/A로 기록합니다.

상세 설정·명령 보기 → 다음: STEP 11 →순서 목록으로 ↑

이미 구축된 환경에서 새 사용자만 추가할 때

12단계를 처음부터 다시 하지 않습니다. 아래 순서로 현재 상태를 읽고 필요한 부분만 변경합니다.

1. 대상 앱·사용자 확정

   Cloud EMU와 GHES 앱을 분리하고 각 앱의 Tenant URL·source Object ID·할당·Scope를 확인합니다.

2. 라이선스 조건 확인

   계약상 필요한 Cloud 소비와 GHES 설치 키 한도·만료·실사용량을 대조합니다. 여유가 없거나 갱신이 필요한 경우만 새 키를 발급·적용합니다.

3. GHES 앱 할당·동기화

   유효한 직접 할당/보안그룹 직접 멤버를 구성합니다. 정상 Automatic job이면 다음 증분 대상이며, 승인된 즉시 처리만 사용자 한 명 온디맨드로 실행합니다.

4. 계정·접근 확인

   새 시각의 Action/Status/Target ID → GHES active/externalId → 본인 SAML 로그인 → Org/저장소 권한을 확인합니다. 실패 시 전체 Restart나 삭제로 우회하지 않습니다.

5. 사용량 보고·기록

   Connect를 사용하는 경우 주간 전송 또는 승인된 Sync now의 실제 수신을 확인합니다. 사용자 생성과 키 한도 변경의 증거로 사용하지 않습니다.

필요한 화면 찾기

모든 캡처는 위 해당 작업 바로 뒤에 있습니다. 아래 색인은 화면으로 바로 이동합니다. VMware·백업 등 제품/버전별 화면은 상세 장의 공식 문서와 입력표로 안내합니다.

Phase 0배포 선택·용량·운영 설계

상세 참조 장 · STEP 01의 실행 순서·화면으로 돌아가기 →

담당: 아키텍트·서비스/가상화/보안 책임자선행: 업무·규제·연결 요구 수집산출물: 버전·플랫폼·사양·RPO/RTO·책임 승인서

0-1. 제품과 운영 책임을 먼저 선택한다

공식 근거: GHES 시스템 구조 · Cloud·Server 병용 · EMU 공식 안내

0-2. 버전 기준과 지원 종료를 승인서에 적는다

변경 승인서에는 실제 패치 버전, 이미지 파일명, 다운로드 날짜, 릴리스 노트의 알려진 문제, 시험 결과, 지원 종료 전 업그레이드 일정을 남긴다. 이 문서는 특정 패치 번호를 ‘최신’으로 고정하지 않는다. 문서가 열리는 것과 해당 버전이 지원 중인 것은 다르다.

공식 근거: 전체 릴리스·지원 기간 · 3.21 릴리스 노트

0-3. 지원 플랫폼별 배포 경로를 구분한다

공식 근거: 지원 플랫폼 색인 · VMware · Azure · AWS · Hyper-V · OpenStack KVM · GCP

0-4. 좌석 수를 출발점으로, 실제 부하로 용량을 결정한다

위 값은 GHES 3.21 VMware 문서의 최소 권장 구성이지 성능 보증이 아니다. Actions는 기본 CPU·메모리에 각각 최소 25%, Code Security도 각각 최소 25%의 추가 자원을 계획한다. 두 기능을 모두 쓰면 두 증가 요인을 함께 반영한다. Actions 자체의 최소 조건인 8 vCPU / 64 GB도 동시에 충족해야 하므로 단순히 표에 25%만 더해 끝내지 않는다.

CPU 증설 시에는 16 vCPU까지 vCPU당 최소 6.5 GB 메모리 추가를 권장한다. 이는 증설 지침이며 위 표 전체를 대체하는 전역 최소 비율이 아니다. 예를 들어 12 vCPU / 80 GB는 검증을 시작할 계획안일 뿐, 사용자 50명 또는 특정 runner 수용량을 보증하지 않는다. runner 연결 수·동시 job·job 길이·artifact 크기·Git 부하는 서로 다른 지표이다. runner는 어플라이언스와 분리된 실행 호스트에 둔다.

1. 부하 목록 수집

   저장소 수·대형 저장소 크기·LFS 증가량·동시 clone/fetch·API/webhook 빈도·Code Security 분석·Actions job 및 artifact/cache 보존량을 적는다. 반복 polling은 줄이고 webhook 기반 연계를 검토한다.

2. 스토리지 설계

   SSD의 지연시간·지속 IOPS·동시 부하 여유를 확인한다. 기본 루트 디스크는 200 GB이므로 비클러스터 신규 배포는 400 GB로 사전 조정한다. 약 절반은 업그레이드·롤백용이어서 400 GB 전체가 루트 파일시스템에 표시되지 않는다.

3. 데이터 볼륨 분리

   루트와 별도로 새 빈 데이터 디스크를 전원 투입 전에 연결한다. 기존 데이터나 파티션이 있는 디스크를 재사용하지 않는다. VMware는 thick provisioning with lazy zeroing을 권장한다. 데이터 디스크 초기화·포맷 명령을 수동 실행하지 않는다.

4. 파일럿으로 수정

   업무를 대표하는 시험 저장소 examplerepo와 승인된 부하로 clone·push·API 지연, CPU·메모리 압박, 디스크 지연·여유, 백업 시간을 측정한다. 목표·경보 임계값을 사전에 합의하고 초과하면 확장 후 재시험한다. 좌석 수만으로 운영 승인하지 않는다.

공식 근거: VMware 하드웨어·디스크 · Actions 최소 자원·외부 저장소

0-5. 운영 인수인계 워크시트

공식 근거: 시스템·백업 구조 · 관리 셸 지원 범위

Phase 1계약 모델·라이선스 확보와 검증

상세 참조 장 · STEP 02의 실행 순서·화면으로 돌아가기 →

담당: 구매·Cloud billing·GHES 운영 담당선행: Phase 0 제품 선택산출물: 라이선스 파일·한도/사용량 대조표·갱신 책임

1-1. 계약 모델부터 판별한다

공식 근거: 라이선스 파일 · PAYG·Volume 병용 비교

1-2. 사람 수, Cloud 소비, 설치된 서버 한도를 분리한다

Cloud People > Members의 전체 수나 Total consumed 값을 키 좌석 산정에 대신 쓰지 않는다. Billing and licensing > Licensing의 consumed Cloud licenses를 확인한다. GHEC 계정·SCIM 계정 생성만으로 Enterprise 유료 좌석 소비가 확정되지 않는다. 조직에 속하지 않은 unaffiliated 사용자, Copilot만 배정된 인원 수도 GHE 소비 좌석 수와 같지 않다. 조직 소속·협업자 역할·구독 유형 등 공식 과금 조건을 확인하고 특히 Visual Studio 결합 라이선스의 예외도 별도 검토한다.

1. 현재 값 기록

   계약 모델, Cloud 소비 좌석, 설치된 GHES 키 한도, GHES 실제 사용 좌석, 만료일을 서로 다른 열로 적는다. PAYG 생성 전 조직 할당이 완료되고 Licensing 화면의 소비에 반영됐는지 확인한다.

2. 좌석 확대

   설치 한도 확대가 필요하면 PAYG는 Cloud 소비 증가를 확인한 뒤 새 서버 키를 생성·다운로드하고 GHES에 직접 업로드한다. Cloud 인원 증가만으로 기존 서버 키 한도가 자동 확대되지 않는다. Volume은 추가 구매 후 제공된 파일을 적용한다.

3. Connect의 경계 확인

   라이선스 동기화는 GHES → Cloud 사용량 보고 및 이메일 기반 중복 제거다. 계정 프로비저닝이나 Cloud → GHES 키·quota 자동 갱신이 아니다. 자동 보고는 매주 실행되며 Sync now도 사용량만 전송한다. 한도·만료일을 바꾸는 작업과 분리한다.

4. 만료 대응

   만료일·내부 갱신 담당·알림 시점을 기록하고 갱신 파일 업로드 후 재검증한다. 키 만료 시 웹·Git 접근을 사용할 수 없으므로 정상 업무 중단 전에 처리한다. 회사명·키 원문·사용자 이메일이 담긴 출력은 공개 문서에 붙이지 않는다.

공식 근거: Cloud 소비 사용자·예외 · 사용량 동기화 방향

1-3. 다운로드와 업로드 절차

1. Cloud 경로

   승인된 기업 소유자 권한으로 GitHub Enterprise Cloud에 접속한다. 프로필 → Enterprise 또는 Enterprises → 대상 기업 → Billing and licensing → Licensing으로 이동한다. consumed Cloud licenses 증가 또는 만료까지 30일 이하일 때 표시되는 노란 배너의 Generate new license를 선택한다. Enterprise Server licenses → Download로 파일을 받는다. 올바른 기업인지, 파일 생성일·수량이 요청과 일치하는지 대조한다.

2. 독립형·평가 경로

   Cloud 기업이 없는 경우, 평가판, GHE.com Volume 또는 경로가 불명확한 경우 공식 enterprise.github.com/download에서 계약 권한으로 확인한다. 파일이 없으면 구매·Sales에 문의한다. 단순히 Cloud 계정부터 새로 만드는 것으로 해결하지 않는다.

3. 안전한 보관

   파일의 계약·만료일·좌석을 확인하고 접근 제한 저장소에 보관한다. 다운로드 권한과 GHES 업로드 권한을 분리한다. 이메일 본문, 저장소, 실행 명령 인자에 라이선스 원문을 넣지 않는다.

4. 신규 설치

   Phase 3에서 격리된 최초 설정 화면에 파일을 업로드하고 root Management Console 암호를 설정한다. 아직 생성되지 않은 웹 사용자나 IdP 계정 암호를 입력하는 단계가 아니다.

5. 기존 인스턴스 갱신

   웹 site administrator로 로그인 → Enterprise settings → Settings → License → User licenses / Quick links → Update license. Console 인증이 요구되면 별도 Console 자격증명을 사용한다. License file 선택 → Upload. 백그라운드 반영에 몇 분 걸릴 수 있으므로 완료 후 한도·만료일을 다시 확인한다.

공식 근거: 공식 다운로드 분기·UI · 업로드 UI · Console 인증 · Console 계정 유형

1-4. 설치 후 조회로 파일·사용량을 각각 검증한다

ghe-license info
ghe-license check

ghe-license info의 seats는 실제 사용 인원이 아니라 키 한도다. seats: 0이고 unlimited_seating: true이면 무제한 의미이지 사용자가 0명이라는 뜻이 아니다. 사용량은 License UI 또는 다음 REST 조회의 seats_used와 구분한다.

gh api --hostname github.example.com --method GET /enterprise/settings/license

공식 근거: ghe-license info / check · 라이선스 GET API

1-5. 신규 사용자마다 키를 바꾸기 전에 판단한다

공식 근거: 파일·PAYG 좌석 기준 · 다운로드·노란 배너

1-6. 후보 파일 검사·UI 우회·전후 증거를 남긴다

1. 변경 전 증거·복구 준비

   변경 승인 번호·수행자·검증자·변경 창과 현재 기업·Cloud 소비·설치 한도·사용량·만료일·조회 시각을 기록한다. 기존 .ghl은 접근 제한 저장소에 보존하고 덮어쓰지 않는다. 이전 키가 만료됐거나 현재 사용량을 수용하지 못하면 되돌리기도 안전하지 않으므로 복구 가능 여부와 Support 연락 기준을 먼저 승인받는다.

2. 후보 파일만 조회

   승인된 전달 경로로 관리 셸에서 읽을 수 있는 제한된 위치에 새 .ghl을 준비한 뒤 아래 명령을 사용한다. /APPROVED/PATH/new-license.ghl은 실제 승인 경로로 바꾼다. 생성일은 다운로드 기록과 함께 대조한다. 이 검사는 설치 키를 교체하지 않으며 check 성공만으로 올바른 기업·수량을 보증하지 않는다.

GHE_LICENSE_FILE=/APPROVED/PATH/new-license.ghl ghe-license info
GHE_LICENSE_FILE=/APPROVED/PATH/new-license.ghl ghe-license check

1. License 화면이 HTTP 500이면

   오류 시각·대상 화면·요청 ID를 보존하고 승인된 관리망에서 https://github.example.com/setup으로 Management Console에 진입한다. 별도 Console 자격증명과 TCP 8443 접근을 확인하고 실제 Console UI의 라이선스 업로드 화면을 사용한다. Console까지 실패하면 반복 업로드·재부팅 대신 오류 증거를 가지고 Support에 문의한다.

2. 승인된 업로드·반영 대기

   1-3의 License file → Upload로 후보 파일을 올린다. 백그라운드 반영은 몇 분 걸릴 수 있으나 고정 SLA가 아니다. 완료 상태를 확인하고 중복 업로드를 피한다. 전체 OS 재부팅은 공식 업로드 절차의 필수 단계로 문서화되어 있지 않으며 개별 재부팅 경험을 일반 요구사항으로 삼지 않는다. CLI의 --apply는 영향을 받는 서비스를 재시작하므로 별도 변경 승인이 필요하다. 추측한 import 구문이나 구성 적용 명령을 기본 후속 작업으로 실행하지 않는다.

3. 변경 후 비교·종료

   1-4의 환경변수 없는 ghe-license info·ghe-license check로 설치 키를 다시 조회하고 License UI/REST의 한도·사용량·만료일, 웹·Git 서비스 복귀를 기록한다. 변경 전·후 값과 업로드 완료 시각을 한 표에 남긴다. 불일치·오류는 파일/적용/사용량을 분리해 조사하고 승인·유효성 확인 없이 이전 파일로 되돌리지 않는다. Connect 보고와 사용자 생성 성공은 별도 검증한다.

공식 근거: 업로드·백그라운드 반영 · 후보 파일 조회·서비스 재시작 · Console 직접 접근

Phase 2통신 방향·DNS·TLS와 검증 설계

상세 참조 장 · STEP 03의 실행 순서·화면으로 돌아가기 →

담당: 네트워크·PKI·IAM·GHES 운영 담당선행: FQDN·토폴로지·기능 선택산출물: 방화벽 행렬·DNS/TLS·Cloud 경로 증거

2-1. 연결을 시작하는 주체별로 방화벽을 설계한다

아래 포트는 모두 GHES 인바운드로 개방하는 목록이 아니다. 출발지·목적지·프로토콜·반환 트래픽·프록시 경로·업무 용도를 변경 요청서에 적는다. 실제 도입한 기능만 승인하고 관리망은 사용자망과 분리한다.

공식 근거: 공식 포트·HA·Connect · Connect 연결 경계 · runner 통신 · Blob·OIDC 선행조건 · GHES SCIM 도달성

2-2. DNS·게시·인증서의 책임 경계를 고정한다

1. FQDN 확정

   github.example.com과 내부·외부 DNS 응답, VIP/NAT, TTL, 갱신 담당을 승인한다. GHES 내부 resolver에서도 자신의 이름이 해석되어야 한다. 초기 설정 후 hostname 변경은 장애·보안키 무효화 가능성이 있으므로 단순 DNS 변경 작업으로 취급하지 않는다. 필요 시 공식 신규 인스턴스·복원 경로 및 Support를 검토한다.

2. 하위 도메인 격리

   *.github.example.com wildcard DNS 또는 공식 목록의 개별 레코드를 만든다. assets, avatars, codeload, raw, uploads, media, gist, pages 등 사용할 서비스가 같은 승인된 게시 경로로 해석되는지 확인한다. API·Actions에 필요한 이름도 해당 기능 문서와 함께 확인한다. 격리 후 이전 /raw/ 같은 경로의 404를 전체 서비스 장애로 오판하지 않는다.

3. TLS 준비

   SAN에 github.example.com과 *.github.example.com을 포함한다. wildcard만으로 루트 FQDN은 보호되지 않는다. GHES 업로드용 인증서·중간 체인은 PEM, 개인키는 암호 없는 RSA PEM으로 준비하고 개인키 보관자를 지정한다. 내부 CA는 승인된 PC·runner의 신뢰 저장소에 배포하되 Cloud SCIM 클라이언트도 그 체인을 신뢰한다고 가정하지 않는다.

4. LB/WAF 확인

   클라이언트 → LB에서 TLS를 종료해도 LB → GHES는 HTTPS를 유지한다. HTTP 다운그레이드는 지원되지 않는다. FQDN·SNI·인증서 검증·SCIM 경로·HTTP 메서드·Authorization 헤더가 정상 전달되는지 확인한다. WAF의 브라우저 인증 챌린지나 로그인 HTML 응답을 SCIM API 앞에 두지 않는다.

5. NTP·인증서 수명

   승인 NTP primary·secondary를 지정하고 UDP 123 반환 경로를 확인한다. 하이퍼바이저 시각 강제 설정과 GHES NTP가 충돌하지 않게 한다. TLS 갱신은 발급→키 전달→업로드→변경 창→전체 체인·SAN 재검증으로 운영하고 만료 경보·주/부 담당을 둔다.

외부 저장소 OIDC를 선택하면 https://github.example.com/_services/token/.well-known/openid-configuration과 https://github.example.com/_services/token/.well-known/jwks의 공개 도달성을 별도 승인한다. 완전 사설망 정책과 양립하지 않으면 무작정 전체 사이트를 공개하지 말고 인증 방식과 배포 설계를 다시 결정한다.

공식 근거: hostname 변경 경고 · DNS resolver · 하위 도메인·SAN · TLS·LB 제한 · NTP · Entra IP Ranges

2-3. PC 검사와 Cloud 검사 결과를 분리한다

Resolve-DnsName github.example.com
Resolve-DnsName assets.github.example.com
Test-NetConnection github.example.com -Port 443
# 아래 두 항목은 승인된 관리망 PC에서만 확인
Test-NetConnection github.example.com -Port 8443
Test-NetConnection github.example.com -Port 122

openssl version
openssl s_client -connect github.example.com:443 \
  -servername github.example.com -verify_hostname github.example.com \
  -verify_return_error -showcerts </dev/null
curl -q --proto '=https' --connect-timeout 10 --max-time 30 \
  --silent --show-error --dump-header - --output /dev/null \
  https://github.example.com/

동일 검사를 assets 등 실제 사용하는 하위 도메인에도 반복한다. 내부 CA라면 승인된 CA 번들을 사용하도록 도구를 구성한다. -k로 검증을 끄거나 -L로 잘못된 리디렉션을 숨기지 않는다. 401/403은 HTTP 서버 도달의 단서일 뿐, 인증·권한·SCIM 동작 성공은 아니다.

1. 설치 전 설계 게이트

   방화벽 규칙과 DNS·TLS 발급·NTP·외부 게시 책임을 승인한다. 아직 기동하지 않은 GHES의 연결 성공을 요구하지 말고 Phase 3 이후 실행 검증 항목을 미완료로 남긴다.

2. 네 가지 증거 수집

   기동 후 ① 각 실제 호출 경로의 DNS 결과 ② FQDN·체인 포함 TLS 성공 ③ IAM 설정 후 Entra의 실제 Test Connection 결과 ④ 동일 시각의 LB/WAF 및 GHES 요청 수신·응답 상관관계를 모은다. 시각·경로·상태코드·요청 ID를 기록하고 토큰·개인정보는 가린다.

3. 제한된 파일럿

   네 가지 증거가 확보된 후 소수의 승인된 사용자로 SSO와 프로비저닝을 검증한다. Test Connection은 사용자 생성·수정·중지를 모두 시험하는 기능이 아니므로 실제 수명주기는 SCIM 단계에서 확인한다. 대기 시간이 0이거나 항상 40분 이내라는 SLA를 약속하지 않는다.

공식 근거: SCIM 선행조건·계정 · Entra Test Connection·주기·온디맨드

2-4. 임시 아웃바운드 허용을 승인된 프록시 경로로 전환한다

1. 현재 규칙 고정·승인

   기존 규칙 ID·출발지·목적지·포트·직접/프록시 경로·만료 시각·담당자·승인자를 적고 네트워크 로그로 실제 외부 NAT IP를 확인한다. GHES 사설 IP나 관리자 PC 공인 IP로 대신하지 않는다. 변경 창·중단 기준·승인된 복구 경로를 정한다.

2. 승인된 HTTP 프록시 구성

   Management Console의 HTTP Proxy Server와 HTTP Proxy Exclusion에서 승인 URL·포트와 꼭 필요한 예외만 검토한다. GHES → 프록시 경로와 프록시 → 외부 목적지 경로를 따로 승인한다. Actions 사용 시 HTTP 프록시만 지원되며 HTTPS/SOCKS5 프록시는 지원되지 않는다. HTTP 프록시를 쓰더라도 목적지 HTTPS/TLS 검증은 유지한다. Privacy/Private mode 변경은 공개 범위에 영향을 주므로 별도 보안 검토 없이 해제하지 않는다. 승인된 설정 저장은 서비스 재시작·중단 가능성을 고려하고 구성 완료를 기다린다.

3. Connect 세 목적지·Cloud 허용 목록

   github.com, api.github.com, uploads.github.com의 TCP 443을 프록시 경유로 허용한다. GHES 서비스가 실제 쓰는 경로와 프록시 예외를 확인하고 전환 후 외부 NAT IP를 기록한다. Cloud 기업에 IP allowlist가 있으면 이 실제 출구 IP/대역을 승인받아 반영한다. 임의 IP 확인 사이트로 조회하지 말고 경계 장비·프록시 로그를 사용한다.

4. 경로 시험과 기능 시험 분리

   2-5의 제한된 무인증 검사를 수행하고 서비스 요청의 같은 시각 로그로 프록시 통과를 대조한다. 이어 실제 GitHub Connect 사용량 동기화 결과·최근 성공 시각·Cloud 수신 값을 확인한다. 별도로 승인된 파일럿 사용자의 SCIM 생성·조직 할당·로그인을 확인한다. 동기화 성공은 계정 생성이나 설치 키 확대의 증거가 아니다.

5. 임시 규칙 회수·재시험

   승인된 프록시 경로의 성공 증거와 복구 계획을 검토한 뒤 변경 창에서 임시 광범위 규칙을 제거한다. 제거 후 같은 Connect·프로비저닝·필요한 Actions 검사를 다시 수행해 우회 경로 의존이 없음을 확인한다. 실패하면 증거를 보존하고 사전 승인된 복구 절차를 적용하며 무기한 전체 허용으로 돌아가지 않는다.

Blob은 실제 저장소 endpoint의 TCP 443, 저장소 OIDC를 선택한 경우에만 login.microsoftonline.com을 추가한다. 직접 연결 또는 Private Endpoint에 맞는 DNS 응답·라우팅·프록시 예외를 GHES와 runner 각각 확인한다. 지정 DNS의 UDP/TCP 53과 NTP의 UDP 123은 HTTPS 프록시와 별도 경로다. runner 프록시·출구 IP는 GHES와 같다고 가정하지 않으며 공개 Actions·패키지·레지스트리 의존성도 별도 시험한다.

공식 근거: Connect의 세 호스트·Cloud IP allowlist · 아웃바운드 프록시·Actions 제한 · Azure Blob·OIDC

2-5. GHES에서 세 목적지만 제한적으로 검사한다

승인된 GHES 관리 셸에서 서비스와 같은 프록시·DNS·CA 신뢰·예외 경로인지 먼저 확인한다. Console 설정이 셸 curl에 자동 반영된다고 가정하지 않는다. 불일치하면 네트워크 담당이 승인된 시험 경로를 준비한 뒤 실행한다. 토큰·Authorization·쿠키를 추가하지 않고 환경변수 전체나 프록시 자격증명을 덤프하지 않는다. PC에서 수집한 성공 로그만으로 GHES 서비스 경로를 입증할 수 없다.

date -u '+%Y-%m-%dT%H:%M:%SZ'
for url in https://github.com/ https://api.github.com/meta https://uploads.github.com/; do
  printf '\nURL=%s\n' "$url"
  rc=0
  curl -q --proto '=https' --connect-timeout 10 --max-time 30 \
    --silent --show-error --output /dev/null \
    --write-out 'http=%{http_code} proxy_connect=%{http_connect} peer=%{remote_ip} tls_verify=%{ssl_verify_result} seconds=%{time_total}\n' \
    "$url" || rc=$?
  printf 'curl_exit=%s\n' "$rc"
done

이 검사는 HTTP 오류에도 curl exit 0이 나올 수 있으므로 HTTP 상태와 종료 코드를 함께 읽는다. 출력은 승인된 제한 기록에 시각·출발지·경로와 함께 보관하고 실제 Connect 동기화·사용자별 프로비저닝 결과는 별도 열에 남긴다.

공식 근거: Connect 연결·동기화 전제 · 사용량 동기화

Phase 3VMware 어플라이언스 설치·초기 보호

상세 참조 장 · STEP 04의 실행 순서·화면으로 돌아가기 →

담당: 가상화·GHES 운영 수행자와 검증자선행: Phase 0–2 승인·공식 이미지·키·관리망산출물: 검증된 기반 인스턴스·관리 접근·IAM 인계서

3-1. 공식 이미지와 변경 창을 준비한다

1. 진입 조건 확인

   Phase 0의 플랫폼·사양, Phase 1의 라이선스 파일, Phase 2의 FQDN·DNS·TLS·관리망을 준비한다. 수행자·검증자·중단 조건·지원 연락 경로를 정하고 초기 설정 동안 담당자가 자리를 비우지 않는다.

2. 공식 OVA 확보

   3.21 Release notes에서 설치일에 승인한 지원 패치를 선택 → Download GitHub Enterprise Server X.X.X → GitHub On-premises의 VMware ESXi/vSphere (OVA) → Download. 비공식 재패키징 이미지를 사용하지 않는다.

3. 출처·무결성 확인

   공식 다운로드 주소, 실제 파일명·버전·크기, vSphere가 표시하는 서명·발행자·인증서 검증 결과를 기록한다. 공식 checksum 또는 서명 검증 자료가 제공되면 그 값·방법과 대조한다. 임의 SHA 값을 만들어 기대값으로 쓰지 않는다. 서명·무결성 오류가 나면 우회하지 않고 재다운로드 또는 Support 확인 후 진행한다.

공식 근거: VMware 공식 이미지·배포 절차 · 설치할 패치 선택

3-2. vSphere에서 전원 투입 전 구성을 끝낸다

1. 루트 용량 사전 결정

   원본 OVA를 보존하고 비클러스터 400 GB 루트 권장을 적용한다. 공식 VMware 가이드의 배포 전 OVF disk attributes 조정 경로를 따른다. 원본 무결성 검사와 승인된 템플릿 변경 기록을 구분하고, 변경 후 manifest·서명 오류가 있으면 검증 우회 없이 배포 담당과 해결한다. 부팅 후 임의 파티션 편집으로 맞추지 않는다.

2. Deploy OVF Template

   vSphere Client에서 승인 호스트·클러스터를 선택하고 Deploy OVF Template로 공식 이미지를 가져온다. VM 이름·대상·데이터스토어·네트워크 매핑을 대조한다. 디스크와 향후 확장 여유가 충분한 datastore, 권장 Thick Provision Lazy Zeroed를 선택한다.

3. 자동 전원 투입 해제

   Power on after deployment를 선택하지 않는다. 배포 후 Edit Settings에서 승인된 CPU·메모리·루트 용량·관리 경로를 다시 확인한다. 잘못된 네트워크 매핑은 최초 설정 화면을 외부에 노출할 수 있다.

4. 새 데이터 디스크 연결

   Add New Device → Hard Disk에서 별도 새 데이터 디스크를 만들고 Phase 0의 승인 용량을 지정한다. 루트 디스크를 데이터 디스크로 착각하지 않도록 장치·용량을 대조한다. 데이터가 있거나 비어 있는지 증명할 수 없는 디스크는 연결하지 않는다.

5. 부팅·네트워크

   검증자 확인 후 전원을 켠다. OS를 따로 설치하지 않는다. vSphere 콘솔에서 IP·gateway·DNS를 확인하고 필요 시 콘솔의 S 네트워크 설정에서 승인된 값을 입력한 뒤 D로 완료한다. 화면의 실제 옵션을 확인하며 원격 세션이 끊길 수 있는 변경을 무작정 반복하지 않는다.

공식 근거: VMware root·disk·power-on 지침 · 콘솔 DNS 설정

3-3. 최초 Console 설정과 웹 관리자 생성을 즉시 수행한다

1. 라이선스·Console 암호

   관리자 브라우저에서 https://github.example.com/setup으로 최초 설정에 진입한다. Management Console은 HTTPS 8443 경로를 사용하므로 해당 관리 포트를 허용한다. 공식 파일을 업로드하고 최초 root Management Console 암호를 설정·금고에 보관한다.

2. Hostname·DNS·Time

   Console의 Hostname에 승인된 FQDN을 지정한다. DNS resolver는 VM 콘솔에서 확인한 값을 사용하고 자신과 필수 외부 이름의 해석을 확인한다. Time의 Primary NTP server와 필요 시 Secondary NTP server를 지정한다. 호스트 이름을 시험용 별칭으로 시작한 뒤 운영명으로 바꾸는 방식을 피한다.

3. 격리·TLS

   Hostname → Subdomain isolation (recommended)을 선택한다. TLS 설정에서 TLS only (recommended), 인증서/전체 체인, Unencrypted key를 지정한다. 버전별 TLS/Privacy 화면 배치를 확인하되 TLS 적용을 이유로 조직의 Private mode 정책을 임의로 해제하지 않는다. 기업 공개 범위 변경은 별도 승인 사항이다.

4. 검토 후 Save settings

   hostname·DNS·NTP·라이선스·TLS·인증 방식을 검증자와 대조한다. Actions는 외부 저장소·인증·runner 설계가 완료될 때까지 비활성 상태로 둔다. Save settings 후 구성 실행이 완료되고 최초 재시작이 끝날 때까지 기다린다. 일반 설정 저장도 서비스 재시작·사용자 중단을 유발하므로 변경 창을 적용한다.

5. 첫 웹 사용자

   Visit your instance로 이동해 첫 built-in 웹 관리자 계정을 즉시 만든다. 강한 암호와 복구 수단을 보관하고 제공되는 2FA를 설정한다. 첫 관리자 권한과 Enterprise settings 접근을 확인한 후 일반 사용자에게 서비스를 공개한다. 최초 Console 암호를 이 웹 계정 암호로 재사용하지 않는다.

6. 후속 IAM 인계

   SAML과 SCIM 단계는 별도 변경이다. SCIM에는 공식 절차의 built-in scim-admin enterprise owner가 필요하다. 첫 웹 관리자와 자동으로 같다고 가정하지 않는다. SAML 전환 전에 비상 로그인·승격·중복되지 않는 사용자명과 이메일을 검증한다. 여기서는 SCIM 토큰을 발급하지 않는다.

공식 근거: Console 진입 · TLS 필수 형식·중단 · 하위 도메인 설정 · 시각 설정 · SCIM built-in setup user

3-4. 관리 접근을 역할별로 분리하고 SSH를 검증한다

1. 공개키 등록

   웹 Site admin → Management Console → SSH access → Add new SSH key에 운영자 공개키만 붙여넣고 Add key를 누른다. 소유자·지문·회수일을 기록한다. 이 변경은 즉시 적용되며 이를 위해 Save settings를 누를 필요가 없다.

2. 호스트 지문 대조

   최초 SSH 연결 전 서버 호스트 키 지문을 승인된 콘솔 또는 별도 신뢰 경로로 확보한다. 프롬프트의 지문과 대조한 뒤 승인한다. 호스트 키 확인을 끄거나 변경된 키를 무조건 삭제해 접속하지 않는다.

ssh -p 122 -i ./approved-admin-key admin@github.example.com

ghe-version
ghe-system-info
ghe-config core.github-hostname
ghe-license check
df -h
free -h

출력에 포함된 시스템 식별자·네트워크 정보는 제한된 운영 기록에만 보관한다. root 여유가 예상보다 작다고 패키지 삭제·파티션 포맷·OS 업데이트를 실행하지 않는다. 설정값 전체 덤프 대신 필요한 hostname만 조회하고, 저장소·토큰·개인키가 포함될 수 있는 로그를 공개 공유하지 않는다.

공식 근거: 개인별 Console 계정 · SSH 키·즉시 적용·지원 제한 · 읽기 도구·시스템 정보 · 저장소·복구 구조

Phase 4관리 복구 경로와 Entra SAML 인증

상세 참조 장 · STEP 05의 실행 순서·화면으로 돌아가기 →

담당: GHES·Entra 관리자선행: TLS·백업·이관 승인산출물: 계정 구분표·SAML 매핑·복구 증거

SAML은 로그인, SCIM은 계정 수명주기, 조직 팀은 저장소 권한을 담당한다. 먼저 관리 복구 경로를 확보하고, 소수 파일럿으로 인증·프로비저닝·인가를 각각 검증한다.

4.1 관리 계정은 네 종류로 구분한다

4.2 변경 전 입력표

4.3 복구 계정 → Entra 앱 → GHES SAML

1. built-in 복구 경로 준비

   Site admin → Management Console → Authentication에서 기존 SAML 사용 시 Allow creation of accounts with built-in authentication과 Disable administrator demotion/promotion을 선택한다. 후자는 설정 중 IdP 밖에서 관리자 권한을 부여하기 위한 임시 상태다. 승인된 변경 창에서 Save settings → 구성 적용 성공을 확인한 뒤 다음 계정 생성·승격으로 진행한다. 선택만 하고 저장하지 않은 상태로 넘어가지 않는다.

2. scim-admin 생성과 독립 로그인

   Site admin → Invite user에서 예시 username·별도 이메일을 입력하고 Generate a password reset link를 사용한다. 새 비공개 창에서 초기 암호를 설정·금고 보관한다. 기존 관리자가 Enterprise settings → People → Administrators → Add owner에서 scim-admin을 검색해 Add로 enterprise owner를 부여한다. https://github.example.com/login의 built-in 로그인 경로로 재접속한다. 이 계정을 SAML에 연결하면 username/password 로그인 선택권을 잃을 수 있으므로 IdP 파일럿으로 사용하지 않는다. 독립 Console 복구 접근과 built-in 계정의 2FA·복구 코드도 확인한다.

3. 동일 파트너 앱 생성

   Entra ID → Enterprise apps → New application → 갤러리의 GitHub Enterprise Server를 추가한다. (Legacy) 앱은 제외한다. 같은 앱으로 SAML과 SCIM을 구성한다. 기존 Legacy/SAML 앱에서 옮길 때 GHES 3.21 가이드는 새 앱 구성을 요구하므로 할당·claims·SCIM 매핑을 검토해 이관한다. 최신 Entra 문서의 기존 앱 재사용 문구만 근거로 기존 앱을 즉시 전환하지 않는다.

4. 인증 전환 전에 로그인 대상 할당

   새 앱의 Users and groups → Add user/group에서 승인된 일반 SSO 파일럿을 먼저 할당한다. 기존 사용자 이관이면 변경 창에서 인증이 필요한 승인 대상도 전환 전에 할당·역할·접근 정책을 대조한다. 앱 할당이 필요한 구성에서 미할당 상태로 GHES 인증부터 바꾸지 않는다. 이때 SCIM 자동 프로비저닝은 아직 시작하지 않으며, 사용자 생성·Owner 검증은 Phase 5에서 별도 수행한다.

5. Entra SAML 기본값 입력

   앱 → Single sign-on → SAML → Basic SAML Configuration → Edit에서 아래 표를 입력한다. SAML certificates의 Certificate (Base64)를 받고 Set up GitHub Enterprise Server의 Login URL, Microsoft Entra Identifier를 수집한다.

6. GHES에서 IdP 값 연결

   Site admin → Management Console → Authentication → SAML에서 Single sign-on URL에 Login URL, Issuer에 Microsoft Entra Identifier, Verification certificate에 Base64 인증서를 넣는다. Signature Method·Digest Method는 IdP 서명 구성에 맞추고 Name Identifier Format도 실제 claim과 일치시킨다. User attributes를 검토하고 두 setup 옵션을 유지한다. IdP initiated SSO는 특별한 필요와 검증 없이 켜지 않는다.

7. 변경 저장과 파일럿 인증

   Management Console의 Save settings와 적용 진행 상태를 확인한다. 설정 적용은 서비스 재시작·중단 영향을 줄 수 있으므로 완료까지 변경 창과 복구 세션을 유지한다. 별도 브라우저에서 GHES 로그인 → Entra 인증 → GHES 복귀를 시험한다. Cloud의 Test SAML configuration 버튼이 GHES에도 있다고 가정하지 않는다. Entra의 Test this application은 별도 기능이다.

curl --head --silent --show-error --connect-timeout 10 https://github.example.com/login

파일럿 증거: 로그인 시각, 앱 이름, 익명화한 사용자 Object ID, Entra sign-in 결과, GHES login을 대응시킨다. SCIM을 아직 켜지 않았다면 JIT 결과이며 Phase 5 후 다시 시험한다. SAML assertion 원문·암호·토큰은 공유 보고서에 붙이지 않는다.

공식 근거: 3.21 SAML 설정 · 3.21 built-in 인증 · 3.21 Entra 통합 · Entra SAML UI·/sso · Console 계정 경계 · 3.21 setup 계정 Owner 승격 · 관리 SSH 122

Phase 5SCIM 프로비저닝과 사용자 수명주기

상세 참조 장 · STEP 06의 실행 순서·화면으로 돌아가기 →

담당: 신원·GHES 운영자선행: Phase 4·IdP의 API 도달성산출물: 할당·매핑·Owner·퇴사/복귀 증거

5.1 활성화 전 조건과 자격 증명

1. 전용 classic PAT 발급

   scim-admin으로 로그인 → Settings → Developer settings → Personal access tokens → Tokens (classic)에서 생성한다. 위 scope와 No expiration을 선택하고 값은 즉시 금고에 저장한다. 토큰은 자동 OIDC 교환 방식이 아니다.

2. GHES에서 SCIM 활성화

   scim-admin → Enterprise settings → Settings → Authentication security → SCIM Configuration → Enable SCIM configuration을 선택한다. 감사 로그의 business.enable_open_scim과 기존 사용자 영향 범위를 확인한다. SAML은 계속 활성 상태로 유지한다.

3. Entra 연결 설정

   같은 GitHub Enterprise Server 앱 → Provisioning → Get started → Automatic → Admin Credentials에서 Tenant URL·Secret Token 입력 → Test Connection → 성공 후 Save. 연결 시험 성공은 사용자 생성·역할·팀 권한의 성공을 의미하지 않는다.

4. 매핑과 범위 고정

   Mappings의 사용자·그룹 매핑을 검토한다. 기본 objectId → externalId, userPrincipalName → userName, email·active·이름 값을 확인한다. roles의 실제 갤러리 expression·출력 값을 보존하고 임의 상수로 바꾸지 않는다. Scope는 할당된 사용자·그룹만으로 설정·저장하고 알림 담당 및 대량 삭제 방지 설정을 검토한다.

5. 일반 사용자와 Owner 직접 할당

   Users and groups → Add user/group에서 일반 파일럿은 일반 역할, Owner 후보는 실제 제공되는 Enterprise Owner 역할로 직접 할당한다. 역할명이 다르면 앱·버전과 roles payload를 확인한다. Owner 그룹 상속만으로 승격을 추정하지 않는다. 그룹은 Security group만 사용하며 중첩 그룹과 Microsoft 365 그룹은 지원하지 않는다.

6. 일반 파일럿의 계정 생성·매칭 확인

   Provision on demand로 정확한 일반 파일럿 한 명을 선택해 실행한다. 이는 계정 상태를 쓰는 변경 작업이며 조회가 아니다. 대상 ID·externalId·active와 Steps의 실제 action·결과를 확인한 뒤 SAML 로그인도 별도로 시험한다. 이 성공을 Owner 역할 반영이나 조직·저장소 권한의 성공으로 해석하지 않는다.

7. Owner 제어 전환·적용

   복구 세션을 유지한 승인 창에서 Management Console의 Disable administrator demotion/promotion을 해제한다. 선택 상태이면 SCIM으로 enterprise owner를 부여할 수 없다. Save settings → 구성 적용 성공과 비상 접근 유지를 확인한 뒤 다음 정기 동기화 단계로 진행한다. 기존 SAML administrator claim에 의한 승격·강등 영향도 조사한다. 적용 실패나 복구 접근 상실 시 진행하지 않는다.

8. 승인된 파일럿 범위의 정기 동기화·Owner 검증

   Overview → Start provisioning으로 승인된 파일럿 범위 전체의 처리를 시작한다. 이미 Running이면 재시작하지 않고 다음 정기 동기화의 대상별 결과를 확인한다. Off·Stopped이면 중지 사유와 누적 변경을, Quarantine이면 원인을 먼저 해결한다. 실제 roles 출력·GHES Owner 목록·새 브라우저 SSO를 모두 확인한다. GHES의 SCIM Owner 프로비저닝 지원과 Microsoft의 on-demand 역할 프로비저닝 미지원은 다른 범위의 설명이다. Owner 후보의 on-demand는 계정 생성·매칭 확인에 한정하며 성공만으로 Owner 반영을 판정하지 않는다. 초기 전체 평가와 이후 증분 주기를 구분한다. 약 40분은 앱별 주기 확인이 필요한 일반 안내이며 전체 앱의 SLA나 개별 사용자 완료 보장이 아니다.

9. 검증 완료 후 대상 확대

   일반 사용자와 운영 Owner의 계정·SSO·역할을 각각 검증하고 setup 계정의 권한·built-in 로그인·PAT가 유지되는지 확인한 후 일상 관리를 위임하고 승인된 대상을 확대한다. built-in 생성 허용 해제는 선택 사항이며 복구 경로 영향을 검증하기 전에는 끄지 않는다. reset·재생성으로 우회하지 않는다.

5.2 Entra Provisioning logs부터 확인한다

1. 정확한 앱과 할당 이후 시간으로 조회

   Entra ID → Enterprise apps → 해당 GitHub Enterprise Server 앱 → Provisioning logs를 연다. Provisioning 화면에서 로그로 이동하는 UI라면 같은 앱·configuration인지 확인한다. Sign-in logs는 SAML 인증 기록이지 SCIM 생성 기록이 아니다. 앱의 service principal Object ID와 사용자 source Object ID를 먼저 대조하고, 시간 범위는 앱 할당 시각 이후로 잡는다. 화면의 시간대를 기록하여 UTC로 환산한다. 표시 이름·UPN만 같은 다른 앱이나 다른 사용자 로그를 섞지 않는다. F4 로그 목록을 참고한다.

2. 행의 Action·Status와 Steps를 함께 읽기

   사용자 행을 열어 Steps의 Import user → Determine scope → Match → Perform action을 확인한다. 실패 시 Test connection 단계도 확인한다. 매칭된 대상과 Modified properties의 externalId·userName·active·실제 roles를 대조한다. 실패 화면의 속성은 전송 시도 값일 수 있으므로 실제 반영으로 취급하지 않는다. F5 Steps와 F7 결과를 참고한다.

3. GHES와 같은 UTC 구간으로 상관 분석

   앱 Object ID, source Object ID, Action·Status, UTC 시각, Target ID, Change ID, 표시되는 job ID·request ID와 오류 본문을 승인된 기록에 남긴다. Change ID는 Entra 이벤트·Steps·변경 속성 연결 키이며 GHES request ID와 같은 값이라고 가정하지 않는다. GHES 감사 로그·SCIM 조회의 externalId와 SCIM User ID를 같은 UTC 구간에 대조한다. Token·개인정보를 제거한 뒤 공유한다.

조회 전용 진단: 기존 승인 토큰만 사용

다음은 Bash subshell에서만 토큰을 유지하는 GET 예시다. gh가 설치된 신뢰할 수 있는 관리자 PC에서 실행한다. 토큰 자체는 쓰기 권한도 가지므로 조회 명령이라고 읽기 전용 자격 증명으로 착각하지 않는다. 세션 녹화·환경 수집도 금지한다.

(
  set +x
  unset GH_DEBUG GH_TOKEN GITHUB_TOKEN GITHUB_ENTERPRISE_TOKEN GH_ENTERPRISE_TOKEN
  IFS= read -r -s -p 'Approved SCIM classic PAT: ' GH_ENTERPRISE_TOKEN
  printf '\n'
  test -n "$GH_ENTERPRISE_TOKEN" || exit 1
  export GH_ENTERPRISE_TOKEN
  export GH_PROMPT_DISABLED=1 GH_PAGER=cat
  gh api --hostname github.example.com --method GET \
    'scim/v2/Users?startIndex=1&count=10' \
    --jq '{totalResults, startIndex, itemsPerPage, Resources: [.Resources[] | {id, externalId, userName, active}]}'
)

Users는 대소문자를 구분한다. gh가 GHES의 /api/v3 접두어를 처리한다. 필요한 페이지에 한해 startIndex를 실제 반환 건수만큼 증가시키고 count·totalResults·itemsPerPage를 확인한다. 빈 페이지면 중단하며 gh --paginate로 일반 REST 페이지 규칙을 무조건 적용하지 않는다. scim/v2/Groups?startIndex=1&count=10도 같은 GET 방식으로 조회한다.

5.3 오류는 대상 사용자와 응답 본문으로 분류한다

5.4 퇴사·복귀와 좌석 검증

5.5 초기 동기화가 끝난 뒤 신규 사용자 1명 추가

Entra 디렉터리에 사용자를 만들었다는 사실만으로 GHES 앱에 할당되지는 않는다. 먼저 5.2 로그를 확인하고 다음 순서로 누락 지점을 좁힌다. 기존 계정 삭제·임의 역할 승격·전체 Restart provisioning으로 진단하지 않는다.

1. GHES 앱과 사용자 신원을 정확히 고정

   Enterprise apps의 예시 example-ghes 앱 Overview/Properties에서 service principal Object ID를 정확히 기록한다. Application (client) ID나 App registrations 객체 ID가 아니다. Admin Credentials의 Tenant URL은 https://github.example.com/api/v3/scim/v2, 일반형은 https://HOST/api/v3/scim/v2다. GHEC EMU의 https://api.github.com/scim/v2/enterprises/SLUG와 구분한다. 사용자 Overview의 Object ID를 source identity와 정확히 비교한다. 이것이 기본 매핑의 SCIM externalId이며 앱 Object ID와 다르다. 같은 UPN의 재생성 객체는 같은 사용자가 아니다.

2. 유효한 직접 할당 또는 그룹의 직접 멤버인지 확인

   앱 → Users and groups에서 사용자 직접 할당 또는 앱에 직접 할당된 Security group의 직접 멤버인지 확인한다. SecurityEnabled=true인 그룹을 사용한다. 중첩 그룹 멤버는 지원되지 않으며, 동적 그룹은 membership rule 평가·처리 완료를 먼저 확인한다. 그룹 평가 지연은 SCIM job 지연과 별개다. 빈 그룹이 있어도 별도로 유효한 사용자 직접 할당을 취소하지 않는다. F1 앱 할당을 참고한다.

3. app role·매핑·Scope를 분리해 점검

   앱 Owners는 Entra 앱 관리 권한이고 Users and groups의 app role 할당이 아니다. 직접 할당과 그룹 할당의 중복·서로 다른 역할, Default Access, roles 매핑 expression·실제 출력을 검토한다. Default Access 처리 여부는 앱의 역할·scoping 조건으로 확인하며 무조건 성공 또는 실패라고 단정하지 않는다. 일반 사용자의 누락을 Enterprise Owner 부여로 우회하지 않는다. Provisioning → Overview → Properties(기존 UI의 Settings)에서 Sync only assigned users and groups와 사용자 scoping filter·소스 활성 상태를 확인한다. F3 Scope·Properties를 참고한다.

4. 정상 실행 중이면 다음 증분 대상인지 확인

   Provisioning mode가 Automatic, status가 On, job이 Running이고 할당·Scope 조건을 충족하면 신규 사용자는 다음 증분 평가 대상이다. 최초 전체 sync를 다시 시작할 필요가 없다. 앱의 실제 주기·last cycle·진행 상황과 해당 사용자 로그로 확인한다. 긴급한 승인 대상 1명은 5.7 on-demand 분기를 사용한다.

5.6 Automatic 설정과 실행 상태를 구분한다

F2 Provisioning Overview에서 상태와 마지막 실행을 읽는다. Start provisioning은 선택한 1명만 보내는 버튼이 아니다. 시작·재개 시 현재 구성된 전체 Scope의 생성·변경·비활성화 영향을 승인받는다. Restart provisioning은 watermark를 초기화하여 전체 소스 재평가를 유발하므로 신규 1명 추가나 로그 0건의 기본 해결책으로 사용하지 않는다.

5.7 Provision on demand: 승인된 1명의 실제 쓰기

1. 실행 전 변경 대상과 상태 승인

   정확한 GHES 앱·Tenant URL·source Object ID·할당·필터를 재확인한다. on-demand는 미리보기나 조회가 아니며 Create·Update·Disable을 수행할 수 있다. 앱에서 할당 해제된 사용자를 선택하면 비활성화할 수도 있다. Entra에서 비활성화·삭제되어 검색되지 않는 사용자를 같은 방식으로 처리할 수 있다고 가정하지 않는다. 새 할당은 on-demand에 전파되기까지 몇 분 걸릴 수 있다.

2. 선택한 사용자 한 명 실행

   앱 → Provisioning → Provision on demand에서 예시 pilot.reader@example.com을 검색하고 source Object ID로 확인한 한 명을 선택한 뒤 승인된 경우에만 Provision을 누른다. GHES의 long-lived bearer PAT 방식은 on-demand를 위해 자동 job을 Stop할 필요가 없다. OAuth 방식인 다른 앱의 정지 요구를 GHES에 적용하지 않는다. F6 사용자 선택를 참고한다.

3. 결과를 판정하고 다음 검증으로 이동

   View details / Steps에서 scope·match·action과 Target ID를 확인한다. Microsoft의 통상 30초 미만은 on-demand job 처리 안내이지 보장 시간이나 GHES 사용자 UI·조직·권한의 SLA가 아니다. 이미 정확한 대상의 Success + Create가 있으면 계정 생성 때문에 다시 40분을 기다리지 않는다. GHES의 같은 계정·active·SSO와 필요한 팀 권한을 확인한다. 할당 전파 전 Not assigned라면 몇 분 후 범위와 로그를 재확인하며 반복 실행으로 덮지 않는다. F7 결과를 참고한다.

5.8 Cloud 한정: 해시 이름·Suspended 계정의 판정

목록 존재 ≠ 조직 멤버십 ≠ consumed Cloud licenses ≠ 설치된 GHES capacity다. Cloud 감사 로그의 user.rename·user.suspend·external_identity.deprovision을 같은 UTC 구간의 Cloud용 Entra Enterprise app Provisioning logs와 대조한다. GHES 앱 로그를 대신 사용하지 않는다. 앱 Object ID·Tenant URL·source Object ID·실제 요청 종류로 원천을 확인하기 전에는 계정 삭제·임의 이름 변경·앱 재할당을 하지 않는다. soft 복구 가능성이 곧 복귀 승인은 아니다.

공식 근거: Entra 초기·증분·범위·격리 · Entra on-demand·전파 지연·역할 제한 · Entra 로그·Change ID·Steps · 3.21 정확한 GHES Tenant URL · Cloud EMU 퇴사·복귀·감사 이벤트 · Cloud·Server 라이선스 소비 기준

공식 근거: 3.21 SCIM setup·Owner 옵션 · 3.21 기존 사용자 매칭 · 3.21 SCIM API·pagination · 3.21 단일 쓰기 원천·가용 좌석 · 3.21 신원·프로비저닝 오류 · 3.21 퇴사·복귀 · GHES 좌석 기준 · Entra 최신 provisioning UI · 3.17 릴리스 · 3.14 릴리스

공식 화면 예시: F1 할당 · F2 Provisioning Overview · F3 Scope·Properties · F4 로그 목록 · F5 Steps · F6 on-demand 선택 · F7 결과. 연결된 이미지는 공식 문서의 일반 예시이며 실제 환경의 실행 증거를 대신하지 않는다. UI 버전 차이는 실제 앱에서 확인한다.

Phase 6조직·팀·저장소의 최소 권한

상세 참조 장 · STEP 07의 실행 순서·화면으로 돌아가기 →

담당: 조직 Owner·보안·개발 리드선행: 파일럿 SCIM 성공산출물: 조직 팀 매핑·샘플 저장소·권한 시험

6.1 조직·팀·저장소 권한 모델

1. 사용자 → 그룹 → 팀 연결

   Phase 5에서 사용자 생성, Security group 프로비저닝, 그룹 멤버 반영을 순서대로 확인한다. Enterprise settings → Identity provider에서 그룹을 읽어 확인한다. 조직 → Teams → New team에서 이름을 입력하고 Identity Provider Groups → Select Groups로 연결 후 Create team 한다. 사용자가 연결된 팀에 들어가면 조직 멤버가 자동 추가된다.

2. 기존 팀 전환은 별도 승인

   기존 팀 첫 연결 전 수동 추가 멤버를 제거해야 한다. 팀 이름·권한을 복제한 파일럿 팀으로 먼저 시험하고, 기존 멤버·저장소 권한을 기록한 후 영향 승인 창에서 전환한다. 사용자 계정 삭제가 아니다. 연결된 팀은 부모·자식 팀으로 중첩할 수 없고 팀 maintainer 지정에도 제약이 있다. 연결 해제 시 다른 가입 경로가 없으면 조직에서도 제거될 수 있다.

3. 저장소 접근 부여

   조직에 Private 샘플 저장소를 만들고 저장소 Settings → Collaborators and teams에서 조직 팀별 Read·Write·Maintain·Admin을 업무에 맞게 부여한다. IdP는 팀 멤버십을, GHES는 팀의 저장소 역할을 관리한다. 이 절차는 조직 팀 기준이다. Cloud Enterprise Teams의 UI·권한 모델을 GHES 3.21에 그대로 적용하지 않는다.

4. 보호 규칙을 실제로 강제

   저장소의 main 대상 ruleset 또는 branch protection에서 PR 승인, 필요한 status checks, Require review from Code Owners와 우회 권한을 명시한다. CI가 실제 보고하는 check 이름을 선택한다. CODEOWNERS 파일만 추가하면 리뷰 요청은 생겨도 병합 차단이 자동 보장되지는 않는다. 미승인·실패 check PR로 병합 거부를 검증한다.

5. 앱·외부 인력·토큰 정책

   조직 소유권 변경·외부 협업자 초대·저장소 생성 권한을 제한한다. 외부 인력은 회사의 IdP 객체·계약 종료·외부 식별자 정책에 따라 온보딩하고 GHES outside collaborator 동작을 확인한다. Cloud EMU의 일괄 외부 협업 제한을 전제하지 않는다. 일반 PAT 만료·최소 scope·SSO 연계 요구·앱 승인을 GHES 버전별로 확인한다. 내부 자동화는 지원되는 작업에 GitHub App의 선택 저장소·최소 permissions를 우선하고, SCIM classic PAT 예외와 분리한다.

6.2 개발자 온보딩 템플릿

README, 기여 절차, PR 템플릿, CI와 .github/CODEOWNERS를 샘플 저장소에 둔다. 아래 패턴은 base branch의 CODEOWNERS 내용 예시이며 팀은 visible·Write 조건을 만족해야 한다.

* @example-org/example-reviewers
/.github/ @example-org/example-reviewers

git clone https://github.example.com/example-org/example-private-project.git
git -C example-private-project config user.name 'Example Developer'
git -C example-private-project config user.email 'developer@example.com'
git -C example-private-project remote -v

git config user.*는 커밋 표시 정보이지 로그인·SSO 설정이 아니다. Git용 SSH 공개키는 개인 GitHub 계정에 등록하며 관리 Console의 SSH 122 키와 분리한다. Cloud의 토큰 SSO 승인 UI가 동일하다고 가정하지 말고 GHES 문서·현재 사용자 설정을 확인한다.

git ls-remote https://github.example.com/example-org/example-private-project.git HEAD

6.3 권한 수용 시험

감사 로그와 분기별 Owner·앱 설치·토큰·SSH 키 검토 책임자를 정한다. GHES에서 제공되는 보안 정책과 라이선스를 확인하며 Cloud 전용 AI Controls가 보편적으로 존재한다고 쓰지 않는다. AI 기능은 Copilot 범위에서 별도로 검토한다.

공식 근거: 3.21 IdP 그룹과 조직 팀 · 3.21 저장소 가시성 · 3.21 CODEOWNERS 강제 조건 · 3.21 보호 브랜치

Phase 7GitHub Connect와 라이선스 동기화

상세 참조 장 · STEP 08의 실행 순서·화면으로 돌아가기 →

담당: GHES·Cloud Owner·구매·개인정보 담당선행: 계약 자격·egress·전송 승인산출물: 연결 대상·선택 기능·사용량 대조

GitHub Connect는 GHES와 Cloud를 제한된 기능으로 연결한다. 사용자 프로비저닝이나 저장소 마이그레이션이 아니다. Cloud 계정이 자동 생성되지 않고 설치된 GHES 라이선스의 좌석 수도 자동 증가하지 않는다.

7.1 연결 전 승인 입력

1. 브라우저 연결

   GHES와 GitHub.com에 각각 로그인한다. GHES 프로필 → Enterprise settings → GitHub Connect → Enable GitHub Connect. Cloud 로그인·승인 흐름에서 대상 enterprise를 선택하고 해당 항목의 Connect를 누른다. Choose enterprise 화면의 대상 이름과 약관을 검토한다. Management Console에서 SCIM 토큰을 붙이는 절차가 아니다.

2. 원하는 기능만 선택

   GHES GitHub Connect 화면의 License sync → Enable을 별도로 선택한다. 필요할 때만 GitHub.com actions, Dependabot alerts, unified search/contributions 등 현재 버전에서 지원하는 기능을 승인한다. Actions 실행·runner와 보안 기능의 GHAS/Code Security/Secret Protection 자격은 별도이다. Connect 하나로 전부 활성화되지 않는다.

3. 첫 동기화와 증거 수집

   자동 사용자 라이선스 동기화는 GHES 사용량을 GHEC에 보내는 주 단위 작업이며 키 갱신이 아니다. 즉시 외부 데이터 전송을 승인했다면 GHES Enterprise settings → Settings → License(또는 Licensing) → License sync → Sync now를 사용한다. 이는 단순 조회가 아니라 데이터 전송이다. Cloud Billing and licensing → Licensing에서 해당 Server source·마지막 동기화 시각·상태를 읽어 확인한다.

4. 불일치 분석

   GHES active·suspended 사용자, GHES 기본 이메일, Cloud 신원·검증 이메일, 중복 제거 결과를 대조한다. Cloud 사용량 화면의 GitHub Connect server usage synced / never synced / Server usage uploaded 구분과 시각을 남긴다. 네트워크 실패·잘못된 연결 대상·이메일 불일치를 구분하고 무작정 재연결하지 않는다.

7.2 전송·중복 제거·비용은 별도 판정

curl --head --silent --show-error --connect-timeout 10 https://api.github.com

7.3 세 가지 동기화 시계와 라이선스 파일 적용을 구분한다

별도 파일 적용 시간: 새 GHES 라이선스 키를 승인 후 Upload하면 백그라운드로 적용되며 화면 반영에 몇 분 걸릴 수 있다. 이는 위 세 동기화 주기와 다르다. 키 만료일도 별도로 추적한다. metered 방식의 생성 키는 문서상 1년 유효하며 현재 파일의 실제 만료일·갱신 알림을 확인한다. weekly sync나 사용자 증분이 만료를 연장하지 않는다.

7.4 주간 전송의 성공은 토글이 아니라 상태로 확인한다

License sync의 Enable은 설정 증거일 뿐 전송 성공 증거가 아니다. GHES Enterprise settings → Settings → License / Licensing → License sync → Sync now는 사용자 ID·이메일 등 사용량 데이터의 외부 전송이므로 목적·수신 enterprise·전송 범위 승인 후 실행한다. 실행 전후 Cloud Billing and licensing → Licensing의 해당 Server source, last sync, 성공·실패 또는 never synced 상태를 기록한다. 수동 실행 역시 GHES capacity를 늘리거나 라이선스 키를 재발급하지 않는다.

7.5 신규 사용자와 키 재발급은 조건부로 연결한다

1. 설치 capacity·만료·소비량을 먼저 읽기

   신규 사용자 한 명마다 무조건 키를 재생성하지 않는다. 현재 GHES License 화면의 설치 좌석·사용량·만료, Cloud의 consumed Cloud licenses, 계약·과금 방식을 각각 대조한다. metered Server 키는 생성 시점의 consumed Cloud licenses를 기준으로 capacity가 정해지므로 Cloud 계정 목록 수나 결합 Total consumed를 대신 넣지 않는다.

2. 부족·갱신 필요가 확인된 경우에만 파일 변경 승인

   현재 설치 capacity가 필요한 사용량에 부족하거나 갱신이 필요한 경우, 자격·계약·다운로드 가능한 새 capacity를 확인한 뒤 승인받아 새 키 생성·다운로드·GHES 업로드를 수행한다. Cloud Licensing의 Generate new license 안내는 metered Cloud 소비 증가 또는 만료 30일 이내 등의 조건으로 나타난다. 업로드 뒤 백그라운드 반영과 실제 좌석·만료일을 다시 확인한다. Cloud에서 먼저 모든 사람을 만들어야만 GHES SCIM 생성이 된다는 보편적 순서로 바꾸지 않는다.

7.6 운영자 인수인계 체크리스트

완료·실패·미확인 항목을 구분하고 각 증거 위치, 담당자, 승인된 다음 조치를 인계한다. 요약 상태만으로 계정·권한·연결의 종단 간 검증을 대신하지 않는다.

공식 근거: Entra 주기·상태 · Entra on-demand 시간·제한 · 3.21 연결 메타데이터의 주간 시각 · 3.21 키 생성 조건·metered capacity·유효기간 · 3.21 키 업로드·백그라운드 적용 · 3.21 SCIM 생성과 가용 라이선스

공식 근거: 3.21 GitHub.com Connect 자격·UI · 3.21 기능·전송 데이터 · 3.21 자동 license sync · 3.21 수동 실행·파일 대안 · 3.21 Cloud/Server 병용 · 3.21 사용량 기반 결제 · 3.21 이메일 중복 제거 · Cloud 현재 사용량 UI · Copilot 현재 제품 범위 · Cloud agent 현재 호스팅 조건

Phase 8Actions 제어 서비스와 외부 저장소

상세 참조 장 · STEP 09의 실행 순서·화면으로 돌아가기 →

담당: GHES·Azure·Entra·보안 담당선행: TLS·DNS·라이선스·용량·백업산출물: 인증 선택표·경로표·쓰기 테스트·구성 적용 기록

8.1 구성과 용량을 먼저 결정한다

8.2 인증 분기와 UI 입력값

https://github.example.com/_services/token/.well-known/openid-configuration
https://github.example.com/_services/token/.well-known/jwks

8.3 비밀을 출력하지 않는 사전 조회

아래 Azure CLI는 이미 인증된 승인 세션에서 실행한다. 계정 전환이 필요하면 현재 출력을 확인한 뒤 별도 승인으로 로그인한다. APP_TENANT_ID, STORAGE_TENANT_ID, SUBSCRIPTION_ID, APP_CLIENT_ID, STORAGE_SP_OBJECT_ID는 담당자가 확인한 값이며 비밀번호가 아니다. 연결 문자열은 이 변수 목록에 포함하지 않는다.

az account show --query "{subscription:id,tenant:tenantId,state:state}" -o json
az storage account show --resource-group rg-ghes-storage --name storageexample --query "{id:id,kind:kind,sku:sku.name,location:location,httpsOnly:enableHttpsTrafficOnly,minTLS:minimumTlsVersion,sharedKey:allowSharedKeyAccess,publicNetwork:publicNetworkAccess,firewallDefault:networkRuleSet.defaultAction,blobEndpoint:primaryEndpoints.blob}" -o json

az login --tenant "$APP_TENANT_ID" --allow-no-subscriptions --output none

OIDC를 선택한 경우에만 다음 앱/Federated credential 조회를 수행한다. 앱 소유 tenant에서 읽기 권한이 있어야 한다. Credentials-based의 403을 고친다고 무관한 앱에 RBAC를 추가하지 않는다.

az ad app show --id "$APP_CLIENT_ID" --query "{clientId:appId,appObjectId:id,displayName:displayName}" -o json
APP_OBJECT_ID=$(az ad app show --id "$APP_CLIENT_ID" --query id -o tsv) &&
test -n "$APP_OBJECT_ID" &&
az ad app federated-credential list --id "$APP_OBJECT_ID" --query "[].{name:name,issuer:issuer,subject:subject,audiences:audiences}" -o json

az login --tenant "$STORAGE_TENANT_ID" --output none
az account set --subscription "$SUBSCRIPTION_ID"

az ad sp show --id "$APP_CLIENT_ID" --query "{clientId:appId,spObjectId:id,appOwnerTenant:appOwnerOrganizationId}" -o json
STORAGE_SCOPE=$(az storage account show -g rg-ghes-storage -n storageexample --query id -o tsv) &&
test -n "$STORAGE_SCOPE" &&
az role assignment list --scope "$STORAGE_SCOPE" --assignee-object-id "$STORAGE_SP_OBJECT_ID" --include-inherited --fill-principal-name false --query "[].{role:roleDefinitionName,scope:scope,principalId:principalId}" -o json

8.4 경로 확인 → 저장소 쓰기 테스트 → 설정 적용

1. 경로를 각각 승인한다

   GHES → Blob, runner → GHES hostname/API 및 필요한 Blob 경로, Entra → OIDC metadata/JWKS를 별도 항목으로 검토한다. Entra SCIM → GHES의 inbound 성공은 Blob outbound 성공 증거가 아니다. PE의 private DNS zone·VNet 연결·실제 서비스의 DNS 응답·출구 NAT/firewall을 확인한다. HTTP proxy 제외 목록의 .localhost, 127.0.0.1, ::1과 내부 저장소 경로도 공식 문서에 맞춘다.

2. 연결만 확인한다

   승인된 GHES 관리 셸에서 아래 무인증 curl을 실행한다. PC의 같은 명령은 보조 자료일 뿐이다. 인증 없는 400/403은 HTTP 도달 가능성을 보여도 실제 GHES 서비스의 proxy 환경이나 읽기·쓰기 권한을 증명하지 않는다. TLS 오류를 -k로 우회하지 않는다.

3. Test storage settings — 변경 승인 필요

   Management Console에서 승인된 테스트 범위에 대해 실행한다. create/upload/delete를 포함하는 쓰기 검증으로 취급한다. 읽기 전용 점검으로 분류하지 않는다. 테스트 시각과 성공/오류 코드만 기록하고 잔여 테스트 객체 및 정리 결과를 저장소 담당자가 확인한다.

4. Save settings — 서비스 재시작 가능

   테스트 통과 후 공지된 작업창에서 저장한다. configuration run 종료까지 기다리고 진행 화면·구성 로그의 성공/실패 단계·시각을 기록한다. 진행 중 재저장하거나 ghe-config-apply를 중복 실행하지 않는다. 실패 시 원인 분석과 승인된 복구 절차로 돌아가며 저장소를 임의 교체하지 않는다.

curl --silent --show-error --connect-timeout 10 --max-time 20 --output /dev/null --write-out "HTTP %{http_code}\n" https://storageexample.blob.core.windows.net/
ghe-config core.github-hostname

구성 진행은 Management Console의 진행/로그 화면을 우선 사용한다. 추가 로그는 해당 버전의 관리 유틸리티 도움말과 공식 지원 절차로 범위를 좁혀 확인한다. 원본 전체 로그를 공유하지 말고 configuration run 단계·UTC 시각·마스킹된 오류만 전달한다.

8.5 403을 인증·권한·네트워크로 나누어 조사한다

StorageBlobLogs는 Blob 진단 설정이 Log Analytics로 수집 중일 때만 조회 가능하다. 진단 설정 활성화는 별도 변경·비용 승인이다. 아래는 실패 재현 직후 15분 범위 예시이며, URI/SAS/인증 hash는 출력하지 않는다. 필요한 식별자는 내부 제한 기록에서만 상관 분석한다.

StorageBlobLogs
| where TimeGenerated > ago(15m)
| where AccountName == "storageexample"
| project TimeGenerated, OperationName, StatusCode, StatusText,
    AuthenticationType = column_ifexists("AuthenticationType", ""),
    CorrelationId = column_ifexists("CorrelationId", ""),
    ClientRequestId = column_ifexists("ClientRequestId", "")
| order by TimeGenerated desc
| take 50

공식 근거: Actions 개요·최소 자원 · Azure 설치·25% 증설 · 3.21 Azure 인증 · 3.22 Azure 인증 · 관리 명령 · Azure 403 · Federated credential CLI · StorageBlobLogs 스키마

Phase 9격리 runner와 workflow 종단 검증

상세 참조 장 · STEP 10의 실행 순서·화면으로 돌아가기 →

담당: Runner 운영·조직 관리자·pilot 개발자선행: Phase 8 적용 성공·private 테스트 저장소산출물: runner 그룹·실행 URL·artifact 비교·접근 차단 증거

9.1 appliance와 격리한 실행 VM을 준비한다

1. 생성된 설치 명령을 실행한다 — 변경

   VM의 전용 작업 디렉터리에서 UI 명령을 순서대로 복사한다. 일반 OS 계정으로 압축 해제·config를 실행한다. 등록 URL은 조직 URL이어야 한다. UI의 등록 token은 1시간 만료되는 비밀이며 PAT와 다르다. token을 문서에 전사하지 않고 로그·셸 추적을 끈 승인 세션에서 사용한다. 만료되면 UI에서 다시 발급한다.

2. 그룹·레이블을 확인한다

   등록 단계에서 pilot-linux 그룹과 ghes-pilot 레이블을 선택한다. 기본 self-hosted/Linux/X64 레이블도 확인한다. UI에서 Online/Idle을 확인한다. production secret, Docker socket, 운영망 접근을 시험 runner에 제공하지 않는다.

3. 서비스로 전환한다 — OS별 승인

   대화형 run 프로세스를 먼저 종료한다. 아래 Linux systemd 서비스 설치만 승인된 관리자 권한으로 실행한다. macOS는 공식 launchd 절차, Windows는 config의 서비스 설치 선택과 해당 서비스 계정을 따른다. 전체 workflow를 sudo/root로 실행하지 않는다.

sudo ./svc.sh install runneruser
sudo ./svc.sh start

sudo ./svc.sh status

9.2 읽기 조회와 ref 검증

이미 github.example.com에 인증된 gh를 사용한다. 조직 runner 목록의 classic PAT 기준 요구 scope는 admin:org이며 호출자는 조직 관리 권한이 있어야 한다. 여기서는 조회만 하지만 자격 증명 자체가 읽기 전용이라는 뜻은 아니다. 403은 runner 0대가 아니며 권한 담당자에게 전달한다. 토큰을 명령에 넣지 않는다.

gh api --hostname github.example.com --paginate orgs/testorg/actions/runners --jq ".runners[] | {name,status,busy,labels:[.labels[].name]}"
gh api --hostname github.example.com repos/actions/checkout/git/ref/tags/v4 --jq .object.sha
gh api --hostname github.example.com repos/actions/upload-artifact/git/ref/tags/v3-node20 --jq .object.sha
gh api --hostname github.example.com repos/actions/download-artifact/git/ref/tags/v3-node20 --jq .object.sha

9.3 최소 workflow로 실행과 artifact 왕복을 증명한다

승인된 private testorg/ghes-smoke 저장소 기본 branch에 .github/workflows/ghes-smoke.yml로 저장한다. 파일 생성·commit·push 또는 Contents API PUT은 모두 변경이다. 샘플은 Linux bash 전용이며 synthetic payload만 사용한다. 세션·운영 파일을 artifact로 올리지 않는다.

name: GHES smoke
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  smoke:
    runs-on: [self-hosted, linux, x64, ghes-pilot]
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Prepare synthetic payload
        id: payload
        shell: bash
        run: |
          set -euo pipefail
          work="$RUNNER_TEMP/ghes-smoke-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
          mkdir -m 700 "$work"
          printf 'synthetic-ghes-smoke\n' > "$work/payload.txt"
          printf 'work=%s\n' "$work" >> "$GITHUB_OUTPUT"
      - uses: actions/upload-artifact@v3-node20
        with:
          name: smoke-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ steps.payload.outputs.work }}/payload.txt
          if-no-files-found: error
          retention-days: 1
      - uses: actions/download-artifact@v3-node20
        with:
          name: smoke-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ steps.payload.outputs.work }}/download
      - name: Compare
        shell: bash
        env:
          SMOKE_DIR: ${{ steps.payload.outputs.work }}
        run: cmp "$SMOKE_DIR/payload.txt" "$SMOKE_DIR/download/payload.txt"
      - name: Clean only this run
        if: ${{ always() && steps.payload.outputs.work != '' }}
        shell: bash
        env:
          SMOKE_DIR: ${{ steps.payload.outputs.work }}
        run: |
          rm -f -- "$SMOKE_DIR/payload.txt" "$SMOKE_DIR/download/payload.txt"
          if [ -d "$SMOKE_DIR/download" ]; then rmdir -- "$SMOKE_DIR/download"; fi
          rmdir -- "$SMOKE_DIR"

gh workflow run ghes-smoke.yml --repo github.example.com/testorg/ghes-smoke --ref main

gh run list --repo github.example.com/testorg/ghes-smoke --workflow ghes-smoke.yml --limit 5 --json databaseId,status,conclusion,url
gh run view "$RUN_ID" --repo github.example.com/testorg/ghes-smoke --json status,conclusion,jobs,url

공식 근거: Runner 등록·token · OS별 서비스 · 통신·ephemeral · 조직 runner API · Actions 공급 · Upload GHES 지원 · Upload Node20 ref · Download Node20 ref

Phase 10Packages 저장소와 private 배포

상세 참조 장 · STEP 11의 실행 순서·화면으로 돌아가기 →

담당: GHES·Storage·패키지 운영·pilot 개발자선행: 별도 Blob·TLS·시험 namespace·preview 승인산출물: ecosystem 설정·digest·권한 검증·복구 계획

10.1 Actions와 별개로 저장소·생태계를 설계한다

10.2 DNS·TLS·포트를 검증한다

curl --silent --show-error --connect-timeout 10 --max-time 20 --output /dev/null --write-out "HTTP %{http_code}\n" https://containers.github.example.com/v2/

10.3 인증 → 작은 private image push/pull

일반 GHES 사용자명 USER를 실제 pilot 로그인으로 바꾼다. SCIM 식별자나 임의의 '%' 접미사를 만들지 않는다. 개인 인증은 해당 GHES에서 발급한 PAT classic의 read:packages / write:packages와 실제 package·연결 저장소 권한이 필요하다. fine-grained PAT로 대체된다고 가정하지 않는다. 삭제 scope는 필요한 관리자에게만 부여한다. repo scope는 registry·private repository 요구를 확인해 최소화하며 무조건 선택하지 않는다.

아래는 승인 후 변경하는 선택적 synthetic 시험이다. bash에서 실행하고 Docker·전용 credential helper가 준비되어 있어야 한다. 토큰은 무표시 입력으로 받으며 credential helper 없이는 Docker 설정에 남을 수 있다. 승인한 private testorg namespace만 사용하고 public registry에 push하지 않는다. 외부 base image 없이 FROM scratch로 만든 데이터 전용 image이며 실행용 컨테이너가 아니다.

(
set -euo pipefail
set +x
work="./ghes-package-smoke-$(date -u +%Y%m%dT%H%M%SZ)-$$"
mkdir -m 700 "$work"
cleanup_auth() {
  original_status=$?
  unset CR_PAT
  if ! docker logout containers.github.example.com; then
    printf 'Credential cleanup failed; follow the approved cleanup procedure.\n' >&2
    test "$original_status" -ne 0 || original_status=1
  fi
  exit "$original_status"
}
trap cleanup_auth EXIT
read -r -s -p 'GHES classic PAT: ' CR_PAT
printf '\n'
test -n "$CR_PAT"
printf '%s' "$CR_PAT" | docker login containers.github.example.com -u USER --password-stdin
unset CR_PAT
printf 'synthetic-ghes-package\n' > "$work/payload.txt"
printf '%s\n' 'FROM scratch' 'COPY payload.txt /payload.txt' \
  'LABEL org.opencontainers.image.source="https://github.example.com/testorg/ghes-smoke"' > "$work/Dockerfile"
image="containers.github.example.com/testorg/ghes-smoke:smoke-$(date -u +%Y%m%d%H%M%S)-$$"
docker build --tag "$image" "$work"
docker push "$image"
docker image inspect "$image" --format '{{json .RepoDigests}}'
printf 'Test image: %s\n' "$image"
rm -- "$work/payload.txt" "$work/Dockerfile"
rmdir -- "$work"
)

다운로드 증명은 캐시 없는 별도 승인 Docker daemon에서 수행한다. 같은 daemon의 pull은 로컬 레이어를 재사용하여 Blob 다운로드 장애를 놓칠 수 있다. 아래 PACKAGE_DIGEST에는 위 push가 반환한 전체 sha256 digest를 넣고, USER에는 read:packages와 실제 package 읽기 권한이 있는 일반 pilot을 사용한다. 별도 PC여도 동일 원격 Docker daemon을 사용하면 독립 검증이 아니다.

(
set -euo pipefail
set +x
: "${PACKAGE_DIGEST:?Set the approved push digest before this test}"
cleanup_auth() {
  original_status=$?
  unset CR_PAT
  if ! docker logout containers.github.example.com; then
    printf 'Credential cleanup failed; follow the approved cleanup procedure.\n' >&2
    test "$original_status" -ne 0 || original_status=1
  fi
  exit "$original_status"
}
trap cleanup_auth EXIT
read -r -s -p 'Pilot read-only classic PAT: ' CR_PAT
printf '\n'
test -n "$CR_PAT"
printf '%s' "$CR_PAT" | docker login containers.github.example.com -u USER --password-stdin
unset CR_PAT
image="containers.github.example.com/testorg/ghes-smoke@$PACKAGE_DIGEST"
docker pull "$image"
docker image inspect "$image" --format '{{json .RepoDigests}}'
)

10.4 Actions의 GITHUB_TOKEN 경로

workflow 저장소에 연결되어 있고 해당 저장소에 package 접근이 허용된 경우 아래 인증을 사용한다. workflow 수준의 permissions와 job steps에 각각 병합한다. Docker 준비는 runner에서만 한다. 기존 CLI-push package는 연결/Actions access 권한을 확인해야 하며, packages: write 선언만으로 다른 저장소 package 권한이 생기지 않는다. secrets.GITHUB_TOKEN을 별도 PAT로 생성해 저장하지 않는다.

permissions:
  contents: read
  packages: write
# 기존 job의 steps에 병합할 단계
steps:
  - name: Authenticate to this GHES registry
    shell: bash
    env:
      PACKAGE_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      PACKAGE_USER: ${{ github.actor }}
    run: |
      set +x
      printf '%s' "$PACKAGE_TOKEN" | docker login containers.github.example.com \
        -u "$PACKAGE_USER" --password-stdin
  # 승인된 synthetic image build/push 단계를 이 사이에 추가
  - name: Logout
    if: ${{ always() }}
    run: docker logout containers.github.example.com

10.5 장애·백업·완료 판정

공식 근거: 3.21 Azure Packages · 3.22 Azure Packages · 자원·생태계 · Ecosystem toggles · Container registry·인증 · DNS·TLS host map · 백업 서비스 · Backup Utilities 전환

공식 근거: Docker pull·레이어 캐시

Phase 11Copilot 계정·데이터·지원 경계

상세 참조 장 · STEP 11의 실행 순서·화면으로 돌아가기 →

담당: Cloud owner·구매·보안·GHES 관리자·pilot 개발자선행: 계약 경로·데이터 반출·클라이언트 승인산출물: 좌석/정책표·비관리자 pilot·지원 범위·회수 계획

11.1 구매·계정 경로를 선택한다

11.2 Cloud 경로의 pilot UI와 실행 순서

1. 책임자·승인표를 만든다

   구매 담당은 상품/좌석/예산, Cloud enterprise owner는 AI controls, 보안 담당은 모델·클라이언트·MCP·데이터 반출, GHES 관리자는 코드 접근을 담당한다. 허용 IDE/CLI 버전, 모델, repository, tool별 read/write 범위와 폐기 일정을 작성한다.

2. 좌석과 정책을 적용한다 — 변경

   Cloud enterprise의 Copilot access 관리 화면에서 pilot을 할당한다. AI controls에서 모델·클라이언트·agent·MCP 관련 정책을 검토한다. 직접 할당 사용자는 Policies for enterprise-assigned users도 확인한다. GHES Management Console의 Actions/Packages 화면에서 설정하는 것이 아니다.

3. 개발자 로그인과 출구를 분리 확인한다

   IDE의 Copilot 로그인에서 라이선스 계정을 선택한다. CLI 일반 Cloud 로그인도 github.com 또는 GHE.com 경로를 사용한다. github.example.com을 Cloud Copilot 로그인 host로 무조건 넣지 않는다. 인증·모델 호출의 최신 공식 allowlist와 proxy CA를 승인하고 TLS 검증을 유지한다. GHES clone/push 인증은 별도로 준비한다.

4. synthetic 문맥으로 시험한다

   승인된 private testorg 저장소의 무해한 예제 함수만 열고 ‘이 함수의 단위 테스트 초안을 제안하라’고 요청한다. 첫 시험은 제안 검토로 제한하고 파일/명령/MCP 쓰기 실행은 금지한다. 모델 응답·라이선스 인식·정책 차단·GHES read 접근 결과를 각각 기록한다.

5. 비관리자와 차단 조건을 확인한다

   pilot 일반 사용자로 재현하고, 승인된 비허용 모델/도구 또는 테스트 계정으로 차단을 확인한다. 광범위 토큰을 발급해 실패를 숨기지 않는다. 응답 원문보다 성공/거부, client·model 버전, 시각, 정책 식별자를 보관한다.

11.3 CLI/SDK BYOK·3.22 preview를 구분한다

3.22 preview가 승인·구성된 경우에만 아래 로컬 설정을 사용한다. 사전에 해당 GHES에 인증된 gh가 있어야 한다. 토큰은 stdout에 인쇄하지 않고 동적으로 받는다. API key 설정이나 preview 활성화를 이 명령이 대신하지 않는다.

set +x
COPILOT_PROVIDER_GHES_HOST=github.example.com
if COPILOT_PROVIDER_GHES_TOKEN="$(gh auth token --hostname "$COPILOT_PROVIDER_GHES_HOST")" &&
   test -n "$COPILOT_PROVIDER_GHES_TOKEN"; then
  export COPILOT_PROVIDER_GHES_HOST COPILOT_PROVIDER_GHES_TOKEN
  export COPILOT_OFFLINE=true
  printf 'Client environment prepared. Start only the approved CLI session.\n'
else
  unset COPILOT_PROVIDER_GHES_TOKEN COPILOT_PROVIDER_GHES_HOST COPILOT_OFFLINE
  printf 'STOP: no approved GHES token was retrieved.\n' >&2
fi

11.4 운영 정책·장애 분류와 인수

공식 근거: Copilot 요금제·GHES 경계 · Business 전용 enterprise · Cloud/Server 청구 구분 · Cloud 정책·AI controls · 좌석 할당 · Cloud CLI 인증 · 네트워크 allowlist · 선택 참고: EMU · BYOK · SDK BYOK · Content exclusion · 문맥과 책임 있는 사용 · Cloud agent · 3.22 릴리스 · 3.22 CLI technical preview

최종 검토일: 2026-09-19. Cloud/CLI 문서는 지속 변경된다. 위 날짜는 공개 문서 검토일이지 실제 고객 환경 인증일·지원 보증일이 아니다. rollout 전 해당 버전·계약·정책을 다시 확인한다.

Phase 12모니터링·감사·운영 점검

상세 참조 장 · STEP 12의 실행 순서·화면으로 돌아가기 →

담당: 운영·보안·라이선스 담당선행: 입력표·관리 접근·수집/반출 승인산출물: 기준선·점검표·알림 시험·제한된 증거

12.1 매일 보는 화면과 정상·실패 분기

1. 접속·시간·대상 확인

   Site admin → Management Console → Monitor. HA/cluster는 노드 선택을 확인하고 같은 시간대의 정상 기준선과 비교합니다. 장애 시작·끝은 UTC로 기록합니다.

2. 운영 상태에서 원인으로 이동

   Operational Health에서 이상 구간을 찾고 System & Application Insights의 CPU·Memory·Storage·Application Health·Background jobs·Actions를 비교합니다. CPU만 보지 말고 I/O 지연, 디스크 포화, 요청 큐, 백그라운드 적체와 배포 시점을 함께 봅니다.

3. 이상 시 변경보다 증거 확보

   노드·UTC 구간·지표·영향 기능을 먼저 남깁니다. 인증 오류, 스토리지 지연, Runner 부족을 구분하고 담당자에게 전달합니다. 서비스 재시작·확장·에이전트 설치를 일상 조회 명령에 섞지 않습니다.

ssh -p 122 admin@HOSTNAME
ghe-version
ghe-service-list
ghe-system-info
ghe-license info
ghe-license check
df -h / /data/user

12.2 제한된 로그 조사와 지원 자료

조회할 UTC 시작·끝을 먼저 지정: 승인된 관리 셸에서 START_UTC와 END_UTC를 실제 실패 구간의 YYYY-MM-DD HH:MM:SS UTC 값으로 설정합니다. 기본값은 없으며 미설정·빈 값이면 조회하지 않습니다. UTC 구간 지정을 참고합니다. ghe-config.log는 최근 설정 적용 조사용이며 SCIM 기본 조회 대상이 아닙니다.

(
  : "${START_UTC:?Set START_UTC to the actual start: YYYY-MM-DD HH:MM:SS UTC}"
  : "${END_UTC:?Set END_UTC to the actual end: YYYY-MM-DD HH:MM:SS UTC}"
  tail -n 200 /var/log/github/exceptions.log
  tail -n 200 /data/user/common/ghe-config.log
  journalctl -t github-unicorn --utc --since "$START_UTC" --until "$END_UTC" -n 200 --no-pager
)

(
  umask 077
  set -C
  ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -p 2days -o' > ./APPROVED-LOCAL-FOLDER/CASE-UTC-UNIQUE-support.tgz
)

폴더·파일 이름은 승인된 실제 값으로 치환합니다. 호스트 키 검증을 끄지 않습니다. UI 대안은 Management Console → Support → Download support bundle입니다. geo-replication/cluster는 공식 절차의 ghe-cluster-support-bundle -p 2days -o 적용 여부를 확인합니다. -u·-t 자동 업로드 옵션은 사용하지 않으며 생성 후에도 반출 승인은 별개입니다.

12.2.1 기본 로그는 어디서 보는가

1. 대상과 권한 고정

   승인된 관리자 PC에서 위 ssh -p 122 admin@HOSTNAME으로 연결합니다. HOSTNAME은 실제 승인된 GHES 호스트로 치환합니다. 예시 https://github.example.com/api/v3/scim/v2는 승인된 실제 호스트로 바꿉니다. GHES용 Entra 앱·테넌트·실제 Tenant URL을 확인하고 Cloud용 앱과 구분합니다.

2. 최근 일부만 조회

   아래는 기본 애플리케이션 로그의 최근 100행입니다. 파일 전체나 최근 100분이 아닙니다. 행별 시각·시간대·노드와 실제 실패 구간을 대조합니다. 읽기 권한 오류는 기록 부재가 아니며 임의 권한 변경으로 우회하지 않습니다.

tail -n 100 /var/log/github/production.log

tail -n 100 -F /var/log/github/production.log

12.2.2 최근 구간과 정확한 UTC 구간

journalctl -t github-unicorn --utc --since '20 minutes ago' --no-pager -n 200 -o short-iso

(
  : "${START_UTC:?Set START_UTC to the actual start: YYYY-MM-DD HH:MM:SS UTC}"
  : "${END_UTC:?Set END_UTC to the actual end: YYYY-MM-DD HH:MM:SS UTC}"
  journalctl -t github-unicorn --utc --since "$START_UTC" --until "$END_UTC" --no-pager -n 200 -o short-iso
)

12.2.3 SCIM: HTTP 수신부터 애플리케이션 오류까지

Entra의 사용자별 provisioning event에서 실패 단계·상세 응답을 먼저 확인합니다. 할당 직후 사용자가 없으면 자동 주기의 진행·대기와 Stopped 상태를 구분합니다. 승인된 단일 시험 사용자의 이벤트를 대조하며 전체 재프로비저닝으로 진단을 시작하지 않습니다.

tail -n 1000 /var/log/nginx/github.log | grep -F '/api/v3/scim/v2' | tail -n 50

journal은 먼저 위의 필터 없는 제한 조회로 시각과 형식을 확인합니다. 필요할 때만 아래 추가 필터를 사용합니다. tag·메시지 형식에 경로가 없거나 최대 행 수 밖이면 검색되지 않습니다.

journalctl -t github-unicorn --utc --since '20 minutes ago' --no-pager -n 200 -o short-iso | grep -F '/api/v3/scim/v2'

메서드·경로·응답을 함께 읽기

LB/WAF의 상태와 GHES 원본(origin) 상태를 구분합니다. HTTP 200인 HTML 로그인 응답은 SCIM 성공이 아닙니다. 메서드·경로·UTC·source/target ID·request ID를 기록하고 실제 응답에서 확인된 값만 사용합니다. Entra Change ID는 자동으로 GHES request ID가 되지 않습니다. 일치가 확인되지 않으면 각 ID를 별도 필드로 보관하고 시간·대상·작업을 함께 대조합니다.

12.2.4 신원 이벤트·예외 교차 확인

tail -n 1000 /var/log/github/audit.log | grep -E 'external_identity|user\.(create|suspend|unsuspend|rename)' | tail -n 50

tail -n 100 /var/log/github/exceptions.log
tail -n 100 /var/log/nginx/github.error.log

감사 이벤트는 HTTP 요청 로그의 대체물이 아닙니다. 실패한 생성은 사용자 생성 감사 이벤트를 남기지 않을 수 있습니다. GHEC에 무작위처럼 보이는 계정명이 있다는 사실만으로 새 신원 생성이나 GHES 계정과의 동일성을 확정하지 않습니다. 호스트·Entra 객체·externalId·대상 ID·생성 시각을 비교합니다.

12.2.5 라이선스 UI·설정 적용은 별도 분기

Management Console의 라이선스 업로드·갱신 UI/API 오류를 조사할 때만 콘솔 로그를 추가합니다. 일반 GHES License 화면 오류는 먼저 해당 요청의 production/journal/HTTP 기록을 확인합니다. SCIM 기본 조사에 콘솔·설정 로그를 무조건 섞지 않습니다.

tail -n 100 /var/log/enterprise-manage/unicorn.log

tail -n 100 /data/user/common/ghe-config.log

새 라이선스 키 업로드나 재시작 뒤 정상화가 관측되더라도 이는 변경 후 관측입니다. 키 한도·실패 상세·변경 전후 요청을 비교하지 않고 근본 원인이 입증됐다고 쓰지 않습니다. 라이선스와 Connect의 사용량 동기화는 분리하며 Sync/Enable만으로 설치 키의 좌석 한도가 늘어날 것으로 기대하지 않습니다.

12.2.6 내장 통합 로그 관찰 — 선택 사항

ghe-logs-tail

이 통합 관찰과 tail -F는 총 출력 행 수가 제한되지 않습니다. 기본 선택은 위의 제한된 조회이며 Ctrl+C는 조회기만 종료하고 GHES 서비스는 중지하지 않습니다. 파일 전체 복사나 무기한 수집으로 대체하지 않습니다.

12.2.7 무출력·연결 오류·자료 취급 주의 조회표

연결·프로비저닝·라이선스 완료는 실제 환경에서 각각 검증합니다. 증상별 출발점은 부록의 로그·주의사항 빠른 조회, 신원 흐름은 SCIM을 참조합니다.

12.3 감사·알림·수명주기·라이선스 운영

gh api --hostname HOSTNAME --method GET /enterprise/settings/license

UI는 Enterprise settings → Settings → License입니다. ghe-license info와 ghe-license check만 일상 조회에 사용하며 --used는 포함하지 않습니다. Code Security·Secret Protection 또는 기존 Advanced Security 계약은 활성 저장소의 최근 90일 내 push된 커밋의 고유 active committer를 기준으로 검토합니다. 저장소별 수를 단순 합산하거나 사용자별 좌석 체크박스로 수동 배정하는 모델로 설명하지 않습니다. GHEC 청구·Copilot 구독/정책은 별도이며 확인하지 않은 Cloud 화면을 GHES 경로로 만들지 않습니다.

공식 근거: 3.21 Monitor · 임계값 · 스토리지 구조 · 로그·회전 · CLI · 지원 자료 · 감사 보존 · 조직 감사 180일 · 감사 스트리밍 · Syslog · SMTP · 라이선스 API · Security 청구

Phase 13백업·복구·재해 복구 훈련

상세 참조 장 · STEP 12의 실행 순서·화면으로 돌아가기 →

담당: GHES·스토리지·네트워크 담당선행: 백업 저장소·격리 STAGING·변경 승인산출물: 성공 snapshot·복구 증거·관측 RPO/RTO

13.2 백업 입력표 → 초기 설정 → 첫 성공

1. 저장소 승인

   Phase 0의 입력표에 백업 방식·소스 버전·전용 디스크 ID·용량·마운트·복구 대상·UTC 일정·보존 개수·RPO/RTO·담당자를 기록합니다. Service는 primary 데이터 디스크 사용량의 최소 5배, 대소문자 구분 및 hard/symbolic link 지원을 확인합니다. Utilities 문서의 primary 할당량 5배 권고와 혼동하지 않습니다.

2. Service 저장소 준비 — 파괴 작업 분리

   하이퍼바이저에서 승인된 전용 디스크를 연결하고 아래 조회로 식별합니다. 신규 빈 디스크에 한해서 공식 ghe-storage-init-backup 초기화 절차를 2인 확인 후 수행합니다. 초기화는 해당 장치를 포맷·삭제하므로 복사 가능한 포맷 명령은 제공하지 않습니다. 기존 초기화 디스크는 재포맷하지 말고 공식 재사용 절차로 mount service를 활성화합니다. root·data 디스크와 불명확하면 중단합니다.

3. Service 화면 입력

   /data/backup 마운트 후 Management Console의 Backup 영역 / Backup Service가 나타납니다. Settings → Backup에서 승인 일정(Daily 또는 custom cron)과 Number of snapshots를 설정하고 Save settings합니다. 기본 10개는 10일이 아닙니다. Include Pages·Skip search indices·복구 시 감사/관리 암호 옵션을 승인 범위와 대조합니다. Save settings는 서비스 재시작 가능성이 있는 변경이므로 적용 완료까지 확인합니다.

4. 최초 백업

   변경 창의 I/O·비용·잔여 용량 승인 후 Backups → Backup Now를 선택합니다. 첫 실행은 full, 이후 증분 판단은 서비스가 수행합니다. CLI 대안은 아래와 같으며 UI와 동시에 실행하지 않습니다. Backup Service → Backup History에서 시작·종료·성공·snapshot ID·지속 시간을 기록합니다.

5. 기존 Utilities 경로

   별도 호스트에서 호환 release archive·backup.config·GHE_HOSTNAME·GHE_DATA_DIR·일정을 검토합니다. GHES 관리 키 등록과 TCP 122를 승인한 다음 아래 host check와 백업을 수행합니다. Service로 이전할 때 설정 재입력 또는 공식 migration 절차를 사용하고 새 복구 시험 전 기존 사본을 폐기하지 않습니다.

lsblk
findmnt /data/backup
df -h /data/backup

ghe-backup

./bin/ghe-host-check && ./bin/ghe-backup

13.3 백업 상태 판정과 보관 범위

tail -n 200 /var/log/github-backup/backup-verbose-YYYYMMDD.log
ls -l /data/user/common/backup_utils_in_progress

실패/중첩이면 이전 작업의 진행·스토리지 접근·여유·지연·버전을 확인하고 중복 실행을 멈춥니다. marker를 지우거나 retention을 줄여 즉시 재실행하지 않습니다. 성공 후 자동 prune이 일어나므로 보존 변경도 승인 대상입니다. 매일 마지막 성공의 나이·지속 시간·누락 일정·잔여 용량을 확인하고 복구 시험을 주기적으로 재수행합니다.

13.4 격리 STAGING 복구 훈련

1. 복구 선언·버전 선택

   사고 기준 T0, 선택 snapshot의 복구 가능 시점 T1, 복구 시작 T2를 UTC로 기록합니다. 같은 feature 또는 최대 두 feature 앞 대상까지 지원하며 최신→구버전 복원은 금지입니다. 예: 3.21 snapshot은 3.21/3.22 대상 가능, 3.22→3.21은 불가. 처음에는 같은 패치로 연습합니다.

2. 격리 먼저

   새 STAGING 대상의 DNS·방화벽·관리 접근을 분리합니다. 운영 IdP/SCIM·webhook·SMTP·Runner·Actions/Packages 쓰기를 차단하고 시험용 목적지만 허용합니다. 서비스 시작 전에 차단을 적용합니다. snapshot 및 외부 저장소 사본을 준비하며 운영 storage 자격 증명을 시험에 그대로 복제하지 않습니다.

3. Actions 호환성 게이트

   공식 Actions 복구는 원래 provider/credentials를 사전 구성하도록 안내합니다. 격리 복제 저장소의 주소·인증으로 메타데이터 호환성을 보장할 수 없으면 전체 Actions 복구 시험을 중단하고 지원팀과 격리 설계를 확인합니다. 운영 연결로 우회하거나 부분 시험을 전체 성공으로 보고하지 않습니다.

4. maintenance·복원

   대상 maintenance를 켜고 백업 읽기 접근을 확인합니다. HA 구성 대상은 replication stop만으로 부족하며 공식 teardown 절차가 필요하므로 훈련은 새 standalone으로 시작합니다. 아래 선택 snapshot만 복원합니다. -c는 설정·인증서·license 덮어쓰기 옵션이지 DB 복원 여부가 아니므로 기본 예제에서 제외합니다.

ghe-restore -s SNAPSHOT_TIMESTAMP

./bin/ghe-restore -s SNAPSHOT_TIMESTAMP STAGING_HOSTNAME

1. 설정 검토·시작

   Management Console에서 네트워크·인증·TLS·storage·관리 암호 복원 영향을 확인 후 Save settings합니다. 네트워크 격리를 유지한 채 승인된 시험 IP exception list로 제한 접근을 열어 Git·issue·LFS·Pages·API·감사·검색·시험 Actions/Packages를 검증하고 Runner를 재등록합니다. 실패 시 restore-verbose-[timestamp].log를 제한 조회하며 HA 재구성은 standalone 성공 뒤에만 진행합니다.

2. 측정·종료

   검증 완료 T3을 기록합니다. 관측 데이터 손실 구간은 T0−T1, 기술 복구 시간은 T3−T2, 사고 기준 서비스 회복 시간은 T3−T0입니다. 외부 blob의 일관된 복구 시점까지 포함해 승인 RPO/RTO와 비교합니다. 훈련 종료는 운영 트래픽 전환 승인이 아니며 결과·미복구 항목·후속 조치·사본 보존을 서명합니다.

13.5 HA 장애 전환은 별도 변경

replica는 hot standby이며 일반 사용자용 독립 읽기 전용 서버가 아닙니다. 일반 HA에서 replica 관리 콘솔은 replication mode를 표시하고 Git 요청은 primary로 전달될 수 있습니다. 노드 간 TCP 122·UDP 1194는 공식 포트 기준으로 범위 승인합니다. 연결·복제 상태를 확인하고 장애 선언 → 기존 primary fencing/maintenance → 미복제 손실 승인 → 수동 승격 → DNS/LB 전환 → 기능 검증 순서를 별도 실행계획으로 승인합니다. 여기에는 복사 가능한 운영 승격 명령을 넣지 않습니다. 되돌릴 때 양쪽 쓰기 허용 금지·재복제 계획이 필요합니다. 3.22는 cluster topology의 HA replication을 retired로 명시하며 일반 standalone HA와 다릅니다.

공식 근거: 3.21 Utilities·제거 예정 · 3.21 Service 구조 · 3.21 설정·NFS 주의 · 3.22 설정 · 이력·로그·marker · 설정 항목 · 복원 · Actions 외부 저장소 · Packages 외부 저장소 · HA 구조·트래픽 · 장애 전환 · 포트 · 3.22 GA·retired·알려진 문제

Phase 14업그레이드·패치·안전한 복구

상세 참조 장 · STEP 12의 실행 순서·화면으로 돌아가기 →

담당: 변경 관리자·GHES·서비스 담당선행: 지원 경로·용량·STAGING·복구 게이트산출물: 버전/서명·검증·변경 종료 증거

14.1 기준일·지원 버전·변경 영향

14.2 준비·다운로드·검증

1. 영향·복구 승인

   변경 창·사용자 공지·서비스 중단 허용·담당·중단 시각·복구 승인자를 확정합니다. STAGING에서 SAML/LDAP·SCIM·GitHub Apps/OAuth·webhook·Runner·Actions·Packages·Code Security/Secret Protection·GEI 등 실제 사용 기능을 시험합니다. Cloud EMU 화면을 GHES로 대체하지 않습니다.

2. 용량·백업 게이트

   공식 capacity 점검: CPU/메모리 통상 70% 미만, 디스크 비포화, 요청 큐 지속 200 미만, Aqueduct 적체 1~2시간 미만 및 data disk 최소 15% 여유를 확인합니다. 최근 백업·외부 storage·복구 시험과 feature 변경 직전 일관된 VM/디스크 snapshot 계획을 모두 준비합니다. 미충족이면 일정 연기합니다.

3. 패키지 선택

   공식 releases → 대상 버전 Download → Upgrading → 실제 플랫폼의 .pkg를 선택합니다. URL·파일 크기·공식 SHA256(제공되는 artifact)·서명 검증 결과를 기록합니다. 게시되지 않은 hash를 만들지 않습니다. 3.21→3.22에 .hpkg나 Management Console의 patch 설치 화면을 사용하지 않습니다.

ghe-version
ghe-upgrade -h

cd /home/admin && test ! -e APPROVED-UPGRADE.pkg &&
curl --fail --location --output APPROVED-UPGRADE.pkg 'OFFICIAL-PKG-URL' &&
sha256sum APPROVED-UPGRADE.pkg

ghe-upgrade --verify /home/admin/APPROVED-UPGRADE.pkg

14.3 standalone feature upgrade 실행

1. maintenance와 snapshot

   Management Console → Maintenance → Enable maintenance mode → now → Save. 진행 중 쓰기·작업 종료를 기다린 뒤 승인한 일관된 VM/디스크 snapshot을 생성·식별합니다. 전원이 켜진 VM의 임의 snapshot만으로 정합성을 가정하지 않습니다. maintenance 설정은 실제 서비스 변경입니다.

2. 설치·재시작

   아래 명령의 패키지 경로와 표시된 target·서명을 다시 확인한 뒤 대화형 설치를 승인합니다. 새 root 영역 쓰기 및 자동 재시작을 예상하고 콘솔 접근을 유지합니다. 자동 yes 옵션은 넣지 않습니다. phased pre-upgrade는 준비 쓰기 작업이며 실제 지원 확인·별도 승인 시 표준 설치 대신 공식 절차를 택합니다.

ghe-upgrade /home/admin/APPROVED-UPGRADE.pkg

ghe-version
ghe-service-list
tail -n 200 /data/user/common/ghe-config.log

1. 검증 후 개방

   migration·background jobs 상태와 custom firewall 규칙 재적용을 확인합니다. 자동 config apply를 이유 없이 재실행하지 않습니다. 제한된 시험 접근으로 로그인·clone/fetch/push·API·webhook·Actions/Packages·Security·백업 일정 및 첫 후속 백업을 확인합니다. IP exception list는 제한 접근 상태로 maintenance를 해제하는 기능이므로 별도 승인합니다.

2. 정상화

   성공 증거·담당 서명 후 IP exception list를 사용했다면 해당 목록 기능을 비활성화·저장합니다. 사용하지 않았다면 Maintenance의 Enable maintenance mode를 해제·저장합니다. 시험 허용 목록 밖의 일반 사용자 접근도 재검증합니다. CPU/I/O·큐·오류율을 이전 기준선과 비교하며 관찰 창 종료 뒤 변경을 닫습니다. 실패하면 접근을 제한한 채 복구 분기로 갑니다.

14.4 patch·HA·cluster 분기와 실패 복구

공식 근거: 전체 릴리스·GA/EOL · 3.21 release notes · 3.22 release notes · Upgrade assistant · 경로 요건 · 용량 · 개요·백업 · 3.21 package 절차 · 3.22 package·HA·phased · Hotpatch · Cluster · Snapshot · Maintenance·IP 예외 · 실패 복구 · 공식 다운로드 · 공식 화면: Maintenance · 공식 화면: Updates

부록 A. 증상 → 증거 → 조치 → 중단 기준

원인을 먼저 정하지 말고 실제 대상·실행 시각·인증 주체·HTTP/SCIM 상세부터 고정합니다. 아래 표는 가능한 원인의 분기이며 특정 환경에 발생했다고 확인한 장애 목록이 아닙니다.

로그·주의사항 빠른 조회

공식 근거: GHES SCIM · 시스템 로그 · Storage 403 · Support 자료

부록 B. 자주 섞이는 개념과 위험한 지름길

부록 C. 구축·운영 인수 체크리스트

체크는 이 문서에서의 로컬 표시이며 실제 운영 완료 증명이 아닙니다. 자동 저장되지 않습니다. 실제 결과·UTC·작업자·승인·증거 위치를 별도로 기록하고 미사용 기능은 N/A 사유를 남깁니다.

설계·라이선스

• 01. GHES 선택 이유, 데이터·외부 전송·별도 Cloud/AI 범위 합의
• 02. 설치 버전·지원 기한·목표 패치·3.22 운영 차이 확인
• 03. 배포 플랫폼·CPU/RAM·IOPS·루트/별도 데이터 디스크 산정
• 04. Trial/volume/PAYG 및 실제 파일 발급 주체 확인
• 05. RPO/RTO·유지보수 시간·담당·승인·비상 연락 경로 확정
• 06. 현재 키의 유효성·한도와 실제 소비 좌석을 분리 확인

네트워크·설치

• 07. FQDN·서브도메인 DNS·TLS 전체 체인·갱신 책임 확인
• 08. 사용자·관리자·Entra·Runner·Cloud·Blob 경로별 연결표 승인
• 09. Entra SCIM의 서비스 기원 도달성과 실제 서버 수신 증거 확보
• 10. SSH122·콘솔8443의 승인된 관리 접근과 공개키 확인
• 11. NTP·DNS·SMTP·proxy/LB의 필요한 방향과 조건 확인
• 12. 공식 가상 appliance와 빈 데이터 디스크로 설치
• 13. 실제 버전·파일시스템·기본 서비스·관리 콘솔 비상 접근 확인

신원·권한

• 14. GHES용 Entra 갤러리 앱·테넌트·service principal ID 확정
• 15. GHES builtin setup user·관리 콘솔·SSH 권한 구분
• 16. SAML Entity ID/ACS/issuer/서명 인증서·NTP 대조
• 17. SCIM PAT 소유자·classic·scope·보관 및 교체 절차 확인
• 18. GHES Tenant URL /api/v3/scim/v2 및 Test Connection 성공
• 19. 범위·직접/그룹 할당·역할·externalId/userName 매핑 확인
• 20. 대표 사용자·운영 Owner 생성·로그인·권한 인수 확인
• 21. Org·Team·private/internal·허용/거부 접근 시험
• 22. 동일 IdP 객체 기준 비활성화·복원 시험과 비상 절차

선택 기능·연결

• 23. Connect 사용 조건·실제 Cloud 대상·보고 데이터·최근 sync 확인
• 24. Azure/S3 등 선택한 외부 Actions storage 지원 조건 확인
• 25. Shared Key/OIDC 등 실제 인증 분기와 보안 승인 확인
• 26. OIDC 사용 시 federation·공개 metadata/JWKS·역할 확인
• 27. Storage 검사와 실제 읽기/쓰기 성공 결과 확인
• 28. 전용 self-hosted runner·그룹·label·저장소 허용 확인
• 29. GHES에서 허용된 action ref·런타임·artifact 버전 확인
• 30. 시험 workflow checkout·artifact upload/download·내용 비교 성공
• 31. Packages 사용 시 독립 저장소·registry주소·권한·push/pull 확인
• 32. Copilot 사용 시 별도 신원·좌석·정책·외부 통신 승인

운영·인수

• 33. 용량·오류·인증서/토큰/라이선스 만료 모니터링과 수신자 확인
• 34. 감사·시스템 로그의 저장 위치·보존·접근 통제 확인
• 35. 백업 방식과 설치 버전 호환성·최근 성공·보존 확인
• 36. Actions/Packages 등 외부 객체와 설정·비밀정보 보호 범위 확인
• 37. 격리된 복원 시험·데이터 확인·실측 RPO/RTO 기록
• 38. HA 사용 시 복제·장애 감지·수동 전환·복귀 계획 검토
• 39. 업그레이드 공식 경로·staging·검증·지원/복구 절차 확인
• 40. 사용자 회수·runner/PAT/GitHub App·운영 권한 정기 점검
• 41. 미해결 과제·N/A 사유·지원 티켓·책임·다음 확인 시점 인수

일반 운영 점검: 제한된 로그·신원·연결 검증

• 42. GHES용 Entra 앱·테넌트·실제 Tenant URL과 Cloud 앱 분리 확인
• 43. 할당 후 자동 주기 진행/대기·Stopped·사용자별 event와 제한된 시험 결과 기록
• 44. 실패 UTC 시작/끝·시간대·처리 노드·LB·로그 보존 확인 및 START_UTC·END_UTC 설정
• 45. production 최근 행·제한된 journal·SCIM HTTP 교차 확인과 필터 누락 가능성 기록
• 46. 메서드·경로·원본 HTTP 상태·source/target ID·request ID 기록 및 Entra Change ID 구분
• 47. audit 신원 이벤트·예외 대조, Cloud 계정 표시 이름 대신 객체 ID로 동일성 확인
• 48. 라이선스 사용량 동기화와 키 한도 분리, 키 업로드·재시작 뒤 관측과 원인 입증 구분
• 49. Connect 일반 오류의 NTP·DNS/TLS·outbound·proxy 가설을 각각 증거로 검증
• 50. 임시 넓은 outbound의 최소화·proxy 경유 재시험·규칙 회수 담당과 기한 인수
• 51. 짧은 실시간 로그 조회 종료·민감 원문 제한 보관·공유본 비식별화 및 미확인 사항 인수

결과 기록 양식

Check item:
Target / installed version:
Operator / approver / UTC:
Expected result:
Observed result / event or request ID:
PASS / FAIL / NOT TESTED / N/A with reason:
Evidence location (restricted):
Approved change and recovery decision:
Owner / support case / next checkpoint:

부록 D. 공식 문서·이미지 출처

2026-09-19 기본 절차에 2026-09-21 운영상 주의점의 공식 근거를 보강한 참조 목록입니다. 기존 모든 기능을 새로 감사했다는 뜻은 아닙니다. 명령·UI는 해당 버전·권한에 맞춰 현장에서 검증해야 합니다. 개념도·공식 예제 화면은 실제 환경의 구성·성공 결과를 증명하지 않습니다.

• 공식 원문 출처https://docs.github.com/en/enterprise-server@3.21/billing/how-tos/manage-server-licenses/upload-new-license
• 공식 원문 출처https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-server-provisioning-tutorial
• 공식 원문 출처https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac#new-service-principal
• 공식 원문 출처https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal
• 공식 원문 출처https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-server-tutorial
• GHES 3.21 SAML·SCIM 제품 기준https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id
• 공식 원문 출처https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand
• 공식 원문 출처https://learn.microsoft.com/en-us/entra/identity/monitoring-health/concept-provisioning-logs
• 공식 원문 출처https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise
• 공식 원문 출처https://docs.github.com/en/enterprise-server@3.21/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage
• 공식 원문 출처https://docs.github.com/en/enterprise-server@3.21/actions/how-tos/manage-runners/self-hosted-runners/add-runners
• GHES 시스템 구조https://docs.github.com/en/enterprise-server@3.21/admin/overview/system-overview
• Cloud·Server 병용https://docs.github.com/en/enterprise-server@3.21/billing/concepts/enterprise-billing/combined-enterprise-use
• EMU 공식 안내https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users
• 전체 릴리스·지원 기간https://docs.github.com/en/enterprise-server@3.22/admin/all-releases
• 3.21 릴리스 노트https://docs.github.com/en/enterprise-server@3.21/admin/release-notes
• 지원 플랫폼 색인https://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance
• VMwarehttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware
• Azurehttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure
• AWShttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws
• Hyper-Vhttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v
• OpenStack KVMhttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm
• GCPhttps://docs.github.com/en/enterprise-server@3.21/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform
• Actions 최소 자원·외부 저장소https://docs.github.com/en/enterprise-server@3.21/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server
• 관리 셸 지원 범위https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh
• 라이선스 파일https://docs.github.com/en/enterprise-server@3.21/billing/concepts/enterprise-billing/ghes-license-files
• Cloud 소비 사용자·예외https://docs.github.com/en/enterprise-cloud@latest/billing/reference/github-license-users
• 사용량 동기화 방향https://docs.github.com/en/enterprise-server@3.21/billing/how-tos/manage-server-licenses/sync-license-usage
• enterprise.github.com/downloadhttps://enterprise.github.com/download
• 공식 다운로드 분기·UIhttps://docs.github.com/en/enterprise-server@3.21/billing/how-tos/manage-server-licenses/download-your-license
• Console 인증https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console
• Console 계정 유형https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console
• ghe-license info / checkhttps://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-license
• 라이선스 GET APIhttps://docs.github.com/en/enterprise-server@3.21/rest/enterprise-admin/licensing#get-license-information
• 파일·PAYG 좌석 기준https://docs.github.com/en/billing/concepts/enterprise-billing/ghes-license-files
• 다운로드·노란 배너https://docs.github.com/en/enterprise-cloud@latest/billing/how-tos/manage-server-licenses/download-your-license
• 공식 포트·HA·Connecthttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-network-settings/network-ports
• Connect 연결 경계https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-github-connect/about-github-connect
• runner 통신https://docs.github.com/en/enterprise-server@3.21/actions/reference/runners/self-hosted-runners#communication
• GHES SCIM 도달성https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users
• hostname 변경 경고https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance
• DNS resolverhttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-network-settings/configuring-dns-nameservers
• 하위 도메인·SANhttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-subdomain-isolation
• TLS·LB 제한https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls
• NTPhttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-network-settings/configuring-time-synchronization
• Entra IP Rangeshttps://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#ip-ranges
• Entra Test Connection·주기·온디맨드https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#integrate-your-scim-endpoint-with-the-microsoft-entra-provisioning-service
• Connect의 세 호스트·Cloud IP allowlisthttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom
• 아웃바운드 프록시·Actions 제한https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-network-settings/configuring-an-outbound-web-proxy-server
• 읽기 도구·시스템 정보https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities
• 3.21 SAML 설정https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise
• 3.21 built-in 인증https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider
• Console 계정 경계https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/administering-your-instance-from-the-web-ui
• 3.21 setup 계정 Owner 승격https://docs.github.com/en/enterprise-server@3.21/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator
• Entra 초기·증분·범위·격리https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works
• Entra 로그·Change ID·Stepshttps://learn.microsoft.com/en-us/entra/identity/monitoring-health/howto-analyze-provisioning-logs
• Cloud EMU 퇴사·복귀·감사 이벤트https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim/deprovisioning-and-reinstating-users
• Cloud·Server 라이선스 소비 기준https://docs.github.com/en/billing/reference/github-license-users
• 3.21 기존 사용자 매칭https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes
• 3.21 SCIM API·paginationhttps://docs.github.com/en/enterprise-server@3.21/rest/enterprise-admin/scim
• 3.21 단일 쓰기 원천·가용 좌석https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api
• 3.21 신원·프로비저닝 오류https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise
• 3.21 퇴사·복귀https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/deprovisioning-and-reinstating-users
• GHES 좌석 기준https://docs.github.com/en/enterprise-server@3.21/billing/reference/github-license-users
• 3.17 릴리스https://docs.github.com/en/enterprise-server@3.17/admin/release-notes
• 3.14 릴리스https://docs.github.com/en/enterprise-server@3.14/admin/release-notes
• 3.21 IdP 그룹과 조직 팀https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups
• 3.21 저장소 가시성https://docs.github.com/en/enterprise-server@3.21/repositories/creating-and-managing-repositories/about-repositories
• 3.21 CODEOWNERS 강제 조건https://docs.github.com/en/enterprise-server@3.21/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
• 3.21 보호 브랜치https://docs.github.com/en/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
• 3.21 연결 메타데이터의 주간 시각https://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-github-connect/about-github-connect#data-transmitted-when-github-connect-is-enabled
• 3.21 SCIM 생성과 가용 라이선스https://docs.github.com/en/enterprise-server@3.21/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api#provisioning-users-with-the-rest-api
• 3.21 사용량 기반 결제https://docs.github.com/en/enterprise-server@3.21/billing/concepts/enterprise-billing/usage-based-licenses
• 3.21 이메일 중복 제거https://docs.github.com/en/enterprise-server@3.21/billing/reference/enterprise-license-troubleshooting
• Cloud 현재 사용량 UIhttps://docs.github.com/en/enterprise-cloud@latest/billing/how-tos/manage-plan-and-licenses/view-enterprise-usage
• Copilot 현재 제품 범위https://docs.github.com/en/copilot/get-started/plans
• Cloud agent 현재 호스팅 조건https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent
• 3.22 Azure 인증https://docs.github.com/en/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage
• Azure 403https://learn.microsoft.com/en-us/troubleshoot/azure/azure-storage/blobs/authentication/storage-troubleshoot-403-errors
• Federated credential CLIhttps://learn.microsoft.com/en-us/cli/azure/ad/app/federated-credential
• StorageBlobLogs 스키마https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/storagebloblogs
• OS별 서비스https://docs.github.com/en/enterprise-server@3.21/actions/how-tos/manage-runners/self-hosted-runners/configure-the-application
• 통신·ephemeralhttps://docs.github.com/en/enterprise-server@3.21/actions/reference/runners/self-hosted-runners
• 조직 runner APIhttps://docs.github.com/en/enterprise-server@3.21/rest/actions/self-hosted-runners#list-self-hosted-runners-for-an-organization
• Actions 공급https://docs.github.com/en/enterprise-server@3.21/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise
• Upload GHES 지원https://github.com/actions/upload-artifact#ghes-support
• Upload Node20 refhttps://github.com/actions/upload-artifact/blob/v3-node20/action.yml
• Download Node20 refhttps://github.com/actions/download-artifact/blob/v3-node20/action.yml
• 3.21 Azure Packageshttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-packages/enabling-github-packages-with-azure-blob-storage
• 3.22 Azure Packageshttps://docs.github.com/en/enterprise-server@3.22/admin/configuring-packages/enabling-github-packages-with-azure-blob-storage
• 자원·생태계https://docs.github.com/en/enterprise-server@3.21/admin/configuring-packages/getting-started-with-github-packages-for-your-enterprise
• Ecosystem toggleshttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-packages/configuring-package-ecosystem-support-for-your-enterprise
• Container registry·인증https://docs.github.com/en/enterprise-server@3.21/packages/working-with-a-github-packages-registry/working-with-the-container-registry
• 백업 서비스https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/about-the-backup-service-for-github-enterprise-server
• Backup Utilities 전환https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance
• Docker pull·레이어 캐시https://docs.docker.com/reference/cli/docker/image/pull/
• Business 전용 enterprisehttps://docs.github.com/en/copilot/concepts/enterprise/about-enterprise-accounts-for-copilot-business
• Cloud/Server 청구 구분https://docs.github.com/en/billing/concepts/enterprise-billing/combined-enterprise-use
• Cloud 정책·AI controlshttps://docs.github.com/en/copilot/concepts/enterprise/policies
• 좌석 할당https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-access/grant-access
• Cloud CLI 인증https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli
• 네트워크 allowlisthttps://docs.github.com/en/copilot/reference/copilot-allowlist-reference
• BYOKhttps://docs.github.com/en/copilot/concepts/models/bring-your-own-key
• SDK BYOKhttps://docs.github.com/en/copilot/how-tos/copilot-sdk/auth/byok
• Content exclusionhttps://docs.github.com/en/copilot/concepts/context/content-exclusion
• 문맥과 책임 있는 사용https://docs.github.com/en/copilot/responsible-use/chat
• 3.22 릴리스https://docs.github.com/en/enterprise-server@3.22/admin/release-notes
• 3.22 CLI technical previewhttps://docs.github.com/en/enterprise-server@3.22/admin/github-copilot/copilot-cli/set-up-and-use-copilot-cli
• 3.21 Monitorhttps://docs.github.com/en/enterprise-server@3.21/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards
• 임계값https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds
• 스토리지 구조https://docs.github.com/en/enterprise-server@3.21/admin/overview/system-overview#storage-architecture
• 로그·회전https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs
• 지원 자료https://docs.github.com/en/enterprise-server@3.21/support/contacting-github-support/providing-data-to-github-support
• 감사 보존https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise
• 조직 감사 180일https://docs.github.com/en/enterprise-server@3.21/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization
• 감사 스트리밍https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise
• Sysloghttps://docs.github.com/en/enterprise-server@3.21/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding
• SMTPhttps://docs.github.com/en/enterprise-server@3.21/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-email-for-notifications
• 라이선스 APIhttps://docs.github.com/en/enterprise-server@3.21/rest/enterprise-admin/licensing
• Security 청구https://docs.github.com/en/enterprise-server@3.21/billing/concepts/product-billing/github-advanced-security
• 3.21 설정·NFS 주의https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/configuring-the-backup-service
• 3.22 설정https://docs.github.com/en/enterprise-server@3.22/admin/backing-up-and-restoring-your-instance/configuring-the-backup-service
• 이력·로그·markerhttps://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/creating-and-monitoring-backups
• 설정 항목https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/backup-service-settings-reference
• 복원https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-from-a-backup
• Actions 외부 저장소https://docs.github.com/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-with-github-actions-enabled
• HA 구조·트래픽https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration
• 장애 전환https://docs.github.com/en/enterprise-server@3.21/admin/monitoring-and-managing-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance
• Upgrade assistanthttps://support.github.com/enterprise/server-upgrade
• 경로 요건https://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/preparing-to-upgrade/upgrade-requirements
• 용량https://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/preparing-to-upgrade/check-system-capacity-before-upgrading
• 개요·백업https://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process
• 3.21 package 절차https://docs.github.com/en/enterprise-server@3.21/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package
• 3.22 package·HA·phasedhttps://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package
• Hotpatchhttps://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch
• Clusterhttps://docs.github.com/en/enterprise-server@3.22/admin/monitoring-and-managing-your-instance/configuring-clustering/upgrading-a-cluster
• Snapshothttps://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot
• Maintenance·IP 예외https://docs.github.com/en/enterprise-server@3.21/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode
• 실패 복구https://docs.github.com/en/enterprise-server@3.22/admin/upgrading-your-instance/troubleshooting-upgrades/restoring-from-a-failed-upgrade
• 공식 다운로드https://enterprise.github.com/releases
• 공식 화면: Maintenancehttps://docs.github.com/assets/images/enterprise/management-console/maintenance-tab.png
• 공식 화면: Updateshttps://docs.github.com/assets/images/enterprise/management-console/updates-tab.png

GitHub Enterprise Server 범용 구축·운영 가이드 · 2026-09-21 개정 / 기본 절차 2026-09-19 · 절차 기준 3.21 / 3.22 등 목표 버전은 지원·보안 패치·백업·업그레이드 변경을 별도 확인.