Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

GitHub 저장소에 연결

이 페이지에서는 GitHub 저장소를 Cloud Build에 연결하는 방법을 설명합니다. Cloud Build 저장소에 대해 자세히 알아보려면 Cloud Build 저장소를 참고하세요.

시작하기 전에

Cloud Build 및 Secret Manager API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정

소스 코드를 GitHub 저장소에 준비합니다.
GitHub 소스 저장소에 Dockerfile 또는 Cloud Build 구성 파일이 있습니다.
저장소를 처음으로 Cloud Build에 연결하는 경우 저장소에 관리자 수준 권한이 있는지 확인합니다. GitHub 저장소 권한에 대한 자세한 내용은 조직의 저장소 권한 수준을 참고하세요.
이 페이지에서 gcloud 명령어를 사용하려면 Google Cloud CLI를 설치합니다.

참고: 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.

GitHub 호스트에 연결

콘솔

GitHub 저장소를 Cloud Build에 연결하려면 다음 안내를 따르세요.

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

저장소 페이지 열기

저장소 페이지가 표시됩니다.
상단 표시줄의 프로젝트 선택기에서 Google Cloud 프로젝트를 선택합니다.
페이지 상단에서 2세대 탭을 선택합니다.
호스트 연결 만들기를 클릭하여 새 호스트를 Cloud Build에 연결합니다.
왼쪽 패널에서 GitHub를 소스 제공업체로 선택합니다.
연결 구성 섹션에서 다음 정보를 입력합니다.
- 리전: 연결의 리전을 선택합니다.
  
  참고: 리전을 지정해야 합니다. 연결은 전 세계적으로 존재할 수 없습니다.
- 이름: 연결의 이름을 입력합니다.
선택사항: GitHub 저장소의 액세스 토큰을 암호화하는 데 사용되는 암호화 키를 관리하려면 암호화 섹션으로 이동하여 Cloud Key Management Service 키를 선택합니다. 자세한 내용은 Secret Manager용 고객 관리 암호화 키 사용 설정을 참고하세요.
연결을 클릭합니다.

연결 버튼을 클릭하면 GitHub 계정에 액세스할 수 있도록 Cloud Build GitHub 앱을 승인하라는 메시지가 표시됩니다. 언제든지 호스트에서 앱을 제거하거나 삭제하여 앱에 대한 액세스를 취소할 수 있습니다.

Cloud Build가 GitHub 사용자 계정의 승인을 요청하고 그로 인한 승인 토큰을 프로젝트의 Secret Manager에 보안 비밀로 저장합니다. 승인 토큰은 Cloud Build GitHub 앱 설치 및 링크된 저장소에 대한 사용자 계정의 액세스를 검증하는 데 사용됩니다. Cloud Build 서비스 에이전트 계정(service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com)은 보안 비밀에 액세스하는 데 사용됩니다. 보안 비밀을 보려면 보안 비밀 나열 및 보안 비밀 세부정보 보기를 참고하세요.

참고: 이 인증을 사용하면 동일한 프로젝트에서 추가 연결을 만들 수 있습니다. 연결을 안전하게 유지하려면 개인 GitHub 계정 대신 로봇 계정이나 팀에서 공유한 계정을 사용하는 것이 좋습니다.

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

gcloud

gcloud를 사용하여 GitHub 호스트를 연결하려면 다음 단계를 완료하세요.

다음 명령어를 입력하여 GitHub 저장소에 대한 연결을 시작합니다.
```
 gcloud builds connections create github CONNECTION_NAME --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 Cloud Build에 표시될 연결의 이름입니다.
- REGION: 트리거의 리전입니다.
  
  참고: 리전을 지정해야 합니다. 연결은 전 세계적으로 존재할 수 없습니다.
gcloud builds connections 명령어를 실행하면 Cloud Build GitHub 앱을 승인하는 링크가 표시됩니다.
github.com 계정에 로그인합니다.

참고: 이 인증을 사용하면 동일한 프로젝트에서 추가 연결을 만들 수 있습니다. 연결을 안전하게 유지하려면 개인 GitHub 계정 대신 로봇 계정이나 팀에서 공유한 계정을 사용하는 것이 좋습니다.
링크를 클릭하여 Cloud Build GitHub 앱을 승인합니다.

앱을 승인하면 Cloud Build가 인증 토큰을 Google Cloud프로젝트의 Secret Manager에 보안 비밀로 저장합니다. Secret Manager 페이지에서 보안 비밀을 볼 수 있습니다.
계정이나 소유한 조직에 Cloud Build GitHub 앱을 설치합니다.

GitHub 계정을 사용하여 설치를 허용하고 메시지가 표시되면 저장소 권한을 선택합니다.
다음 명령어를 실행하여 GitHub 연결 설치를 확인합니다.
```
 gcloud builds connections describe CONNECTION_NAME --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 Cloud Build의 GitHub 호스트 연결 이름입니다.
- REGION: 트리거의 리전입니다.
installationState 필드가 COMPLETE로 설정되었으면 연결이 성공적으로 설치된 것입니다. 그렇지 않으면 installationState 필드에 필요한 추가 단계의 링크가 제공됩니다.

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

프로그래매틱 연결을 안전하게 설정하려면 Google Cloud의 보안 권장사항을 따르세요.

워크로드 아이덴티티 제휴 (WIF): CI/CD 파이프라인 (예: GitHub Actions 또는 GitLab CI)을 통해 배포 스크립트 또는 Terraform 구성을 실행하는 경우 워크로드 아이덴티티 제휴를 구성하고 IAM 역할을 사용하여 단기 사용자 인증 정보를 활용하여 파이프라인을 Google Cloud에 인증합니다. 이렇게 하면 수명이 긴 서비스 계정 키를 관리하고 노출할 필요가 없습니다.
최소 권한의 원칙: 인증 토큰에 필요한 최소한의 범위와 권한만 선택합니다.
세분화된 개인 액세스 토큰: 기존 개인 액세스 토큰 대신 만료일이 짧은 세분화된 개인 액세스 토큰 (PAT)을 사용하는 것이 좋습니다.
로봇 계정 사용: 직원이 역할을 변경하거나 조직을 떠날 때 파이프라인이 중단될 위험을 줄이려면 직원 개인 계정 대신 전용 GitHub 로봇 계정 또는 서비스 계정을 사용하세요.

Terraform

다음 단계를 완료하면 Google Terraform 제공업체를 사용하여 GitHub 호스트를 Cloud Build에 연결할 수 있습니다.

GitHub 계정 또는 소유한 조직에 Cloud Build GitHub 앱을 설치합니다.
GitHub에서 개인 액세스 토큰을 만듭니다. 전용 GitHub 로봇 계정을 사용하여 이 토큰을 생성하는 것이 좋습니다.
- 세분화된 개인 액세스 토큰(PAT)을 만드는 것이 좋습니다.
  - 짧은 만료일을 설정합니다. 만료일이 없는 토큰은 권장되지 않습니다.
  - 설정에 필요한 최소 권한을 선택합니다.
- 레거시/기본 개인 액세스 토큰을 대체로 사용해야 하는 경우 (광범위한 저장소 범위를 부여하므로 보안이 떨어짐) GitHub에서 메시지가 표시되면 다음 OAuth 범위를 선택하세요.
- repo를 사용하여 공개 및 비공개 저장소에 대한 전체 액세스 권한을 부여합니다.
- read:user를 사용하여 사용자의 프로필 데이터를 읽을 수 있는 액세스 권한을 부여합니다.
- read:org: 조직 멤버십 및 프로젝트에 대한 읽기 전용 액세스 (앱이 조직에 설치된 경우)
토큰을 생성한 후 안전한 위치에 저장합니다. 이 토큰은 후속 단계에서 사용됩니다.

참고: 이전에 만든 연결의 Secret Manager에 인증 토큰이 저장된 경우 새 연결에 동일한 보안 비밀을 사용할 수 있습니다.

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

Terraform Google 공급업체 구성 배포 파이프라인에서 구성을 실행하는 경우 단기 사용자 인증 정보와 함께 워크로드 아이덴티티 제휴를 사용하도록 프로바이더를 구성합니다.
GitHub 개인 액세스 토큰 (PAT)을 표현하는 보안 비밀을 만들고 보안 비밀에 액세스할 수 있는 권한을 Cloud Build 서비스 에이전트에 부여합니다.

GitHub 연결을 만듭니다.

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

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

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" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

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

PROJECT_NUMBER는 Google Cloud 프로젝트 번호입니다.
SECRET_ID: Secret Manager에 있는 토큰 또는 보안 비밀의 ID입니다.
GITHUB_PAT: GitHub에 있는 개인 액세스 토큰의 액세스 토큰입니다.
PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
REGION: 연결의 리전입니다.
CONNECTION_NAME은 Cloud Build에 표시될 연결의 이름입니다.
INSTALLATION_ID: Cloud Build GitHub 앱의 설치 ID입니다. 설치 ID는 Cloud Build GitHub 앱의 URL에서 찾을 수 있습니다. https://github.com/settings/installations/1234567이라는 URL에서 설치 ID는 숫자 값 1234567입니다.

gcloud

이전 연결에서 가져온 기존 토큰 및 설치 ID를 사용하여 GitHub 호스트를 연결하려면 다음 단계를 완료하세요.

GitHub 계정 또는 소유한 조직에 Cloud Build GitHub 앱을 설치합니다.
GitHub에서 개인 액세스 토큰을 만듭니다. 전용 GitHub 로봇 계정을 사용하여 이 토큰을 생성하는 것이 좋습니다.
- 세분화된 개인 액세스 토큰(PAT)을 만드는 것이 좋습니다.
  - 짧은 만료일을 설정합니다. 만료일이 없는 토큰은 권장되지 않습니다.
  - 설정에 필요한 최소 권한을 선택합니다.
- 레거시/기본 개인 액세스 토큰을 대체로 사용해야 하는 경우 (광범위한 저장소 범위를 부여하므로 보안이 떨어짐) GitHub에서 메시지가 표시되면 다음 OAuth 범위를 선택하세요.
- repo를 사용하여 공개 및 비공개 저장소에 대한 전체 액세스 권한을 부여합니다.
- read:user를 사용하여 사용자의 프로필 데이터를 읽을 수 있는 액세스 권한을 부여합니다.
- read:org: 조직 멤버십 및 프로젝트에 대한 읽기 전용 액세스 (앱이 조직에 설치된 경우)
토큰을 생성한 후 안전한 위치에 저장합니다. 이 토큰은 후속 단계에서 사용됩니다.

참고: 이전에 만든 연결의 Secret Manager에 인증 토큰이 저장된 경우 새 연결에 동일한 보안 비밀을 사용할 수 있습니다.
다음 명령어를 실행하여 Google Cloud 프로젝트의 Secret Manager에 토큰을 저장합니다.
```
    echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-
```
각 항목의 의미는 다음과 같습니다.
- TOKEN: 개인 액세스 토큰입니다.
- SECRET_NAME: Secret Manager에서 보안 비밀에 지정할 이름입니다.

보안 비밀에 Cloud Build 서비스 에이전트에 대한 액세스 권한을 부여합니다. 여기서 SECRET_NAME은 Secret Manager에 저장된 보안 비밀의 이름입니다.

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

GitHub 연결을 만듭니다.
```
  gcloud builds connections create github CONNECTION_NAME \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
    --app-installation-id=INSTALLATION_ID --region=REGION
```
각 항목의 의미는 다음과 같습니다.
- CONNECTION_NAME은 Cloud Build의 GitHub 호스트 연결 이름입니다.
- PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
- SECRET_NAME은 Secret Manager에 저장된 보안 비밀의 이름입니다.
- INSTALLATION_ID: GitHub 앱의 설치 ID입니다. 설치 ID는 Cloud Build GitHub 앱의 URL에서 찾을 수 있습니다. https://github.com/settings/installations/1234567이라는 URL에서 설치 ID는 숫자 값 1234567입니다.
- REGION: 연결의 리전입니다.

GitHub 저장소 연결

콘솔

GitHub 저장소를 호스트 연결에 연결하려면 다음 단계를 완료하세요.

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

저장소 페이지 열기

저장소 페이지가 표시됩니다.
페이지 상단에서 2세대 탭을 선택합니다.
저장소 링크를 클릭하여 연결의 저장소에 링크를 겁니다.

저장소 연결 패널이 표시됩니다.
저장소 연결 패널에서 다음 정보를 입력합니다.
1. 연결: 드롭다운 메뉴에서 연결을 선택합니다.
2. 저장소: 연결에 링크를 걸 저장소를 선택합니다.
3. 저장소 이름: 저장소 이름을 입력합니다.
  1. 생성됨: Cloud Build에서 선택한 저장소의 저장소 이름을 자동으로 생성하게 하려면 이 옵션을 선택합니다.
  2. 수동: 선택한 저장소의 이름을 수동으로 지정하려면 이 옵션을 선택합니다.
    
    수동을 선택하면 저장소 이름 섹션에서 선택한 저장소의 이름을 수정할 수 있습니다.
링크를 클릭하여 연결에 저장소의 링크를 겁니다.

gcloud

GitHub 저장소를 연결에 추가하려면 다음 명령어를 입력합니다.

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

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

REPO_NAME: 저장소의 이름입니다.
REPO_URI: GitHub 저장소 링크입니다. 예를 들면 https://github.com/cloud-build/test-repo.git입니다.
CONNECTION_NAME은 GitHub 호스트에 연결에서 Cloud Build에 생성된 GitHub Enterprise 호스트 연결에 지정된 이름입니다.
REGION: 연결의 리전입니다.

Terraform

GitHub 저장소를 연결에 추가하려면 다음 코드 스니펫을 Terraform 구성에 추가합니다.

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

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

PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
REPO_NAME은 GitHub 저장소 이름입니다.
REGION: 연결의 리전입니다.
URI: 저장소의 호스트 URI입니다. 예를 들면 https://github.com/myuser/myrepo.git입니다.

다음 단계

GitHub에서 저장소를 빌드하는 방법을 알아봅니다.
Compute Engine에서 블루-그린 배포를 수행하는 방법을 알아봅니다.
빌드의 종속 항목으로 추가 저장소를 지정하는 방법을 알아봅니다.

GitHub 저장소에 연결 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

GitHub 호스트에 연결

콘솔

gcloud

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

Terraform

gcloud

GitHub 저장소 연결

콘솔

gcloud

Terraform

다음 단계

GitHub 저장소에 연결