빌드 트리거 만들기 및 관리

Cloud Build 트리거는 소스 코드가 변경될 때마다 빌드를 자동으로 시작합니다. 트리거가 소스 저장소의 변경사항 또는 특정 기준과 일치하는 변경사항에 따라 코드를 빌드하도록 구성할 수 있습니다.

이 페이지에서는 GitHub 및 Bitbucket과 같은 소스 저장소에 연결하는 방법과 저장소에서 코드를 빌드하도록 빌드 트리거를 만드는 방법을 설명합니다.

시작하기 전에

  • Cloud Build API 사용 설정

    API 사용 설정

  • 트리거를 만들려면 프로젝트에 Cloud Build 편집자(roles/cloudbuild.builds.editor) 역할이 있어야 합니다.
  • Cloud Source Repositories, GitHub 또는 Bitbucket의 소스 코드가 필요합니다.
  • Dockerfile 또는 Cloud Build 구성 파일이 필요합니다.

소스 저장소에 연결

저장소에 코드를 빌드하기 전에 Cloud Build를 소스 저장소에 연결해야 합니다. Cloud Source Repositories의 저장소는 기본적으로 Cloud Build에 연결됩니다. 수동으로 연결하지 않고 Cloud Source Repositories의 저장소에 대해 트리거를 직접 만들 수 있습니다.

GitHub 또는 Bitbucket에 호스팅되는 것과 같은 외부 저장소에 연결하는 경우 처음에 저장소를 Cloud Build에 연결하기 위해 저장소에 대해 관리자 수준 권한이 필요합니다. 이미 Cloud Build에 연결된 저장소에서 트리거를 만들 때는 관리자 권한이 필요하지 않습니다.

GitHub 또는 Bitbucket에 연결하려면 다음 단계별 안내를 완료하세요.

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    트리거 페이지 열기

  2. 프로젝트를 선택하고 열기를 클릭합니다.

  3. 리전 드롭다운 메뉴에서 트리거를 만들 리전을 선택합니다.

  4. 저장소 연결을 클릭합니다.

  5. 소스 코드를 저장한 저장소를 선택합니다.

    소스 저장소로 GitHub(미러링됨) 또는 Bitbucket(미러링됨)을 선택하면 Cloud Build는 Cloud Source Repositories에서 저장소를 미러링하고 모든 작업에 미러링된 저장소를 사용합니다.

  6. 계속을 클릭합니다.

  7. 사용자 이름과 비밀번호를 사용하여 소스 저장소에 인증합니다.

  8. 사용 가능한 저장소 목록에서 원하는 저장소를 선택한 다음 연결을 클릭합니다.

    GitHub 및 Bitbucket과 같은 외부 저장소의 경우 작업 중인 Google Cloud 프로젝트의 소유자 수준 권한이 있어야 합니다.

  9. 트리거 만들기를 클릭하여 저장소의 소스 코드 빌드를 자동화하는 빌드 트리거를 계속 만들거나 완료를 클릭합니다.

빌드 트리거 만들기

콘솔

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    트리거 페이지 열기

  2. 페이지 상단의 프로젝트 선택기 드롭다운 메뉴에서 프로젝트를 선택합니다.

  3. 열기를 클릭합니다.

  4. 트리거 만들기를 클릭합니다.

  5. 다음 트리거 설정을 입력합니다.

    • 이름: 트리거 이름을 입력합니다.

    • 리전: 트리거의 리전을 선택합니다.

      트리거와 연결된 빌드 구성 파일이 비공개 풀을 지정하는 경우, 트리거에 선택한 리전이 비공개 풀의 리전과 일치해야 합니다.

      global을 리전으로 선택하면 Cloud Build가 빌드 구성 파일에 지정된 리전을 사용하여 빌드를 실행합니다. 빌드 구성 파일에 비공개 풀을 지정하는 경우 비공개 풀의 리전이거나 비공개 풀을 지정하지 않은 경우 전역 기본 풀일 수 있습니다.

    • 설명(선택사항): 트리거에 대한 설명을 입력합니다.

    • 이벤트: 트리거를 호출할 저장소 이벤트를 선택합니다.

      • 브랜치로 푸시: 특정 브랜치 대한 커밋에서 빌드를 시작하도록 트리거를 설정합니다.

      • 새 태그 푸시: 특정 태그가 포함된 커밋에서 빌드를 시작하도록 트리거를 설정합니다.

      • Pull 요청: Pull 요청에 대한 커밋에서 빌드를 시작하도록 트리거를 설정합니다.

    • 소스: 1세대 또는 2세대를 소스로 선택합니다. 2세대를 소스로 선택한 경우에만 GitHub와 GitHub Enterprise의 저장소를 연결할 수 있습니다. 자세한 내용은 Cloud Build 저장소를 참조하세요.

      • 저장소: 사용 가능한 저장소 목록에서 원하는 저장소를 선택합니다. 새 저장소를 연결하려면 소스 저장소에 연결을 참조하세요.
      • 분기 또는 태그: 일치시킬 분기 또는 태그 값으로 정규 표현식을 지정합니다. 슬래시(/)는 태그에 사용할 수 없습니다. 허용되는 정규 표현식 구문에 대한 자세한 내용은 RE2 구문을 참조하세요.

        빌드가 실행되면 Cloud Build가 저장소의 내용을 Cloud Build의 기본 작업 디렉터리인 /workspace에 복사합니다. 빌드 구성 개요 페이지에서 작업 디렉터리에 대해 자세히 알아보세요.

        특정 소스의 빌드만 허용하려면 허용된 통합(constraints/cloudbuild.allowedIntegrations)에 대한 조직 정책을 설정하여 트리거에 정의된 소스와의 상호작용을 거부합니다. 조직 정책이 트리거를 재정의하고 빌드가 실행되지 않습니다. 자세한 내용은 프로젝트의 조직 정책을 기반 게이트 빌드를 참조하세요.

    • 포함된 파일(선택사항): 파일 중 하나 이상에 영향을 주는 변경사항이 있으면 빌드가 호출됩니다. glob 문자열을 사용하여 와일드 카드 문자로 파일 여러 개를 지정할 수 있습니다. 허용되는 와일드 카드 문자에는 Go Match에서 지원하는 문자, **, 교체가 있습니다.

    • 무시된 파일(선택사항): 무시된 파일에만 영향을 주는 변경사항이 있으면 빌드가 호출되지 않습니다. glob 문자열을 사용하여 와일드 카드 문자로 파일 여러 개를 지정할 수 있습니다. 허용되는 와일드 카드 문자에는 Go Match에서 지원하는 문자, **, 교체가 있습니다.

      포함된 파일무시된 파일 모두에 파일을 지정한 경우 파일 변경사항이 있어도 빌드가 호출되지 않습니다. 무시된 파일**/README.md를 지정하여 모든 디렉터리의 README.md를 무시하고 포함된 파일src/*를 지정하여 src/ 폴더의 파일이 변경될 때 빌드를 시작하는 경우를 가정해 보겠습니다. 이제 src/README.md를 변경해도 Cloud Build가 빌드를 시작하지 않습니다. 변경사항을 소스로 내보낼 때마다 Cloud Build가 변경된 파일에 포함된 파일과 및 무시된 파일이 있는지 확인하여 빌드 호출 여부를 결정합니다.

      • 기존 분기의 저장소에 변경사항을 푸시하면 Cloud Build가 방금 전에 푸시된 커밋과 분기가 이전에 가리킨 커밋 사이에 변경된 파일이 있는지 확인합니다.
      • 저장소가 Cloud Source Repository이고 새로 생성된 분기에 변경사항을 푸시하면 Cloud Build가 저장소의 모든 파일을 변경된 파일로 취급합니다.
      • 분기를 삭제하면 Cloud Build가 빌드를 시작하지 않습니다.
    • 구성: 원격 저장소에 있는 빌드 구성 파일을 선택하거나 빌드에 사용할 인라인 빌드 구성 파일을 만듭니다.

      • 유형: 빌드에 사용할 구성의 유형을 선택합니다.
        • Cloud Build 구성 파일(yaml 또는 json): 구성에 대해 빌드 구성 파일을 사용합니다.
        • Dockerfile: 해당 구성에 Dockerfile을 사용합니다.
        • 빌드팩: 구성에 빌드팩을 사용합니다.
      • 위치: 구성의 위치를 지정합니다.

        • 저장소: 구성 파일이 원격 저장소에 있으면 빌드 구성 파일의 위치, Dockerfile 디렉터리 또는 빌드팩 디렉터리를 제공합니다. 빌드 구성 유형이 Dockerfile 또는 빌드팩이면 결과 이미지의 이름을 제공하고, 선택적으로 빌드의 제한 시간을 제공해야 합니다. Dockerfile 또는 빌드팩 이미지 이름을 제공한 경우 빌드가 실행할 docker build 또는 pack 명령어의 미리보기가 표시됩니다.
        • 빌드팩 환경 변수(선택사항): buildpacks를 구성 유형으로 선택한 경우 팩 환경 변수 추가를 클릭하여 빌드팩 환경 변수 및 값을 지정합니다. 빌드팩 환경 변수에 대해 자세히 알아보려면 환경 변수를 참조하세요.
        • 인라인: Cloud Build 구성 파일(yaml 또는 json)을 구성 옵션으로 선택한 경우 빌드 구성을 인라인으로 지정할 수 있습니다. YAML 또는 JSON 구문을 사용하여 Google Cloud 콘솔에서 빌드 구성 파일을 작성하려면 편집기 열기를 클릭합니다. 빌드 구성을 저장하려면 완료를 클릭합니다.

    • 비공개 풀 사용: 이 필드는 Dockerfile구성 옵션으로 선택한 경우에 표시됩니다. 비공개 풀에서 빌드를 실행하는 경우 이 체크박스를 선택합니다.

    • 비공개 풀: 비공개 풀 사용을 선택한 경우 비공개 풀의 리소스 이름을 projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID 형식으로 지정합니다.

    • 대체 변수(선택사항): Cloud Build 구성 파일을 빌드 구성 옵션으로 선택한 경우 이 필드를 사용하여 트리거별 대체 변수를 정의할 수 있습니다. 예를 들어 각 트리거가 앱을 특정 환경에 배포하는 트리거를 여러 개 만든다고 가정해 보겠습니다. 앱이 빌드 구성 파일의 한 환경에 배포되도록 지정한 후 이 필드를 사용하여 트리거가 배포할 환경을 지정하는 대체 변수를 정의할 수 있습니다. 빌드 구성 파일의 대체 값을 지정하는 방법은 대체 변수 값을 참조하세요.

    • 승인(선택사항): 빌드가 실행되기 전에 승인을 요청하려면 상자를 선택합니다.

    • 서비스 계정: 트리거를 호출할 때 사용할 서비스 계정을 선택합니다. 서비스 계정을 선택하지 않으면 기본 Cloud Build 서비스 계정이 사용됩니다.

  6. 만들기를 클릭하여 빌드 트리거를 저장합니다.

gcloud

소스 코드가 Cloud Source Repositories에 있을 때 트리거를 만들려면 다음 안내를 따르세요.

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

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

  • REPO_NAME은 저장소 이름입니다.
  • BRANCH_PATTERN은 빌드를 호출할 저장소의 분기 이름입니다.
  • TAG_PATTERN은 빌드를 호출할 저장소의 태그 이름입니다.
  • BUILD_CONFIG_FILE은 빌드 구성 파일의 경로입니다.

  • SERVICE_ACCOUNT은 서비스 계정과 연결된 이메일입니다. 이 플래그를 포함하지 않으면 기본 Cloud Build 서비스 계정이 사용됩니다.

  • [선택사항] --require-approval은 승인이 필요하도록 트리거를 구성하는 데 포함할 플래그입니다.

플래그 전체 목록은 Cloud Source Repositories에 대한 트리거를 만드는 방법에 대한 gcloud 참조를 참조하세요.

소스 코드가 GitHub에 있을 때 트리거를 만들려면 다음 안내를 따르세요.

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

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

  • REGION은 트리거의 리전입니다.
  • REPO_NAME은 저장소 이름입니다.
  • REPO_OWNER은 저장소 소유자의 사용자 이름입니다.
  • BRANCH_PATTERN은 빌드를 호출할 저장소의 브랜치 이름입니다.
  • TAG_PATTERN은 빌드를 호출할 저장소의 태그 이름입니다.
  • BUILD_CONFIG_FILE은 빌드 구성 파일의 경로입니다.
  • SERVICE_ACCOUNT은 서비스 계정과 연결된 이메일입니다. 이 플래그를 포함하지 않으면 기본 Cloud Build 서비스 계정이 사용됩니다.
  • [선택사항] --require-approval은 승인이 필요하도록 트리거를 구성하는 데 포함할 플래그입니다.
  • [선택사항] --include-logs-with-status는 저장소의 빌드 로그를 표시하도록 지정할 수 있는 플래그입니다. 이 플래그는 GitHubGitHub Enterprise 저장소의 빌드에 지원됩니다.

플래그 전체 목록은 GitHub에 대한 트리거를 만드는 방법에 대한 gcloud 참조를 확인하세요.

Cloud Source Repositories 또는 GitHub를 사용하여 트리거를 만들기 위해 gcloud 명령어를 실행하면 다음과 비슷한 출력이 표시됩니다.

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

빌드 트리거 테스트

빌드 트리거를 수동으로 테스트하려면 다음 안내를 따르세요.

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    트리거 페이지 열기

  2. 목록에서 트리거를 찾은 다음 트리거 실행을 클릭합니다.

빌드 트리거 건너뛰기

경우에 따라 소스 코드를 변경하되 빌드를 호출하지 않으려 할 수 있습니다. 예를 들어 문서 또는 구성 파일을 업데이트할 경우 빌드를 호출하지 않으려 할 수 있습니다.

이러한 경우에는 커밋 메시지에 [skip ci] 또는 [ci skip]을 포함할 수 있습니다. 그러면 빌드가 호출되지 않습니다.

나중에 커밋에서 빌드를 실행하려면 트리거 페이지에서 트리거 실행 버튼을 사용합니다.

빌드에 저장소 기록 포함

Git 저장소의 소스를 빌드할 때는 Cloud Build가 저장소의 부분 클론을 수행합니다. 즉, 빌드를 시작한 단일 커밋만 빌드할 작업공간에서 체크아웃됩니다. Cloud Build는 다른 분기나 기록을 체크아웃하지 않습니다. 이는 효율성을 위한 것으로, 빌드가 단일 커밋을 빌드하기 위해 전체 저장소와 내역을 가져오기 위해 기다릴 필요가 없습니다.

빌드에 저장소 내역을 추가로 포함시키려면 빌드 구성 파일에 빌드 단계를 추가하여 '부분 복제를 해제'합니다. 예를 들면 다음과 같습니다.

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

git fetch에 대한 자세한 내용은 git 참조를 확인하세요. 빌드 구성 파일 작성 방법은 빌드 구성 개요를 참조하세요.

승인을 위해 빌드 다시 제출

빌드가 거부되면 Google Cloud Console에서 다음 단계에 따라 승인을 위해 빌드를 다시 제출할 수 있습니다.

  1. Google Cloud Console에서 Cloud Build 기록 페이지를 엽니다.

    Cloud Build 기록 페이지 열기

  2. 승인을 위해 다시 제출할 빌드의 빌드 ID를 클릭합니다.

  3. 페이지 상단의 다시 빌드를 클릭하여 승인을 위해 빌드를 다시 제출합니다.

권한이 있는 사용자가 빌드를 승인하면 빌드가 시작됩니다. Cloud Build 승인에 대한 자세한 내용은 승인 시 게이트 빌드를 참조하세요.

빌드 트리거 업데이트

콘솔

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    빌드 트리거 페이지 열기

  2. 페이지 상단의 프로젝트 선택기 드롭다운 메뉴에서 프로젝트를 선택합니다.

  3. 열기를 클릭합니다.

  4. 업데이트할 트리거가 있는 행을 찾습니다.

  5. 행의 오른쪽 끝에 있는 메뉴(수직 타원)를 클릭합니다.

  6. 수정을 선택합니다.

gcloud

트리거를 업데이트하려면 다음 안내를 따르세요.

  1. 업데이트하려는 트리거를 내보냅니다.

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

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

    • TRIGGER_NAME은 트리거의 이름입니다.
    • EXPORT_PATH는 트리거를 내보낼 파일 경로입니다. 예를 들어 파일 경로를 examples/trigger.yaml로 지정할 수 있습니다. 트리거의 파일 이름 확장자는 .yaml이어야 합니다.
  2. 내보낸 트리거가 포함된 파일을 엽니다.

    파일이 다음과 비슷하게 표시됩니다.

     createTime: '2022-05-26T21:56:11.830784153Z'
     filename: cloudbuild.yaml
     github:
       name: cloud-build-example
       owner: main
       push:
         branch: master
     id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
     # remove field name and value to not show build logs
     includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
     name: trigger-001
    
  3. 파일을 수동으로 수정하여 트리거를 업데이트합니다.

    트리거에서 추가 또는 삭제할 수 있는 필드를 보려면 트리거 리소스를 참조하세요.

  4. 파일을 저장합니다.

  5. 트리거를 가져옵니다.

     gcloud builds triggers import --source=IMPORT_PATH
    

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

    • IMPORT_PATH는 가져오려는 트리거의 파일 경로입니다.

이제 빌드 트리거가 업데이트되었습니다.

빌드 트리거 사용 중지

콘솔

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    빌드 트리거 페이지 열기

  2. 페이지 상단의 프로젝트 선택기 드롭다운 메뉴에서 프로젝트를 선택합니다.

  3. 열기를 클릭합니다.

  4. 사용 중지할 트리거가 있는 행을 찾습니다.

  5. 행의 오른쪽 끝에 있는 메뉴(수직 타원)를 클릭합니다.

  6. Disable을 선택합니다.

gcloud

트리거를 사용 중지하려면 다음 안내를 따르세요.

  1. 사용 중지하려는 트리거를 내보냅니다.

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

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

    • TRIGGER_NAME은 트리거의 이름입니다.
    • EXPORT_PATH는 트리거를 내보낼 파일 경로입니다. 예를 들어 파일 경로를 examples/trigger.yaml로 지정할 수 있습니다. 트리거의 파일 이름 확장자는 .yaml이어야 합니다.
  2. 내보낸 트리거가 포함된 파일을 엽니다.

    파일이 다음과 비슷하게 표시됩니다.

     createTime: '2020-02-21T20:02:50.215599013Z'
     description: Push to any branch
     filename: cloudbuild.yaml
     github:
       name: example-repo-name
       owner: example-owner
       push:
         branch: .*
     id: example-id
     name: Push-to-any-branch
     tags:
     - github-default-push-trigger
    
  3. 파일 끝에 disabled 필드를 추가하고 값을 True로 설정합니다.

     disabled: True
    
  4. 파일을 저장합니다.

  5. 트리거를 가져옵니다.

     gcloud builds triggers import --source=IMPORT_PATH
    

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

    • IMPORT_PATH는 가져오려는 트리거의 파일 경로입니다.

빌드 트리거가 이제 사용 중지되었습니다.

트리거를 사용 중지해도 트리거가 삭제되지는 않습니다. 트리거를 삭제하려면 빌드 트리거 삭제를 참조하세요. 상태를 사용으로 바꿔서 트리거를 다시 사용 설정할 수 있습니다.

빌드 트리거 삭제

콘솔

  1. Google Cloud Console에서 트리거 페이지를 엽니다.

    빌드 트리거 페이지 열기

  2. 페이지 상단의 프로젝트 선택기 드롭다운 메뉴에서 프로젝트를 선택합니다.

  3. 열기를 클릭합니다.

  4. 삭제할 트리거가 있는 행을 찾습니다.

  5. 행의 오른쪽 끝에 있는 메뉴(수직 타원)를 클릭합니다.

  6. 삭제를 선택합니다.

gcloud

트리거를 삭제하려면 다음 명령어를 실행합니다.

  gcloud builds triggers delete TRIGGER_NAME

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

  • TRIGGER_NAME은 트리거의 이름입니다.

플래그 전체 목록은 트리거를 삭제하는 방법에 대한 gcloud 참조를 확인하세요.

빌드 트리거의 보안 영향

기본적으로 빌드 트리거는 Cloud Build 서비스 계정을 사용하여 빌드를 실행하므로 트리거를 사용하여 빌드를 실행하는 사용자에게 빌드 시간 권한을 제공할 수 있습니다. 빌드 트리거를 사용할 때는 다음과 같은 보안 영향에 유의하세요.

  • 클라우드 프로젝트에 대한 액세스 권한이 없지만 프로젝트에서 빌드 트리거와 연결된 저장소에 쓰기 액세스 권한이 있는 사용자는 빌드 중인 코드를 변경할 수 있는 권한을 갖습니다.
  • GitHub pull 요청 트리거를 사용하는 경우, 저장소에 대해 읽기 액세스 권한이 있는 사용자가 pull 요청을 제출하여, pull 요청에 코드 변경사항이 포함된 빌드를 실행할 수 있습니다. GitHub pull 요청 트리거에 대해 이 동작을 사용 중지하는 방법은 GitHub 트리거 만들기를 참조하세요.

트리거에 필요한 역할만 있는 서비스 계정을 만드는 것이 좋습니다. 자세한 내용은 사용자 지정 서비스 계정 구성을 참조하세요. Cloud Build 서비스 계정 및 연결된 권한에 대한 자세한 내용은 Cloud Build 서비스 계정을 참조하세요.

다음 단계