Como usar vinculações de payload e expansões de parâmetros bash em substituições

Esta página explica como usar vinculações de payload e aplicar expansões de parâmetro bash a variáveis de substituição associadas ao gatilho de compilação. Se você não estiver familiarizado com o uso de variáveis de substituição na configuração da compilação, consulte Como substituir valores de variáveis.

O Cloud Build permite armazenar partes do payload do evento do gatilho como uma variável de substituição. Um payload de evento é o corpo do evento que invoca um gatilho. As variáveis associadas a um payload são chamadas de vinculações e estão disponíveis para builds invocados por eventos de push e pull. As vinculações permitem acessar dados adicionais relacionados ao build, como a linguagem associada ao código-fonte e o autor de uma solicitação de envio.

O Cloud Build também permite que os usuários apliquem expansões de parâmetros bash a valores de variáveis de substituição. As expansões do parâmetro Bash permitem manipular strings associadas a variáveis existentes. É possível manipular strings com letras maiúsculas ou substituir uma substring.

É possível usar vinculações de payload e aplicar expansões de parâmetro bash ao definir ou atualizar um gatilho de compilação no console do Google Cloud e em um arquivo de configuração do Cloud Build. Além disso, você pode aplicar expansões de parâmetros bash ao executar builds manuais.

Vinculações de payload

É possível armazenar partes do payload do evento do gatilho como um valor de variável de substituição. As vinculações de payload estão disponíveis como valores variáveis para builds invocados por eventos push e pull e podem ser usados para acessar o payload JSON quando o código-fonte está nos repositórios do GitHub ou no Cloud Source Repositories. Para saber mais sobre payloads de evento do GitHub, consulte Payloads de evento de webhook. Para saber mais sobre os payloads de eventos do Cloud Source Repositories, consulte Notificações do Cloud Source Repositories.

Você pode acessar informações de um payload de evento usando um prefixo designado, que representa a raiz do payload do evento. Começando com o prefixo, você pode usar a sintaxe JSONPath para acessar o payload e extrair dados dele. Os seguintes prefixos de payload estão disponíveis dependendo do seu tipo de evento:

Prefixo Origem Descrição
push GitHub Permite acessar campos no payload JSON para eventos de push.
pull_request GitHub Permite que você acesse campos dentro de seu payload JSON para eventos de solicitação de envio
issue_comment GitHub Permite acessar campos no payload JSON para emitir eventos de comentário associados a uma solicitação de envio
csr Cloud Source Repositories Permite acessar campos no payload JSON para eventos de push.

Para qualquer evento associado ao aplicativo GitHub, os valores integrados de builds is_collaborator e perm_level também estão disponíveis. O status do usuário é verificado para eventos push e pull pelos valores de variável push.pusher.name, pull_request.pull_request.user.login e issue_comment.comment.user.login. A tabela a seguir mostra como incluí-los como valores de variável do gatilho quando o código-fonte está no GitHub:

Nome da variável Valor da variável Descrição da variável
_PERM_LEVEL $(perm_level) Recebe o nível de permissão do usuário
_IS_COLLABORATOR $(is_collaborator) Gera true se o usuário for um colaborador

Você pode usar os valores de variável is_collaborator e perm_level para eventos push, eventos de solicitação de envio e eventos de solicitação de envio controlados por um comentário. Você não precisa preceder esses valores de variável com um prefixo.

Como criar substituições usando vinculações de payload

Para criar uma variável de substituição que usa uma vinculação de payload:

  1. Abrir a página Gatilhos

  2. Se você não tiver criado um gatilho de versão, clique em Criar gatilho. Caso contrário, selecione um gatilho existente.

  3. Em variáveis de substituição, clique em Adicionar variável.

  4. Adicione um nome para a variável seguindo a convenção descrita abaixo:

    • É obrigatório que as substituições comecem com um sublinhado (_) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular [A-Z0-9_]+). Isso evita conflitos com substituições integradas.

    • O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.

    Para mais informações sobre como definir e usar substituições definidas pelo usuário, consulte Como usar substituições definidas pelo usuário.

  5. Adicione um valor para sua variável, usando um prefixo compatível.

    Se o código-fonte estiver no GitHub, será possível consultar as informações no payload do evento dentro das variáveis de substituição usando vinculações de payload. Para acessar o payload JSON de um evento de push, use o prefixo push ou body. No exemplo a seguir, o prefixo push no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON do build:

    Nome da variável Valor da variável Descrição da variável
    _PUSH_NAME $(push.repository.name) Recebe o nome do repositório associado ao evento push
    _COMMITS $(push.commits) Recebe a matriz de objetos de confirmação que descrevem cada confirmação enviada
    _OWNER $(push.repository.owner.name) Recebe o nome do proprietário do repositório.
    _URL $(push.repository.html_url) Recebe o URL do repositório do GitHub
    _LANGUAGE $(push.repository.language) Recebe o idioma do código-fonte incluído no push.

    Para uma lista de campos que você pode acessar usando o prefixo push, consulte PushEvent.

    Para acessar o payload JSON de um evento de solicitação de envio, use o prefixo pull_request ou body. No exemplo a seguir, o prefixo pull_request no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

    Nome da variável Valor da variável Descrição da variável
    _PULL_REQUEST_ID $(pull_request.pull_request.id) Recebe o ID da solicitação de envio
    _PULL_REQUEST_TITLE $(pull_request.pull_request.title) Recebe o título da solicitação de envio
    _PULL_REQUEST_BODY $(pull_request.pull_request.body) Recebe o corpo da solicitação de envio
    _USERNAME $(pull_request.pull_request.user.login) Recebe o nome de usuário do remetente da solicitação de envio
    _MERGE_TIME $(pull_request.pull_request.merged_at) Recebe o horário em que a solicitação de envio foi mesclada

    Para uma lista de campos que você pode acessar usando o prefixo pull_request, consulte PullRequestEvent.

    Para acessar o payload JSON de um evento de confirmação, use o prefixo commit. No exemplo a seguir, o prefixo commit no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

    Nome da variável Valor da variável Descrição da variável
    _COMMIT_URL $(commit.url) Obtém o URL associado à confirmação
    _COMMIT_USER $(commit.author.login) Obtém o nome de usuário do autor da confirmação
    _COMMIT_MESSAGE $(commit.commit.message) Recebe a mensagem de confirmação associada à confirmação.
    _COMMIT_DATE $(commit.commit.committer.date) Obtém a data associada à confirmação
    _COMMIT_ADDITIONS $(commit.files['*'].additions) Obtém o número de adições associadas a arquivos na confirmação

    Para uma lista de campos que podem ser acessados usando o prefixo commit, consulte Receber uma confirmação.

    Se você ativar Controle de comentários para um gatilho que é invocado por uma solicitação de envio, o evento que invoca o gatilho é um IssueCommentEvent e o prefixo associado é issue_comment. Nos exemplos a seguir, o prefixo issue_comment no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

    Nome da variável Valor da variável Descrição da variável
    _PULL_REQUEST_ID $(issue_comment.issue.id) Recebe o ID da solicitação de envio
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) Recebe o título da solicitação de envio
    _STATE $(issue_comment.state) Recebe o estado da solicitação de envio (ou seja, aberto, fechado etc.)
    _LABELS $(issue_comment.issue.labels) Recebe a lista de rótulos associados à solicitação de envio
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) Recebe o URL associado ao rótulo correspondente à descrição

    Para uma lista de campos que você pode acessar usando o prefixo issue_comment, consulte IssueCommentEvent.

    Se o código-fonte estiver no Cloud Source Repositories, será possível consultar as informações no payload do evento dentro das variáveis de substituição usando as vinculações de payload. Para acessar o payload JSON de um evento de push, use o prefixo csr ou body. No exemplo a seguir, o prefixo csr no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON do build.

    Nome da variável Valor da variável Descrição da variável
    _REPO_NAME $(csr.name) Recebe o nome do seu repositório
    _REPO_URL $(csr.url) Recebe o URL do seu repositório
    _CREATED_REPO $(csr.createRepoEvent) Indica se um usuário criou um repositório.
    _REF_EVENT_NAME $(csr.refUpdateEvent.refUpdates['*'].refName) O nome da referência, como "refs/heads/primary-branch"

    Para ver campos adicionais que você pode acessar no Cloud Source Repositories, consulte Dados de notificação.

Expansões de parâmetros Bash

É possível aplicar expansões de parâmetro bash a variáveis padrão e variáveis definidas pelo usuário. Exemplos de operações compatíveis incluem substituição de substring, fração de strings e capitalização. Por exemplo, é possível substituir uma substring em uma variável padrão e adicioná-la como tag de imagem.

As expansões do parâmetro bash que você pode especificar para variáveis de substituição são as seguintes:

Expansões de intervalo Descrição
${var} Expande o valor da string armazenado em var
${var^} Coloca em letra maiúscula a primeira letra do primeiro caractere na string
${var^^} Coloca em letra maiúscula todos os caracteres na string
${var,} Coloca em letra minúscula o primeiro caractere da string
${var,,} Coloca em letra minúscula todos os caracteres da string
${var:position} Remove os primeiros position caracteres da string
${var:position:length} Corta a string a partir do valor numérico especificado em position e inclui até o valor numérico especificado em length
${var/substring/replacement} Substitui a instância mais à esquerda do valor especificado em substring pelo valor especificado em replacement
${var//substring/replacement} Substitui todas as instâncias do valor especificado em substring pelo valor especificado em replacement
${var/#substring/replacement} Substitui a primeira instância do valor especificado em substring pelo valor especificado em replacement somente se substring for um prefixo de var
${var/%substring/replacement} Substitui a última instância do valor especificado em substring pelo valor especificado em replacement somente se substring for um sufixo de var
${#var} Recupera o comprimento da string
${var:-default} Avalia var como default, a menos que var já esteja definido

Também é possível especificar padrões para corresponder às seguintes expansões de parâmetro bash:

Expansões de intervalo Descrição
${var#pattern} Remove os caracteres do lado esquerdo de uma string até e incluindo a instância mais à esquerda do pattern especificado
${var##pattern} Remove os caracteres do lado esquerdo de uma string até e incluindo a instância mais à direita do pattern especificado
${var%pattern} Remove os caracteres do lado direito de uma string até e incluindo a primeira instância do pattern especificado
${var%%pattern} Remove os caracteres do lado direito de uma string até incluir a instância mais à esquerda de pattern especificado

Os padrões que você pode especificar incluem:

Padrão Descrição
* Corresponde a zero ou mais caracteres alfanuméricos
? Corresponde a qualquer caractere alfanumérico único
[ccc] Corresponde a qualquer caractere em ccc, incluindo intervalos entre a-z e 0-9
[^c] Corresponde a qualquer caractere alfanumérico que não está em c, incluindo um intervalo de caracteres em que lo <= c <= hi
c Corresponde a qualquer caractere alfanumérico c
\c Corresponde a qualquer caractere c, incluindo caracteres não alfanuméricos, como *, ? ou \

Como aplicar expansões de parâmetros bash

Para aplicar expansões de parâmetros bash a uma variável de substituição integrada ou definida pelo usuário:

  1. Abrir a página Gatilhos

  2. Se você não tiver criado um gatilho de versão, clique em Criar gatilho. Caso contrário, selecione um gatilho existente.

  3. Em variáveis de substituição, clique em Adicionar variável.

  4. Adicione um nome para a variável seguindo a convenção descrita abaixo:

    • É obrigatório que as substituições comecem com um sublinhado (_) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular [A-Z0-9_]+). Isso evita conflitos com substituições integradas.

    • O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.

    Para mais informações sobre como definir e usar substituições definidas pelo usuário, consulte Como usar substituições definidas pelo usuário.

  5. Adicione um valor à variável, aplicando uma expansão de parâmetros bash compatível a uma variável de substituição integrada ou a outra variável de substituição definida pelo usuário.

    No exemplo a seguir, a variável de substituição integrada $BRANCH_NAME tem um valor padrão de Feature_Secret_Project_#v2. A tabela a seguir mostra exemplos de expansões de parâmetros bash que você pode aplicar a $BRANCH_NAME:

    Nome da variável Expansão bash Valor da variável Descrição
    _BRANCH_LOWERCASE ${$BRANCH_NAME,,} feature_secret_project_#v2 coloca todos os caracteres da string em letras minúsculas
    _BRANCH_NO_SUFFIX ${_BRANCH_LOWERCASE%_\#v2} feature_secret_project Exclui todos os caracteres do lado direito da string que corresponde ao padrão especificado
    _BRANCH_NO_PREFIX ${_BRANCH_NO_SUFFIX#*_} secret_project exclui todos os caracteres até o primeiro sublinhado
    _BRANCH_FOR_IMAGE_NAME ${_BRANCH_NO_PREFIX//_/-} secret-project substitui todos os sublinhados por um traço;
    _IMAGE_NAME my-app-${_BRANCH_FOR_IMAGE_NAME}-prod my-app-secret-project-prod constrói o nome da imagem usando a variável _BRANCH_FOR_IMAGE_NAME definida acima

    Digamos que _IMAGE_NAME seja definido no seu gatilho como o valor especificado na tabela acima, my-app-secret-project-prod. Esse valor agora substituirá qualquer definição de _IMAGE_NAME no arquivo de configuração da compilação. No exemplo a seguir, o valor da variável especificada para _IMAGE_NAME (my-app-secret-project-prod) substitui o valor padrão de _IMAGE_NAME (test-image) quando o gatilho de compilação é invocado.

    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
       }
     }
    

O campo dynamicSubstitutions, definido como true no exemplo acima, permite que as expansões de parâmetros bash sejam interpretadas. Se o build for invocado por um gatilho, o campo dynamicSubstitutions será sempre definido como true e não precisará ser especificado no arquivo de configuração da compilação. Caso sua versão seja invocada manualmente, defina o campo dynamicSubstitutions como true para que as expansões de parâmetro bash sejam interpretadas ao executar a versão.

Como usar expansões de parâmetros bash com vinculações de payload

É possível aplicar expansões de parâmetros bash a variáveis associadas a vinculações de payload ao criar uma nova variável para fazer referência à variável que contém a vinculação ou ao vincular vinculações com expansões de parâmetro bash. A tabela a seguir lista exemplos de como usar a expansão de parâmetro bash com vinculações de payload:

Nome da variável Valor da variável Descrição da variável
_URL $(push.repository.html_url) Recebe o URL do repositório
_URL_CAPITAL ${_URL^^} Usa uma expansão de parâmetro bash para colocar todos os caracteres do URL em maiúsculas.
_APP_NAME my-app-${_URL_CAPITAL} Adiciona um prefixo ao URL em letras maiúsculas do repositório
APP_NAME_ID my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} Cria um nome de aplicativo que inclui o URL do repositório e os sete primeiros caracteres do ID do payload.

A seguir