대체 항목에서 페이로드 바인딩 및 bash 매개변수 확장 사용

이 페이지에서는 페이로드 바인딩을 사용하고 빌드 트리거와 연결된 대체 변수에 bash 매개변수 확장을 적용하는 방법을 설명합니다. 빌드 구성에서 대체 변수 사용 방법에 익숙하지 않으면 변수 값 대체를 참조하세요.

Cloud Build를 사용하면 트리거의 이벤트 페이로드 일부를 대체 변수로 저장할 수 있습니다. 이벤트 페이로드는 트리거를 호출하는 이벤트의 본문입니다. 페이로드와 연결된 변수를 바인딩이라고 부르고 push 및 pull 이벤트 모두로 호출되는 빌드에 사용할 수 있습니다. 바인딩을 사용하면 소스 코드와 연결된 언어 및 pull 요청의 저자와 같은 빌드 관련 추가 데이터에 액세스할 수 있습니다.

또한 사용자는 Cloud Build를 통해 bash 매개변수 확장을 대체 변수 값에 적용할 수 있습니다. Bash 매개변수 확장을 사용하면 기존 변수와 연결된 문자열을 조작할 수 있습니다. 문자를 대문자로 표시하거나 하위 문자열을 바꿔서 문자열을 조작할 수 있습니다.

Google Cloud Console과 Cloud Build 구성 파일에서 빌드 트리거를 정의 또는 업데이트할 때 페이로드 바인딩을 사용하고 bash 매개변수 확장을 적용할 수 있습니다. 또한 수동 빌드를 실행할 때 bash 매개변수 확장을 적용할 수 있습니다.

페이로드 바인딩

트리거의 이벤트 페이로드 중 일부를 대체 변수 값으로 저장할 수 있습니다. 페이로드 바인딩은 push 및 pull 이벤트로 호출되는 빌드의 변수 값으로 제공되며, 소스 코드가 GitHub 저장소 또는 Cloud Source Repositories에 있을 때 JSON 페이로드에 액세스하기 위해 사용될 수 있습니다. GitHub 이벤트 페이로드에 대한 자세한 내용은 웹훅 이벤트 페이로드를 참조하세요. Cloud Source Repositories의 이벤트 페이로드에 대한 자세한 내용은 Cloud Source Repositories 알림을 참조하세요.

이벤트 페이로드 루트를 나타내는 지정된 프리픽스를 사용하여 이벤트 페이로드의 정보에 액세스할 수 있습니다. 프리픽스로 시작하면 JSONPath 구문을 사용하여 페이로드에 액세스하고 여기에서 데이터를 가져올 수 있습니다. 다음 페이로드 프리픽스는 이벤트 유형에 따라 사용할 수 있습니다.

프리픽스	소스	설명
`push`	GitHub	push 이벤트에 대해 JSON 페이로드 내에 있는 필드에 액세스할 수 있습니다.
`pull_request`	GitHub	pull 요청 이벤트에 대해 JSON 페이로드 내에 있는 필드에 액세스할 수 있습니다.
`issue_comment`	GitHub	pull 요청과 연결된 문제 주석 이벤트에 대해 JSON 페이로드 내에 있는 필드에 액세스할 수 있습니다.
`csr`	Cloud Source Repositories	push 이벤트에 대해 JSON 페이로드 내에 있는 필드에 액세스할 수 있습니다.

GitHub 앱과 연결된 모든 이벤트에 대해서는 기본 제공되는 변수 값 is_collaborator 및 perm_level도 사용할 수 있습니다. 사용자 상태는 push 및 pull 이벤트에 대해 push.pusher.name, pull_request.pull_request.user.login, issue_comment.comment.user.login 변수 값을 사용하여 확인됩니다. 다음 표에서는 소스 코드가 GitHub에 있을 때 이를 트리거의 변수 값으로 포함하는 방법을 보여줍니다.

변수 이름	변수 값	변수 설명
`_PERM_LEVEL`	`$(perm_level)`	사용자의 권한 수준을 가져옵니다.
`_IS_COLLABORATOR`	`$(is_collaborator)`	사용자가 공동작업자인 경우 `true`를 출력합니다.

push 이벤트, pull 요청 이벤트, 댓글로 제어되는 pull 요청 이벤트에 대해 변수 값 is_collaborator 및 perm_level을 사용할 수 있습니다. 이러한 변수 값은 앞에 프리픽스를 추가할 필요가 없습니다.

페이로드 바인딩을 사용하여 대체 항목 만들기

페이로드 바인딩을 사용하는 대체 변수를 만들려면 다음 안내를 따르세요.

트리거 페이지를 엽니다.
빌드 트리거를 만들지 않았으면 트리거 만들기를 클릭합니다. 그렇지 않으면 기존 트리거를 선택합니다.
대체 변수 아래에서 변수 추가를 클릭합니다.
아래 간단히 설명된 규칙에 따라 변수 이름을 추가합니다.
- 대체 항목은 밑줄(_)로 시작하고 대문자 및 숫자만 사용해야 합니다(정규 표현식 [A-Z0-9_]+ 고려). 이렇게 하면 기본 제공 대체 항목과의 충돌을 방지할 수 있습니다.
- 매개변수의 수는 100개로 제한됩니다. 매개변수 키 길이는 100바이트로 제한되고 매개변수 값 길이는 4,000바이트로 제한됩니다.
사용자 정의 대체 항목을 정의하고 사용하는 방법에 대해 자세히 알아보려면 사용자 정의 대체 항목 사용을 참조하세요.

지원되는 프리픽스를 사용하여 변수에 대한 값을 추가합니다.

소스 코드가 GitHub에 있으면 페이로드 바인딩을 사용하는 대체 변수 내에서 이벤트 페이로드의 정보를 참조할 수 있습니다. push 이벤트의 JSON 페이로드에 액세스하려면 push 또는 body 프리픽스를 사용합니다. 다음 예시에서 변수 값의 push 프리픽스는 빌드의 JSON 페이로드 정보에 액세스하기 위한 진입점으로 사용됩니다.

변수 이름	변수 값	변수 설명
`_PUSH_NAME`	`$(push.repository.name)`	push 이벤트와 연결된 저장소의 이름을 가져옵니다.
`_COMMITS`	`$(push.commits)`	각 push된 커밋을 설명하는 커밋 객체의 배열을 가져옵니다.
`_OWNER`	`$(push.repository.owner.name)`	저장소 소유자의 이름을 가져옵니다.
`_URL`	`$(push.repository.html_url)`	GitHub 저장소의 URL을 가져옵니다.
`_LANGUAGE`	`$(push.repository.language)`	push에 포함된 소스 코드의 언어를 가져옵니다.

push 프리픽스를 사용하여 액세스할 수 있는 필드 목록은 PushEvent를 참조하세요.

pull 요청 이벤트의 JSON 페이로드에 액세스하려면 pull_request 또는 body 프리픽스를 사용합니다. 다음 예시에서 변수 값의 pull_request 프리픽스는 빌드의 JSON 페이로드 정보에 액세스하기 위한 진입점으로 사용됩니다.

변수 이름	변수 값	변수 설명
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	pull 요청의 ID를 가져옵니다.
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	pull 요청의 제목을 가져옵니다.
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	pull 요청의 본문을 가져옵니다.
`_USERNAME`	`$(pull_request.pull_request.user.login)`	pull 요청을 보낸 사람의 사용자 이름을 가져옵니다.
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	pull 요청이 병합된 시간을 가져옵니다.

pull_request 프리픽스를 사용하여 액세스할 수 있는 필드 목록은 PullRequestEvent를 참조하세요.

커밋 이벤트의 JSON 페이로드에 액세스하려면 프리픽스 commit를 사용합니다. 다음 예시에서 변수 값의 commit 프리픽스는 빌드의 JSON 페이로드 정보에 액세스하기 위한 진입점으로 사용됩니다.

변수 이름	변수 값	변수 설명
`_COMMIT_URL`	`$(commit.url)`	커밋과 연결된 URL을 가져옵니다.
`_COMMIT_USER`	`$(commit.author.login)`	커밋 작성자의 사용자 이름을 가져옵니다.
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	커밋과 연결된 커밋 메시지를 가져옵니다.
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	커밋과 연결된 날짜를 가져옵니다.
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	커밋에 포함된 파일과 관련된 추가 수를 가져옵니다.

commit 프리픽스를 사용하여 액세스할 수 있는 필드 목록은 커밋 가져오기를 참조하세요.

pull 요청으로 호출된 트리거에 대해 주석 제어를 사용 설정하면, 트리거를 호출하는 이벤트가 대신 IssueCommentEvent이고, 연결된 프리픽스는 issue_comment입니다. 다음 예시에서 변수 값의 issue_comment 프리픽스는 빌드의 JSON 페이로드 정보에 액세스하기 위한 진입점으로 사용됩니다.

변수 이름	변수 값	변수 설명
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	pull 요청의 ID를 가져옵니다.
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	pull 요청의 제목을 가져옵니다.
`_STATE`	`$(issue_comment.state)`	pull 요청의 상태를 가져옵니다(열림, 닫힘 등).
`_LABELS`	`$(issue_comment.issue.labels)`	pull 요청과 연결된 라벨 목록을 가져옵니다.
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	설명과 일치하는 라벨과 연결된 URL을 가져옵니다.

issue_comment 프리픽스를 사용하여 액세스할 수 있는 필드 목록은 IssueCommentEvent를 참조하세요.

프리픽스를 사용합니다.

소스 코드가 Cloud Source Repositories에 있으면 페이로드 바인딩을 사용하는 대체 변수 내에서 이벤트 페이로드의 정보를 참조할 수 있습니다. push 이벤트의 JSON 페이로드에 액세스하려면 csr 또는 body 프리픽스를 사용합니다. 다음 예시에서 변수 값의 csr 프리픽스는 빌드의 JSON 페이로드 정보에 액세스하기 위한 진입점으로 사용됩니다.

변수 이름	변수 값	변수 설명
`_REPO_NAME`	`$(csr.name)`	저장소 이름을 가져옵니다.
`_REPO_URL`	`$(csr.url)`	저장소의 URL을 가져옵니다.
`_CREATED_REPO`	`$(csr.createRepoEvent)`	사용자가 저장소를 만들었는지 여부를 나타냅니다.
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	참조 이름입니다.(예: 'refs/heads/primary-branch')

Cloud Source Repositories에서 액세스할 수 있는 추가 필드를 보려면 알림 데이터를 참조하세요.

bash 매개변수 확장

bash 매개변수 확장을 기본 변수 및 사용자 정의 변수에 적용할 수 있습니다. 지원되는 작업 예시에는 하위 문자열 바꾸기, 문자열 슬라이스, 대문자 표시가 포함됩니다. 예를 들어 기본 변수에서 하위 문자열을 바꾸고 변수를 이미지 태그로 사용할 수 있습니다.

대체 변수로 지정할 수 있는 bash 매개변수 확장은 다음과 같습니다.

bash 확장	설명
`${var}`	`var`에 저장된 문자열 값을 확장합니다.
`${var^}`	문자열에서 첫 번째 문자를 대문자로 표시합니다.
`${var^^}`	문자열의 모든 문자를 대문자로 표시합니다.
`${var,}`	문자열에서 첫 번째 문자를 소문자로 표시합니다.
`${var,,}`	문자열의 모든 문자를 소문자로 표시합니다.
`${var:position}`	문자열에서 처음 `position` 문자를 삭제합니다.
`${var:position:length}`	`position`에 지정된 숫자 값부터 시작해서 문자열을 슬라이스하고 `length`에 지정된 숫자 값까지 포함합니다
`${var/substring/replacement}`	`substring`에 지정된 값의 가장 오른쪽 인스턴스를 `replacement`에 지정된 값으로 바꿉니다.
`${var//substring/replacement}`	`substring`에 지정된 값의 모든 인스턴스를 `replacement`에 지정된 값으로 바꿉니다.
`${var/#substring/replacement}`	`substring`이 `var`의 프리픽스인 경우에만 `substring`에 지정된 값의 첫 번째 인스턴스를 `replacement`에 지정된 값으로 바꿉니다.
`${var/%substring/replacement}`	`substring`이 `var`의 서픽스인 경우에만 `substring`에 지정된 값의 마지막 인스턴스를 `replacement`에 지정된 값으로 바꿉니다.
`${#var}`	문자열의 길이를 검색합니다.
`${var:-default}`	`var`이 이미 정의되지 않은 한 `var`을 `default`로 평가합니다.

다음 bash 매개변수 확장에 일치시킬 패턴을 지정할 수도 있습니다.

bash 확장	설명
`${var#pattern}`	문자열의 왼쪽 측면부터 지정된 `pattern`의 가장 왼쪽 인스턴스까지(포함) 문자를 삭제합니다.
`${var##pattern}`	문자열의 왼쪽 측면부터 지정된 `pattern`의 가장 오른쪽 인스턴스까지(포함) 문자를 삭제합니다.
`${var%pattern}`	문자열의 오른쪽 측면부터 지정된 `pattern`의 첫 번째 인스턴스까지(포함) 문자를 삭제합니다.
`${var%%pattern}`	문자열의 오른쪽 측면부터 지정된 `pattern`의 가장 왼쪽 인스턴스까지(포함) 문자를 삭제합니다.

지정할 수 있는 패턴은 다음과 같습니다.

패턴	설명
`*`	0개 이상의 영숫자 문자와 일치합니다.
`?`	하나의 영숫자 문자와 일치합니다.
`[ccc]`	`a-z` 또는 `0-9` 사이의 범위를 포함하여 `ccc`의 모든 단일 문자와 일치합니다.
`[^c]`	`lo` <= `c` <= `hi`인 문자 범위를 포함하여 `c`에 없는 영숫자 문자와 일치합니다.
`c`	영숫자 문자 `c`와 일치합니다.
`\c`	`*`, `?`, `\`와 같은 영숫자가 아닌 문자를 포함한 모든 문자 `c`와 일치합니다.

bash 매개변수 확장 적용

bash 매개변수 확장을 기본 제공 또는 사용자 정의 대체 변수에 적용하려면 다음 안내를 따르세요.

트리거 페이지를 엽니다.
빌드 트리거를 만들지 않았으면 트리거 만들기를 클릭합니다. 그렇지 않으면 기존 트리거를 선택합니다.
대체 변수 아래에서 변수 추가를 클릭합니다.
아래 간단히 설명된 규칙에 따라 변수 이름을 추가합니다.
- 대체 항목은 밑줄(_)로 시작하고 대문자 및 숫자만 사용해야 합니다(정규 표현식 [A-Z0-9_]+ 고려). 이렇게 하면 기본 제공 대체 항목과의 충돌을 방지할 수 있습니다.
- 매개변수의 수는 100개로 제한됩니다. 매개변수 키 길이는 100바이트로 제한되고 매개변수 값 길이는 4,000바이트로 제한됩니다.
사용자 정의 대체 항목을 정의하고 사용하는 방법에 대해 자세히 알아보려면 사용자 정의 대체 항목 사용을 참조하세요.

변수에 대해 값을 추가하고, 지원되는 bash 매개변수 확장을 기본 제공되는 대체 변수 또는 다른 사용자 정의된 대체 변수에 적용합니다.

다음 예시에서 기본 제공되는 대체 변수 $BRANCH_NAME에는 Feature_Secret_Project_#v2의 기본값이 포함됩니다. 다음 표는 $BRANCH_NAME에 적용할 수 있는 bash 매개변수 확장의 예시를 보여줍니다.

변수 이름	bash 확장	변수 값	설명
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	문자열의 모든 문자를 소문자로 표시합니다.
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	지정된 패턴과 일치하는 문자열의 오른쪽에서 모든 문자를 삭제합니다.
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	첫 번째 밑줄까지 모든 문자를 삭제합니다.
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	모든 밑줄을 대시로 바꿉니다.
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	위에 정의된 `_BRANCH_FOR_IMAGE_NAME` 변수를 사용해서 이미지의 이름을 생성합니다.

_IMAGE_NAME이 위 테이블 my-app-secret-project-prod에 지정된 값으로 트리거에 정의되어 있다고 가정해보세요. 이 값은 이제 빌드 구성 파일에서 _IMAGE_NAME 정의를 재정의합니다. 다음 예시에서는 빌드 트리거가 호출될 때 _IMAGE_NAME(my-app-secret-project-prod)에 지정된 변수 값이 _IMAGE_NAME(test-image)의 기본값을 대체합니다.

YAML

 steps:
 - name: 'gcr.io/cloud-builders/docker'
   args: ['build',
          '-t',
          'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
          '.']
 substitutions:
     _IMAGE_NAME: test-image #default value
 images: [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
 ]
 options:
     dynamicSubstitutions: true

JSON

 {
   'steps': [
     {
       'name': 'gcr.io/cloud-builders/docker',
       'args': [
         'build',
         '-t',
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
         '.'
       ]
     }
   ],
   'substitutions': {
     '_IMAGE_NAME': 'test-image' #default value
   },
   'images': [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
   ],
   "options": {
     "dynamic_substitutions": true
   }
 }

위의 예시에서 true로 설정된 dynamicSubstitutions 필드를 사용하면 bash 매개변수 확장을 해석할 수 있습니다. 빌드가 트리거로 호출되는 경우 dynamicSubstitutions 필드는 항상 true로 설정되며, 빌드 구성 파일에 지정될 필요가 없습니다. 빌드를 수동으로 호출하는 경우 빌드를 실행할 때 bash 매개변수 확장이 해석되도록 dynamicSubstitutions 필드를 true로 설정해야 합니다.

페이로드 바인딩과 함께 bash 매개변수 확장 사용

바인딩이 포함된 변수를 참조하기 위해 새 변수를 만들거나 바인딩을 bash 매개변수 확장과 함께 문자열로 묶어서 페이로드 바인딩과 연결된 변수에 bash 매개변수 확장을 적용할 수 있습니다. 다음 표는 페이로드 바인딩과 함께 bash 매개변수 확장을 사용하는 방법에 대한 예시를 보여줍니다.

변수 이름	변수 값	변수 설명
`_URL`	`$(push.repository.html_url)`	저장소의 URL을 가져옵니다.
`_URL_CAPITAL`	`${_URL^^}`	bash 매개변수 확장을 사용하여 URL의 모든 문자를 대문자로 표시합니다.
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	저장소의 대문자로 표시된 URL에 프리픽스를 추가합니다.
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	저장소 URL과 페이로드ID의 처음 7개 문자가 포함된 애플리케이션 이름을 만듭니다.

다음 단계

변수 값 대체 방법 알아보기
기본 빌드 구성 파일 만들기 방법 알아보기
빌드 트리거 만들기 및 관리 방법 알아보기
수동으로 빌드를 실행하는 방법 알아보기