GitLab Enterprise Edition 호스트에 연결

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

시작하기 전에

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

GitLab Enterprise Edition 서버 인스턴스를 설치하지 않은 경우 GitLab Enterprise Edition 설치 가이드를 참조하세요.

설정

GitLab Enterprise Edition 호스트 연결을 생성하려면 먼저 GitLab Enterprise Edition에서 수신되는 이벤트를 인증하고 수락할 수 있는 API 키를 가져와야 합니다. 또한 웹훅을 만들고 저장소 데이터를 검색하려면 GitLab Enterprise Edition에서 개인 액세스 토큰을 만들어야 합니다.

이 섹션에서는 GitLab Enterprise Edition 트리거를 만들기 전에 완료해야 하는 단계를 설명합니다.

API 키 얻기

호스트 저장소를 연결하고 수신 웹훅 이벤트를 인증하려면 API 키가 필요합니다.

API 키를 가져오려면 다음 안내를 따르세요.

Google Cloud 콘솔의 사용자 인증 정보 페이지를 엽니다.

사용자 인증 정보 페이지 열기
사용자 인증 정보 만들기를 클릭합니다.
API 키를 클릭합니다.

API 키가 생성된 대화상자가 표시됩니다. API 키를 기록해 둡니다.
제품 애플리케이션에 대해 키를 제한하려면 키 제한을 클릭하여 키 보호를 위한 추가 단계를 완료합니다. 그렇지 않으면 닫기를 클릭합니다.

키를 제한하는 방법을 알아보려면 API 키 제한 적용을 참조하세요.

개인 액세스 토큰 만들기

다음 태스크를 수행하려면 GitLab Enterprise Edition에서 두 개의 개인 액세스 토큰을 만들어야 합니다.

웹훅 만들기: api 액세스 권한이 있는 개인 액세스 토큰을 만듭니다.
저장소 데이터 검색: read_api 액세스 권한이 있는 개인 액세스 토큰을 만듭니다.

개인 액세스 토큰을 만든 후에는 토큰 값을 임시로 일반 텍스트 파일에 저장하세요. 이후 Cloud Build에서 사용할 사용자 인증 정보 저장소인 Secret Manager에 토큰을 추가합니다. 토큰은 GitLab Enterprise Edition 저장소를 Cloud Build에 연결하는 데 사용됩니다.

GitLab Enterprise Edition 호스트에 연결

콘솔

Google Cloud 콘솔을 사용하여 GitLab Enterprise Edition 호스트를 Cloud Build에 연결하려면 다음 안내를 따르세요.

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

저장소 관리 페이지 열기
드롭다운 메뉴에서 리전을 선택합니다.

참고: 리전이 global로 설정된 경우 호스트를 연결할 수 없습니다.
호스트 연결을 클릭합니다.
GitLab Enterprise Edition을 선택합니다.

호스트 연결 패널이 나타납니다.

GitLab Enterprise Edition 인스턴스를 Cloud Build에 연결하려면 다음 정보를 입력하세요.
- 이름: 호스트 연결의 이름입니다.
  
  참고: 이름은 Google Cloud 프로젝트 위치 내에서 고유해야 합니다.
- Host url: GitLab Enterprise Edition 인스턴스의 호스트 URL입니다. 예를 들면 https://gitlab.example.com입니다.
  
  참고: 호스트 URL은 IP 주소가 아닌 도메인 이름이어야 합니다.
- Google Cloud API 키: 사용자 인증 정보를 인증하는 데 사용되는 API 키입니다.
- [선택사항] CA 인증서: 자체 서명 또는 비공개 인증서입니다. 인증서 크기는 10KB를 초과할 수 없으며 PEM 형식(.pem, .cer, .crt)이어야 합니다. 이 섹션을 비워 두면 기본 인증서 집합이 사용됩니다.
  참고: 자체 서명 또는 비공개 인증서를 사용하는 경우, 리프 인증서만이 아니라 루트 인증서를 포함한 인증서 체인을 Cloud Build에 업로드해야 합니다.
- 사용자 이름: GitLab Enterprise Edition 계정 사용자 이름입니다. 이 계정에는 Cloud Build와 연결할 저장소에 대한 유지관리 담당자 액세스 권한이 있어야 합니다.
- Read API 액세스 토큰: 읽기 권한이 있는 GitLab Enterprise Edition 계정 개인 액세스 토큰입니다.
- API 액세스 토큰: 프로젝트 및 저장소에 대한 API 권한이 있는 GitLab Enterprise Edition 계정 개인 액세스 토큰입니다.
- 연결 유형: Cloud Build가 공개 인터넷을 통해 인스턴스에 연결하는 경우 공개 인터넷을 선택합니다. Cloud Build가 서비스 디렉터리를 사용하여 기존 VPC 네트워크를 통해 인스턴스를 연결하는 경우 비공개 네트워크 액세스를 선택합니다.
- [선택사항] 서비스 디렉터리 서비스: 연결 유형으로 비공개 네트워크 액세스를 선택한 경우 서비스 디렉터리 서비스의 이름을 입력합니다. 자세한 내용은 비공개 액세스를 위한 서비스 디렉터리 사용 또는 비공개 네트워크의 GitLab Enterprise Edition에서 저장소 빌드를 참조하세요.
호스트 연결을 클릭합니다.

저장소 연결 패널이 나타납니다.

호스트 연결을 만든 후 개인 액세스 토큰과 API 키는 Secret Manager에 안전하게 저장됩니다. 호스트 연결에 따라 Cloud Build가 사용자를 대신하여 웹훅 보안 비밀을 만듭니다. Secret Manager 페이지에서 보안 비밀을 보고 관리할 수 있습니다.

gcloud

gcloud 명령어를 사용하여 GitLab Enterprise Edition 호스트를 Cloud Build에 연결하려면 터미널에서 gcloud alpha builds enterprise-config gitlab create 명령어를 실행해야 합니다. Google Cloud 콘솔을 사용하여 호스트를 연결하는 것과 달리 다음 명령어를 실행하기 전에 개인 액세스 토큰, API 키, 웹훅 보안 비밀을 수동으로 Secret Manager에 저장해야 합니다.

gcloud alpha builds enterprise-config gitlab create
    --name=GITLAB_ENTERPRISE_EDITION_CONFIG_NAME \
    --region=REGION \
    --user-name=USERNAME \
    --host-uri=HOST_URI \
    --api-access-token-secret-version=API_ACCESS_TOKEN_SECRET_VERSION \
    --read-access-token-secret-version=READ_ACCESS_TOKEN_SECRET_VERSION \
    --webhook-secret-secret-version=WEBHOOK_SECRET_SECRET_VERSION \
    --api-key-secret-version=API_KEY_SECRET_VERSION \
    --service-directory-service=SERVICE_DIRECTORY_SERVICE \
    --ssl-ca-file=SSL_CA_FILE

다음을 바꿉니다.

GITLAB_ENTERPRISE_EDITION_CONFIG_NAME: GitLab Enterprise Edition 구성 이름입니다.
REGION: GitLab Enterprise Edition 구성이 위치한 리전입니다.

참고: 리전이 global로 설정된 경우 호스트를 연결할 수 없습니다.
USERNAME:GitLab Enterprise Edition 사용자 이름입니다.
HOST_URI: GitLab Enterprise Edition의 호스트 URI입니다.
API_ACCESS_TOKEN_SECRET_VERSION: Secret Manager에 저장된 api 액세스 토큰의 리소스 이름입니다. Secret Manager에 저장된 보안 비밀에 필요한 형식은 projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}입니다. 보안 비밀의 최신 버전을 사용하도록 latest를 버전으로 지정할 수 있습니다. 이는 Secret Manager에 저장된 각 리소스에 적용됩니다.

참고: Cloud Build 서비스 계정인 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com에 Secret Manager 역할을 부여해야 할 수 있습니다. 자세한 내용은 서비스 계정에 Secret Manager 역할 부여를 참조하세요.
READ_ACCESS_TOKEN_SECRET_VERSION: Secret Manager에 저장된 읽기 액세스 토큰의 리소스 이름입니다.
WEBHOOK_SECRET_SECRET_VERSION: Secret Manager에 저장된 웹훅 보안 비밀의 리소스 이름입니다.
API_KEY_SECRET_VERSION: Google Cloud API 키입니다.
[선택사항] SERVICE_DIRECTORY_SERVICE: GitLab Enterprise Edition 인스턴스와 통신하는 데 사용되는 서비스 디렉터리의 이름입니다.
[선택사항] SSL_CA_FILE은 GitLab Enterprise Edition에 대한 요청에 사용할 SSL 인증서입니다. 인증서는 PEM 형식이어야 합니다. 로컬 파일 경로를 사용하여 인증서를 업로드할 수 있습니다.

API

Cloud Build API를 사용하여 GitLab Enterprise Edition 호스트를 Cloud Build에 연결하려면 다음 JSON 템플릿을 사용하세요. Google Cloud 콘솔을 사용하여 호스트를 연결하는 것과 달리 API를 호출하기 전에 개인 액세스 토큰과 웹훅 보안 비밀을 Secret Manager에 수동으로 저장해야 합니다.

  {
      "username": "USERNAME",
      "secrets": {
        "apiAccessTokenVersion": "API_ACCESS_TOKEN_SECRET_VERSION",
        "readAccessTokenVersion": "READ_ACCESS_TOKEN_SECRET_VERSION",
        "webhookSecretVersion": "WEBHOOK_SECRET_SECRET_VERSION",
        "apiKeyVersion": "API_KEY_SECRET_VERSION"
      },
      "enterpriseConfig": {
        "hostUri": "HOST_URI",
        "sslCa": "SSL_CA",
        "serviceDirectoryConfig": {
          "service: "SERVICE_DIRECTORY_SERVICE"
        }
      }
  }

다음을 바꿉니다.

USERNAME:GitLab Enterprise Edition 사용자 이름입니다.
API_ACCESS_TOKEN_SECRET_VERSION: Secret Manager에 저장된 api 액세스 토큰의 리소스 이름입니다. Cloud Build 서비스 계정(service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com)에 Secret Manager 역할을 부여해야 할 수 있습니다. 자세한 내용은 서비스 계정에 Secret Manager 역할 부여를 참조하세요.

참고: Secret Manager에 저장된 보안 비밀의 리소스 이름에 필요한 형식은 projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}입니다. 보안 비밀의 최신 버전을 사용하도록 latest를 버전으로 지정할 수 있습니다. 이는 Secret Manager에 저장된 각 리소스에 적용됩니다.
READ_ACCESS_TOKEN_SECRET_VERSION: Secret Manager에 저장된 읽기 액세스 토큰의 리소스 이름입니다.
WEBHOOK_SECRET_SECRET_VERSION: Secret Manager에 저장된 웹훅 보안 비밀의 리소스 이름입니다.
API_KEY_SECRET_VERSION: Google Cloud API 키입니다.
HOST_URI: GitLab Enterprise Edition 인스턴스의 호스트 URI입니다.
[선택사항] SSL_CA은 GitLab Enterprise Edition에 대한 요청에 사용할 SSL 인증서입니다. 인증서는 PEM 형식이어야 하며 문자열로 제공되어야 합니다.
[선택사항] SERVICE_DIRECTORY_SERVICE은 GitLab Enterprise Edition 인스턴스와 통신하는 데 사용되는 서비스 디렉터리의 이름입니다.

터미널에 다음 curl 명령어를 입력합니다.

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/gitLabConfigs?gitlabConfigId=GITLAB_ENTERPRISE_EDITION_CONFIG_NAME -d @config.json

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REGION: GitLab Enterprise Edition 구성이 위치한 리전입니다.

참고: 리전이 global로 설정된 경우 호스트를 연결할 수 없습니다.
GITLAB_ENTERPRISE_EDITION_CONFIG_NAME: GitLab Enterprise Edition 구성 이름입니다.

다음 단계

GitLab Enterprise 버전 저장소 연결 방법 알아보기