웹훅 설정

이 페이지에서는 Secure Source Manager에서 웹훅을 설정하는 방법을 설명합니다.

웹훅은 Secure Source Manager의 이벤트에 의해 트리거되고 사용자가 지정한 URL로 전송되는 HTTP 요청입니다.

시작하기 전에

1. Secure Source Manager 인스턴스를 만듭니다.
2. Secure Source Manager 저장소 만들기

필요한 역할

웹훅을 만드는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 민감한 쿼리 문자열을 사용하여 웹훅을 인증합니다.
  • Secure Source Manager 저장소에 대한 Secure Source Manager 저장소 관리자 (roles/securesourcemanager.repoAdmin)
  • Secure Source Manager 인스턴스에 대한 Secure Source Manager 인스턴스 접근자 (roles/securesourcemanager.instanceAccessor)
• 서비스 계정 승인을 사용하여 웹훅을 인증합니다.
  • Secure Source Manager 저장소 서비스 계정에 대한 서비스 계정 사용자 (roles/iam.serviceAccountUser)
  • Secure Source Manager 저장소 서비스 계정의 SSM 서비스 에이전트 (roles/iam.serviceAccountTokenCreator)
  • 대상 서비스에 대한 Cloud Run 호출자 (roles/run.invoker)(대상 서비스가 Cloud Run인 경우에만 필요)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Secure Source Manager 역할 부여에 대한 자세한 내용은 IAM으로 액세스 제어 및 사용자에게 인스턴스 액세스 권한 부여를 참고하세요.

웹훅 설정

콘솔

1. Secure Source Manager 웹 인터페이스에서 웹훅을 만들 저장소로 이동합니다.
2. 설정을 클릭합니다.
3. 웹훅을 클릭한 다음 웹훅 추가를 클릭합니다.

4. Hook ID 필드에 웹훅의 ID를 입력합니다.

   참고: 후크 ID는 리소스 이름 지정 규칙을 따라야 합니다. 소문자, 숫자 또는 대시만 포함해야 하며 문자로 시작해야 하고 웹훅을 만든 후에는 변경할 수 없습니다.

5. 타겟 URL 필드에 웹훅 URL을 입력합니다. 예를 들어 Jenkins에서 빌드를 트리거하려면 웹훅 트리거를 설정한 다음 여기에 Jenkins 트리거 URL을 입력하여 Jenkins에서 빌드를 트리거하면 됩니다.

6. 트리거 조건 섹션에서 다음 중 하나를 선택합니다.

   • 푸시: 저장소로 푸시할 때 트리거됩니다.
   • Pull request state changed: pull 요청 상태가 변경될 때 트리거됩니다.

7. 민감한 쿼리 문자열 또는 서비스 계정 인증을 사용하여 웹훅 인증을 구성합니다.

   • 민감한 쿼리 문자열:

     민감한 쿼리 문자열은 key= 및 secret= 접두사를 포함하여 웹훅 URL의 key 및 secret 값으로 구성됩니다. 민감한 쿼리 문자열 승인을 구성하려면 웹훅 URL에서 이러한 값을 삭제하고 민감한 쿼리 문자열 필드에 추가해야 합니다.

     1. 웹훅 URL에서 ?를 삭제합니다.
     2. key=로 시작하는 URL의 나머지 부분을 복사합니다.
     3. 이 부분을 민감한 쿼리 문자열 필드에 붙여넣습니다.
     4. 웹훅 URL에서 동일한 부분을 삭제합니다.

     예를 들어 다음 URL이 있다고 가정해 보겠습니다. https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

     민감한 쿼리 문자열은 다음과 같습니다. key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

     참고: 웹훅을 추가하거나 수정할 때 Sensitive Query String의 길이가 입력된 길이와 일치하지 않을 수 있습니다. 이는 보안을 위해 자리표시자 문자열이 사용되기 때문입니다.

   • 서비스 계정 인증:

     1. 저장소에 필수 역할에 서비스 계정 인증을 위해 정의된 IAM 역할이 있는 서비스 계정이 있는지 확인합니다.
     2. 서비스 계정 인증 사용 설정을 선택합니다.

8. 푸시를 선택한 경우 브랜치 필터 필드에 푸시 이벤트 허용 목록을 입력할 수 있습니다.

   브랜치 필터 필드는 glob 패턴을 사용하며 일치하는 브랜치에 대한 작업만 빌드 트리거를 발생시킵니다. 예를 들어 {main,dev}는 main 및 dev 브랜치로 푸시하는 이벤트에서 트리거됩니다. 필드가 비어 있거나 *이면 모든 브랜치의 푸시 이벤트가 보고됩니다. 구문에 대한 자세한 내용은 glob 문서를 참고하세요.

9. 웹훅 추가를 클릭합니다.

10. 웹훅이 웹훅 페이지에 표시됩니다.

REST

웹훅을 만들려면 hooks 엔드포인트에 POST 요청을 실행하여 hooks.create 메서드를 호출합니다. 민감한 쿼리 문자열 또는 서비스 계정 인증을 사용하여 웹훅을 인증할 수 있습니다.

• 민감한 쿼리 문자열

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
      "events": ["PUSH"]
      "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
    }' \
    "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"
  

  SENSITIVE_QUERY_STRING_VALUE은 웹훅 URL의 key 및 secret 값이어야 합니다. 예를 들어 key이 eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf이고 secret이 MySecret이면 SENSITIVE_QUERY_STRING_VALUE은 key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret이어야 합니다.

  참고: 웹훅을 추가하거나 수정할 때 Sensitive Query String의 길이가 입력된 길이와 일치하지 않을 수 있습니다. 이는 보안을 위해 자리표시자 문자열이 사용되기 때문입니다.

• 서비스 계정 인증

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "targetUri": "https://${SERVICE_NAME}.app/webhook",
      "events": ["PUSH"],
      "serviceAccountAuth": true
    }' \
    "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"
  

웹훅 테스트

1. Secure Source Manager 웹훅 페이지에서 테스트할 웹훅을 클릭합니다.

2. 페이지 하단으로 이동하여 전송 테스트를 클릭합니다.

   플레이스홀더 이벤트가 전송 큐에 추가됩니다. 배송 기록에 표시되기까지 몇 초 정도 걸릴 수 있습니다.

3. git 명령어를 사용하여 pull 요청을 푸시하거나 병합하여 웹훅을 테스트할 수도 있습니다.

4. 웹훅 트리거를 구성한 서비스의 빌드 기록에서 트리거된 빌드 또는 이벤트의 상태를 확인합니다.

5. 첫 번째 테스트 전송을 보낸 후 Secure Source Manager 웹훅 페이지의 최근 전송 섹션에서 테스트 전송에 대한 요청 및 응답을 확인할 수도 있습니다.

Cloud Build YAML 변수를 페이로드 데이터로 대체

웹훅을 사용하여 Cloud Build에 연결하는 경우 Cloud Build YAML 변수를 Secure Source Manager 웹훅 페이로드 데이터로 대체할 수 있습니다.

1. Secure Source Manager 웹훅 페이지의 최근 전송 섹션에서 상단 행을 클릭합니다.

   웹훅 페이로드에서 전송된 Request 헤더와 콘텐츠가 표시됩니다.

2. Cloud Build 대시보드로 이동한 다음 트리거를 클릭합니다.

3. 구성하려는 트리거를 클릭합니다.

4. 고급 섹션의 대체 변수에서 + 변수 추가를 클릭합니다.

5. 변수의 이름과 값을 입력합니다. 값 접두사는 body입니다.

   예를 들어 _REPO_URL을 페이로드 데이터 필드 repository.clone_url로 대체하고 _COMMIT_SHA을 Cloud Build YAML의 최신 커밋 sha로 대체하려면 다음 이름과 값을 입력합니다.

   • 변수 1: _REPO_URL 값 1: $(body.repository.clone_url)
   • 변수 2: _COMMIT_SHA 값 2: $(body.after)

   Cloud Build YAML 파일은 다음과 유사합니다.

   steps:
   - name: gcr.io/cloud-builders/git
     env:
     - '_REPO_URL=$_REPO_URL'
     - '_COMMIT_SHA=$_COMMIT_SHA'
     script: |
       #!/bin/sh
       git clone ${_REPO_URL} /workspace
       cd /workspace
       git reset --hard ${_COMMIT_SHA}
   

다음 단계

• Jenkins에 연결