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âmetros bash ao definir ou atualizar um gatilho de build 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, é possível 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 está no GitHub, você pode consultar as informações na sua payload de evento nas 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 abaixo, o prefixo push 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
   _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, consulte do payload do evento nas variáveis de substituição usando 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 da sua versão.

   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 quiser substituir uma substring em uma variável padrão e usar a variável como uma 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 em letra minúscula todos os caracteres na string
   _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

• Saiba como substituir valores variáveis.
• Saiba como criar um arquivo de configuração de compilação básico.
• Saiba como criar e gerenciar gatilhos de compilação.
• Saiba como executar builds manualmente.