GitHub Enterprise 호스트에 연결

이 페이지에서는 GitHub Enterprise 호스트를 Cloud Build에 연결하는 방법을 설명합니다.

시작하기 전에

API Cloud Build and Secret Manager 사용 설정
API 사용 설정

최신 버전의 GitHub Enterprise가 있는지 확인합니다.
커스텀 도메인을 GitHub Enterprise 호스트에 매핑하고 호스트에 대해 적합한 SSL 인증서를 준비해야 합니다.

참고: GitHub Enterprise 호스트가 Compute Engine 인스턴스에서 실행 중인 경우 외부 HTTP(S) 부하 분산기를 만들 수 있으며, 인스턴스에 Google 관리형 SSL 인증서를 사용할 수 있습니다.
GitHub Enterprise 인스턴스가 비공개 네트워크에서 호스팅되는 경우 이 페이지의 안내를 완료하기 전에 비공개 네트워크의 GitHub Enterprise에서 저장소 빌드를 참조하세요.

필수 IAM 권한

GitHub Enterprise 호스트를 연결하려면 사용자 계정에 Cloud Build 연결 관리자(roles/cloudbuild.connectionAdmin) 역할을 부여합니다.

사용자 계정에 필요한 역할을 추가하려면 Cloud Build 리소스에 대한 액세스 구성을 참조하세요. Cloud Build와 연관된 IAM 역할에 대한 자세한 내용은 IAM 역할 및 권한을 참조하세요.

gcloud 설치 단계를 사용하여 연결을 만들려면 Google Cloud 프로젝트에서 다음 명령어를 실행하여 Cloud Build 서비스 에이전트에 Secret Manager 관리자 역할(roles/secretmanager.admin)을 부여합니다.

      PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
      CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
       gcloud projects add-iam-policy-binding ${PROJECT_ID} \
         --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
         --role="roles/secretmanager.admin"

GitHub Enterprise 인스턴스가 비공개 네트워크에서 호스팅되는 경우 비공개 네트워크의 GitHub Enterprise에서 저장소 빌드를 참조하여 호스트 연결 전에 필요한 추가 IAM 역할에 대해 알아보세요.

GitHub Enterprise 호스트에 연결

콘솔

GitHub Enterprise 호스트를 Cloud Build에 연결하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기

저장소 페이지가 표시됩니다.
상단 표시줄의 프로젝트 선택자에서 Google Cloud 프로젝트를 선택합니다.
페이지 상단에서 2세대 탭을 선택합니다.
호스트 연결 만들기를 클릭하여 새 호스트를 Cloud Build에 연결합니다.
왼쪽 패널에서 GitHub Enterprise를 소스 제공업체로 선택합니다.
연결 구성 섹션에서 다음 정보를 입력합니다.
1. 리전: 연결의 리전을 선택합니다.
  
  참고: 리전을 지정해야 합니다. 연결은 전 세계적으로 존재할 수 없습니다.
2. 이름: 연결의 이름을 입력합니다.
호스트 세부정보 섹션에서 다음 정보를 입력합니다.
1. 호스트 URL: 연결의 호스트 URL을 입력합니다. 예를 들면 github.example.com입니다.
2. CA 인증서: 찾아보기를 클릭하여 자체 서명 인증서를 업로드합니다.
  참고: 인증서 크기는 10KB를 초과할 수 없으며 PEM 형식(.pem, .cer, .crt)이어야 합니다. 이 섹션을 비워 두면 기본 인증서 집합이 사용됩니다.
3. 연결 유형에서 다음 옵션 중 하나를 선택합니다.
  1. 공개 인터넷: 공개 인터넷을 통해 인스턴스에 액세스할 수 있는 경우 이 옵션을 선택합니다.
  2. 비공개 네트워크 액세스: 인스턴스가 비공개 네트워크에서 호스팅되는 경우 이 옵션을 선택합니다.
  3. 서비스 디렉터리 서비스에서 서비스의 위치를 선택합니다.
    - 프로젝트 your-project 내
    - 다른 프로젝트 내
    - 직접 입력
    1. 다른 프로젝트 내 또는 직접 입력을 선택한 경우 다음 정보를 입력합니다.
      - 프로젝트: 드롭다운 메뉴에서 Google Cloud 프로젝트 ID를 입력하거나 선택합니다.
      - 리전: 이 필드는 연결의 리전을 미리 선택합니다. 서비스에 지정된 리전은 연결과 연관된 리전과 일치해야 합니다.
    2. 네임스페이스: 서비스의 네임스페이스를 선택합니다.
    3. 서비스: 네임스페이스에서 서비스 이름을 선택합니다.
연결을 클릭합니다.

연결 버튼을 클릭하면 GitHub Enterprise 호스트에서 GitHub 앱을 만들고 사용자 계정 또는 조직에 해당 앱을 설치하라는 메시지가 표시됩니다. GitHub Enterprise 호스트의 인증 토큰이 생성되어 이 프로젝트에 Secret Manager 보안 비밀로 저장됩니다. 언제든지 호스트에서 GitHub 앱을 제거하거나 삭제하여 액세스 권한을 취소할 수 있습니다.

Cloud Build는 생성된 GitHub 앱의 인증 데이터를 프로젝트의 Secret Manager에 보안 비밀로 저장합니다. 이 데이터에는 비공개 키와 웹훅 보안 비밀이 포함됩니다. 비공개 키는 엔터프라이즈 서버의 API에 액세스하기 위한 인증 방법으로 사용됩니다. 웹훅 보안 비밀은 서버에서 Cloud Build로 전송된 이벤트를 검증하는 데 사용됩니다. Cloud Build 서비스 에이전트 계정(service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com)은 보안 비밀에 액세스하는 데 사용됩니다. 보안 비밀을 보려면 보안 비밀 나열 및 보안 비밀 세부정보 보기를 참조하세요.

Cloud Build GitHub 앱을 승인하면 Cloud Build 저장소 페이지로 리디렉션됩니다.

이제 GitHub Enterprise 연결이 성공적으로 생성되었습니다.

gcloud

gcloud 명령어를 사용하여 GitHub Enterprise 호스트를 Cloud Build에 연결하려면 다음 단계를 완료하세요.

다음 명령어를 입력하여 GitHub Enterprise 연결을 만듭니다.
```
gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 연결의 이름입니다.
- HOST_URI는 GitHub Enterprise 인스턴스의 URI입니다. 예를 들면 https://mmy-ghe-server.net입니다.
- REGION은 연결의 리전입니다.
GitHub Enterprise 인스턴스가 비공개 네트워크에 있으면 서비스 디렉터리 리소스를 지정합니다. CA 인증서를 지정할 수도 있습니다.
```
--service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
--ssl-ca-file=SSL_CA_FILEPATH
```
각 항목의 의미는 다음과 같습니다.
- PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
- REGION은 연결의 리전입니다.
- NAMESPACE는 서비스의 네임스페이스입니다.
- SERVICE_NAME은 네임스페이스의 서비스 이름입니다.
- SSL_CA_FILEPATH는 CA 인증서의 파일 경로입니다.
gcloud builds connections... 명령어를 실행하면 Cloud Build GitHub 앱을 설치할 수 있는 링크가 전송됩니다.
이전 단계에서 반환된 링크를 클릭하여 엔터프라이즈 서버에 Cloud Build GitHub 앱을 만들고 설치합니다.
다음 명령어를 입력하여 연결을 확인합니다.
```
gcloud builds connections describe CONNECTION_NAME --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 연결의 이름입니다.
- REGION은 연결의 리전입니다.
installationState 필드가 COMPLETE로 설정되었으면 연결이 성공적으로 설치된 것입니다. 그렇지 않으면 installationState 필드에 필요한 추가 단계의 링크가 제공됩니다.

이제 GitHub Enterprise 연결이 성공적으로 생성되었습니다.

프로그래매틱 방식으로 GitHub Enterprise 호스트에 연결

GitHub Enterprise 호스트를 Cloud Build에 프로그래매틱 방식으로 연결하려면 다음 단계를 완료하여 GitHub 앱을 설치해야 합니다.

새 GitHub 앱을 등록합니다. 예를 들어 https://my-ghe-server.net/settings/apps/new에 새 GitHub 앱을 등록할 수 있습니다.
페이지의 필드를 작성합니다.
1. GitHub 앱 이름: 앱의 이름을 입력합니다.
2. 홈페이지 URL: GitHub Enterprise 서버의 URL을 입력합니다.
3. 사용자 승인 토큰 만료 체크박스를 선택 해제합니다.
4. 웹훅 섹션에서 다음 단계를 완료합니다.
  - 활성: 웹북을 활성화하려면 체크박스를 선택합니다.
  - 웹훅 URL: 웹훅 URL을 입력합니다. 예를 들면 https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook입니다. 웹훅 URL의 리전은 연결의 리전과 일치해야 합니다.
  - 웹훅 보안 비밀: 무작위로 생성된 문자열을 입력하고 기록해 둡니다.
5. 권한 섹션에서 다음 권한을 지정합니다.
  - 저장소 권한:
    - 확인: 읽기 및 쓰기
    - 콘텐츠: 읽기 및 쓰기
    - 문제: 읽기 전용
    - 메타데이터 읽기 전용
    - 커밋 상태: 읽기 전용
    - pull 요청: 읽기 전용
6. 이벤트 구독 섹션에서 다음 체크박스를 선택합니다.
  - 실행 검사
  - 제품군 검사
  - 커밋 설명
  - 문제 설명
  - pull 요청
  - pull 요청 검토 설명
  - 푸시
  - 저장소
7. 모든 사용자 또는 조직에서 GitHub 앱을 설치할 수 있도록 모든 계정 체크박스를 선택합니다.
GitHub 앱 만들기를 클릭하여 GitHub 앱을 만듭니다.

GitHub 앱 만들기를 클릭하면 앱 페이지로 리디렉션됩니다. 앱 ID와 앱 슬러그를 기록해 둡니다. 앱 슬러그는 페이지 URL의 마지막 세그먼트에서 확인할 수 있습니다. 예를 들면 https://my-ghe-server.net/settings/apps/{app-slug}입니다.
비공개 키 섹션에서 비공개 키 생성을 클릭합니다.

다운로드한 파일을 안전한 곳에 저장합니다.
왼쪽 창에서 앱 설치를 선택합니다.

앱을 설치하려는 사용자 또는 조직을 선택합니다. 앱이 설치되면 설치 ID를 기록합니다. 설치 ID는 페이지 URL의 마지막 세그먼트에서 확인할 수 있습니다. 예를 들면 https://my-ghe-server.net/settings/installations/{installation-id}입니다.

GitHub 앱을 설치한 후 다음 단계에 따라 Terraform 또는 gcloud를 사용하여 GitHub Enterprise 호스트를 프로그래매틱 방식으로 연결합니다.

Terraform

GitHub 앱을 설치했으면 Google Terraform 제공업체를 사용하여 GitHub Enterprise 호스트를 Cloud Build에 연결할 수 있습니다.

다음 예시의 코드 스니펫은 다음을 수행합니다.

Terraform Google 공급업체 구성
GitHub 앱의 비공개 키와 웹훅 보안 비밀을 저장하기 위해 보안 비밀 만들기
보안 비밀에 액세스하기 위해 Cloud Build 서비스 에이전트에 필요한 권한 부여

GitHub Enterprise 연결 만들기

// Configure the terraform google provider
terraform {
  required_providers {
    google = {}
  }
}

// create Secrets and grant permissions to the Service Agent
resource "google_secret_manager_secret" "private-key-secret" {
    project = "PROJECT_ID"
    secret_id = "PRIVATE_KEY_SECRET"

    replication {
        automatic = true
    }
}

resource "google_secret_manager_secret_version" "private-key-secret-version" {
    secret = google_secret_manager_secret.private-key-secret.id
    secret_data = file("private-key.pem")
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET"

    replication {
        automatic = true
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

data "google_iam_policy" "serviceagent-secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy-pk" {
  project = google_secret_manager_secret.private-key-secret.project
  secret_id = google_secret_manager_secret.private-key-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

// create the connection and add the repository resource ---
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    github_enterprise_config {
        host_uri = "URI"
        private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
        app_id = "APP_ID"
        app_slug = "APP_SLUG"
        app_installation_id = INSTALLATION_ID
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pk,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

각 항목의 의미는 다음과 같습니다.

PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
PRIVATE_KEY_SECRET는 GitHub 앱 비공개 키를 포함하는 보안 비밀입니다.
WEBHOOK_SECRET은 GitHub 앱의 웹훅 보안 비밀 값을 포함하는 보안 비밀 이름입니다.
WEBHOOK_SECRET_VALUE는 GitHub 앱 웹훅 보안 비밀의 값입니다.
REGION은 연결의 리전입니다.
CONNECTION_NAME은 GitHub 연결의 이름입니다.
URI는 연결의 URI입니다. 예를 들면 https://my-github-enterprise-server.net입니다.
APP_ID는 GitHub 앱 ID입니다.
APP_SLUG는 앱 슬러그입니다. 예를 들면 https://github.com/settings/apps/{app-slug}입니다.
INSTALLATION_ID는 GitHub 앱의 설치 ID입니다. 설치 ID는 Cloud Build GitHub 앱 URL https://github.com/settings/installations/{installation-id}에서 찾을 수 있습니다.

이제 GitHub Enterprise 연결이 성공적으로 생성되었습니다.

gcloud

GitHub 앱을 설치한 후 다음 단계에 따라 gcloud를 사용하여 GitHub Enterprise 호스트를 프로그래매틱 방식으로 연결합니다.

Secret Manager에 보안 비밀을 저장합니다.
```
echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
# creating secret from the downloaded private key:
gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE
```
각 항목의 의미는 다음과 같습니다.
- WEBHOOK_SECRET는 웹훅 보안 비밀용으로 만든 문자열입니다.
- PRIVATE_KEY_FILE은 생성한 비공개 키의 파일 경로입니다.

보안 비밀에 액세스하기 위해 Cloud Build 서비스 에이전트에 대한 액세스 권한을 부여합니다.

PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"
gcloud secrets add-iam-policy-binding mygheapp-private-key \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"

각 항목의 의미는 다음과 같습니다.

PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
CLOUD_BUILD_SERVICE_AGENT는 제품별, 프로젝트별 계정입니다.

GitHub Enterprise 연결을 만듭니다.
```
gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI \
  --app-id=APP_ID \
  --app-slug=APP_SLUG \
  --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
  --app-installation-id=INSTALLATION_ID \
  --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 연결의 이름입니다.
- HOST_URI는 GitHub Enterprise 인스턴스의 URI입니다. 예를 들면 https://mmy-ghe-server.net입니다.
- APP_ID는 GitHub 앱 ID입니다.
- APP_SLUG는 앱 슬러그입니다. 예를 들면 https://my-ghe-server.net/settings/apps/app-slug입니다.
- PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
- INSTALLATION_ID는 GitHub 앱의 설치 ID입니다. 예를 들면 https://my-ghe-server.net/settings/installations/installation-id입니다.
- REGION은 연결의 리전입니다.
GitHub Enterprise 인스턴스가 비공개 네트워크에 있으면 서비스 디렉터리 리소스를 지정합니다. CA 인증서를 지정할 수도 있습니다.
```
  --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
  --ssl-ca-file=SSL_CA_FILEPATH
```
각 항목의 의미는 다음과 같습니다.
- PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
- REGION은 연결의 리전입니다.
- NAMESPACE는 서비스의 네임스페이스입니다.
- SERVICE_NAME은 네임스페이스의 서비스 이름입니다.
- SSL_CA_FILEPATH는 CA 인증서의 파일 경로입니다.

이제 GitHub Enterprise 연결이 성공적으로 생성되었습니다.

다음 단계

저장소를 GitHub Enterprise에 연결하는 방법 알아보기
Compute Engine에서 블루/그린 배포를 수행하는 방법 알아보기