GitLab 호스트에 연결

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

시작하기 전에

  • Cloud Build 및 Secret Manager API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한을 이미 보유하고 있을 가능성이 높습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법을 알아보세요.

    API 사용 설정

GitLab 호스트에 연결

GitLab 인스턴스에 대한 호스트 연결을 만들기 전에 다음 단계를 완료하여 GitLab에서 개인 액세스 토큰을 만들어야 합니다.

  1. GitLab 인스턴스에 로그인합니다.

  2. 인스턴스의 GitLab 페이지 오른쪽 상단에 있는 아바타를 클릭합니다.

  3. 프로필 수정 을 클릭합니다.

  4. 왼쪽 사이드바에서 액세스 토큰 을 선택합니다.

    개인 액세스 토큰 페이지가 표시됩니다.

  5. 저장소 연결과 연결 해제에 사용할 수 있도록 api 범위의 액세스 토큰을 만듭니다.

  6. Cloud Build 저장소가 저장소에 있는 소스 코드에 액세스할 수 있도록 read_api 범위의 액세스 토큰을 만듭니다.

콘솔

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

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

    저장소 페이지 열기

    저장소 페이지가 표시됩니다.

  2. 페이지 상단에서 2세대 탭을 선택합니다.

  3. 상단 표시줄의 프로젝트 선택기에서 Google Cloud 프로젝트를 선택합니다.

  4. 호스트 연결 만들기 를 클릭하여 새 호스트를 Cloud Build에 연결합니다.

  5. 왼쪽 패널에서 GitLab을 소스 제공업체로 선택합니다.

  6. 연결 구성 섹션에서 다음 정보를 입력합니다.

    • 리전: 연결의 리전을 선택합니다.

    • 이름: 연결의 이름을 입력합니다.

  7. 호스트 세부정보 섹션에서 GitLab 호스트 로 이동하여 GitLab.com 을 선택합니다.

  8. 선택사항: GitLab 저장소의 액세스 토큰을 암호화하는 데 사용되는 암호화 키를 관리하려면 암호화 섹션으로 이동하여 Cloud Key Management Service 키를 선택합니다. 자세한 내용은 Secret Manager에 고객 관리 암호화 키 사용 설정을 참조하세요.

  9. 개인 액세스 토큰 섹션에서 다음 정보를 입력합니다.

    • API 액세스 토큰: api 범위 액세스 권한이 있는 토큰을 입력합니다. 이 토큰은 저장소 연결과 연결 해제에 사용됩니다.

    • API 읽기 액세스 토큰: read_api 범위 액세스 권한이 있는 토큰을 입력합니다. Cloud Build 트리거는 이 토큰을 사용하여 저장소의 소스 코드에 액세스합니다.

  10. 연결을 클릭합니다.

    연결 버튼을 클릭한 후 개인 액세스 토큰이 Secret Manager에 안전하게 저장됩니다. 호스트 연결에 따르면 Cloud Build에서 웹훅 보안 비밀도 자동으로 만듭니다. Secret Manager 페이지에서 보안 비밀을 보고 관리할 수 있습니다.

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

gcloud

GitLab 호스트를 Cloud Build에 연결하기 전에 다음 단계를 완료하여 사용자 인증 정보를 저장합니다.

  1. Secret Manager에 토큰을 저장합니다.

  2. 다음 명령어를 실행하여 Secret Manager에 웹훅 보안 비밀을 만듭니다 .

     cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-

  3. 호스트 연결을 만드는 데 사용하려는 것과 다른 Google Cloud 프로젝트에 보안 비밀을 저장하는 경우 다음 명령어를 입력하여 프로젝트에 Cloud Build 서비스 에이전트에 대한 액세스 권한을 부여합니다.

    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"

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

    • PROJECT_ID는 Google Cloud 프로젝트 ID입니다.

이제 GitLab 호스트를 Cloud Build에 연결하는 단계를 진행할 수 있습니다.

다음 단계를 완료합니다.

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

  1. 다음 명령어를 입력하여 GitLab 연결을 만듭니다.

    gcloud builds connections create gitlab CONNECTION_NAME \
  --host-uri=HOST_URI \
  --project=PROJECT_ID \
  --region=REGION \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/API_TOKEN/versions/SECRET_VERSION \
  --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION

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

    • CONNECTION_NAME은 Cloud Build의 GitLab 호스트 연결 이름입니다.
    • HOST_URI은(는) GitLab 인스턴스의 URI입니다. 예를 들면 https://my-gle-server.net입니다.
    • PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
    • REGION은 연결의 리전입니다.
    • API_TOKEN: api 범위의 토큰 이름입니다.
    • READ_TOKEN: read_api 범위의 토큰 이름입니다.
    • SECRET_VERSION: 보안 비밀 버전입니다.
    • WEBHOOK_SECRET: 웹훅 보안 비밀입니다.

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

오래되었거나 만료된 GitLab 액세스 토큰 순환

Cloud Build 호스트 연결이 GitLab 저장소에 대한 연결을 유지할 수 있도록 액세스 토큰을 순환합니다. GitLab 액세스 토큰이 만료되면 Cloud Build 호스트 연결이 GitLab 저장소에서 연결 해제됩니다. 이 경우 만료된 토큰을 순환할 때까지 연결을 사용 중지하거나 저장소를 연결할 수 없습니다. 또한 다음과 같은 상황에서 오류가 표시됩니다.

  • 연결의 연결 세부정보 페이지에 Connection is disconnected due to an invalid or expired access token이라는 오류 메시지가 표시됩니다.

  • 만료된 토큰이 있는 연결에 저장소를 연결하려고 하면 액세스 토큰이 유효하지 않음 메시지가 표시됩니다. 연결 보기 를 클릭하면 만료된 토큰이 있는 연결의 연결 세부정보 페이지로 이동합니다.

Cloud Build를 사용하면 새 토큰 값을 입력하고 해당 토큰의 최신 보안 비밀 버전에서 Secret Manager에 저장하여 액세스 토큰을 순환할 수 있습니다. 액세스 토큰을 순환하려면 다음 안내를 따르세요.

  1. GitLab에서 각 액세스 토큰을 순환합니다.

    1. Cloud Build 호스트 연결에 연결된 GitLab 저장소로 이동합니다.

    2. GitLab 문서의 안내에 따라 액세스 토큰을 순환합니다. 토큰을 순환하면 GitLab에서 새 사용자 인증 정보로 새 토큰을 만들고 이전 버전의 토큰을 무효화합니다. 순환된 토큰은 원래 토큰과 동일한 권한과 범위를 갖습니다.

    3. 순환된 토큰의 ID를 복사합니다.

  2. Cloud Build에서 액세스 토큰을 업데이트합니다.

    1. 연결의 연결 세부정보 페이지로 이동합니다.

    2. 액세스 토큰 업데이트 를 선택합니다.

    3. 토큰 순환 메뉴에서 API 액세스 토큰 및 액세스 토큰 읽기 필드에 새 토큰을 입력합니다.

    4. 선택사항: 연결에서 항상 토큰의 최신 버전의 보안 비밀을 사용하도록 하려면 항상 최신 버전을 사용하도록 연결 업데이트 를 선택합니다. 연결에서 특정 보안 비밀 버전 번호를 사용하는 경우 이 옵션을 선택하지 않은 상태로 두는 것이 유용할 수 있습니다.

    5. 업데이트 를 선택하여 변경사항을 저장합니다.

      Cloud Build는 새 액세스 토큰을 Secret Manager에 최신 버전의 보안 비밀로 저장합니다.

자세한 내용은 액세스 토큰 만료를 GitLab 문서에서 참조하세요.

다음 단계