Criar e gerenciar gatilhos de compilação

Um gatilho do Cloud Build inicia automaticamente um build sempre que você faz qualquer alteração no código-fonte. É possível configurar o gatilho para criar o código em qualquer alteração no repositório de origem ou somente alterações que correspondam a determinados critérios.

Nesta página, explicamos como se conectar a repositórios de origem, como o GitHub e o Bitbucket, e criar gatilhos de build para criar o código nos repositórios.

Antes de começar

• Ative a API Cloud Build.

  Ative a API

• É necessário ter o papel Editor do Cloud Build (roles/cloudbuild.builds.editor) no projeto para criar gatilhos.
• Você precisa do código-fonte no Cloud Source Repositories, no GitHub ou no Bitbucket.
• Você precisa de um Dockerfile ou um arquivo de configuração do Cloud Build.

Como se conectar a repositórios de origem

Primeiro, é preciso conectar o Cloud Build ao repositório de origem antes de compilar o código nesse repositório. Por padrão, seus repositórios no Cloud Source Repositories estão conectados ao Cloud Build. É possível criar acionadores diretamente para seus repositórios no Cloud Source Repositories sem se conectar manualmente a eles.

Se você estiver conectando um repositório externo, como um hospedado no GitHub ou no Bitbucket, precisará de permissões de nível de administrador no repositório para conectar inicialmente seu repositório ao Cloud Build. As permissões de administrador não são necessárias para criar gatilhos em um repositório já conectado ao Cloud Build.

Conclua as etapas a seguir para se conectar ao GitHub ou ao Bitbucket:

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página "Gatilhos"

2. Selecione o projeto e clique em Abrir.

3. Selecione a região em que você quer criar o gatilho no menu suspenso Região.

   Observação: se você selecionar global como sua região, os pools padrão serão usados para executar seu build. Caso contrário, um pool particular na região do gatilho será usado para executar a compilação. Você precisa especificar o pool particular no arquivo de configuração do build ou usando argumentos de build.

4. Clique em Conectar repositório.

5. Selecione o repositório em que você armazenou seu código-fonte.

   Se você selecionar GitHub (espelhado) ou Bitbucket (espelhado) como o repositório de origem, o Cloud Build espelhará esse repositório no Cloud Source Repositories e usará o repositório espelhado em todas as operações.

6. Clique em Continuar.

7. Autentique o repositório de origem com seu nome de usuário e senha.

8. Na lista de repositórios disponíveis, selecione o repositório que você quer e clique em Conectar.

   Para repositórios externos, como GitHub e Bitbucket, você precisa de permissões de nível de proprietário para o projeto do Google Cloud em que está trabalhando.

9. Clique em Criar gatilho para continuar criando um gatilho de build para automatizar builds para o código-fonte no repositório ou clique em Concluído.

Como criar um gatilho de versão

Console

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página Acionadores

2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

3. Clique em Abrir.

4. Clique em Criar gatilho.

5. Preencha as configurações de gatilho a seguir:

   • Nome: insira um nome para o gatilho.

   • Região: selecione a região do gatilho.

     Se o arquivo de configuração de versão associado ao seu gatilho especificar um pool particular, a região selecionada para o gatilho precisa corresponder à região desse pool.

     Se você selecionar global como sua região, o Cloud Build usará a região especificada no arquivo de configuração da versão para executar a versão. Pode ser a região do pool particular, se você especificar um pool particular no arquivo de configuração da versão, ou o pool padrão global, se não especificar um pool particular.

   • Descrição (opcional): insira uma descrição para o gatilho.

   • Evento: selecione o evento de repositório para invocar seu gatilho.

     • Enviar para uma ramificação: defina o gatilho para iniciar um build em confirmações de uma ramificação específica.

     • Enviar nova tag por push: configure o gatilho para iniciar um build em confirmações que contenham uma tag específica.

     • Solicitação de envio: configure o gatilho para iniciar uma compilação após confirmações em uma solicitação de envio.

       Observação :com base em confirmações de ramificação ou de tag, os builds são invocados apenas em envios à origem remota, e não em alterações locais, pré-envios ou solicitações de envio.

   • Origem: selecione 1a geração ou 2a geração como sua origem. Só é possível conectar repositórios do GitHub e do GitHub Enterprise ao selecionar a 2a geração como origem. Para saber mais, consulte os repositórios do Cloud Build.

     Observação: a região do seu repositório precisa corresponder à região do seu gatilho. Se a origem for um Cloud Source Repository, o repositório não estará conectado a uma região específica, mas ao projeto.
     • Repositório: na lista de repositórios disponíveis, selecione o repositório que você quer. Para conectar um novo repositório, consulte Como se conectar a repositórios de origem.
     Observação: se você renomear seu repositório após a criação do gatilho, será necessário atualizar manualmente o nome do repositório no gatilho. Atualmente, o Cloud Build não redireciona automaticamente solicitações de versão do seu gatilho se um nome de repositório for atualizado.

     • Ramificação ou Tag: especifique uma expressão regular correspondente ao valor da ramificação ou da tag. Não é possível usar barras (/) nas tags. Para mais informações sobre a sintaxe aceitável da expressão regular, consulte Sintaxe de RE2 (em inglês).

       Quando a versão é executada, o Cloud Build copia o conteúdo do repositório para /workspace, o diretório de trabalho padrão do Cloud Build. Saiba mais sobre diretórios de trabalho na página de visão geral da configuração da versão.

       Para permitir apenas builds de origens específicas, defina uma política da organização para integrações permitidas (constraints/cloudbuild.allowedIntegrations) para negar a interação com a fonte definida no seu gatilho. A política da organização substitui o acionador e sua versão não é executada. Para saber mais, consulte O portão cria na política da organização para seu projeto.

   • Arquivos incluídos (opcional): as alterações que afetam pelo menos um desses arquivos invocarão um build. É possível usar strings de glob para especificar vários arquivos com caracteres curinga. Entre os caracteres curinga aceitáveis estão os caracteres compatíveis com Go Match, ** e alternância.

     Observação: ** é uma versão recursiva de * que corresponde a todos os arquivos e diretórios no diretório selecionado e nos subdiretórios dele. Por exemplo, o padrão src/* corresponderá a src/code.py, mas vai ignorar src/sub/code.py, enquanto src/** corresponderá a ambos.

   • Arquivos ignorados (opcional): as alterações que afetam somente os arquivos ignorados não invocarão um build. É possível usar strings de glob para especificar vários arquivos com caracteres curinga. Entre os caracteres curinga aceitáveis estão os caracteres compatíveis com Go Match, ** e alternância.

     Observação: as strings glob não permitem variáveis de substituição em arquivos incluídos e ignorados.

     Se você especificar um arquivo em Arquivos incluídos e Arquivos ignorados, as alterações nesse arquivo não invocarão uma build. Digamos que você especifique **/README.md em Arquivos ignorados para ignorar README.md em qualquer diretório e especifique src/* em Arquivos incluídos para iniciar uma versão quando houver alterações em qualquer arquivo na pasta src/. Agora, se você fizer uma alteração em src/README.md, o Cloud Build não iniciará uma build. Cada vez que você envia uma alteração à sua origem, o Cloud Build verifica os arquivos alterados para identificar arquivos incluídos e ignorados a fim de determinar se uma versão precisa ser chamada:

     • Se você enviar uma alteração ao seu repositório em um branch atual, o Cloud Build examinará os arquivos alterados entre a confirmação que você acabou de enviar e a confirmação para que o branch apontou anteriormente.
     • Se o repositório for um Cloud Source Repository e você enviar uma alteração para uma ramificação recém-criada, o Cloud Build tratará todos os arquivos no repositório como arquivos alterados.
     • Se você excluir uma ramificação, o Cloud Build não iniciará uma build.
   Observação :Arquivos incluídos e Arquivos ignorados só podem ser especificados se você selecionar Enviar para uma ramificação ou Enviar nova tag como seu Evento.

   • Configuração: selecione o arquivo de configuração do build localizado no seu repositório remoto ou crie um arquivo de configuração do build inline para usar no build.

     • Tipo: selecione o tipo de configuração a ser usado para seu build.
       • Arquivo de configuração do Cloud Build (yaml ou json): use um arquivo de configuração do build na sua configuração.
       • Dockerfile: use um Dockerfile para sua configuração.
       • Buildpacks: use os buildpacks na sua configuração.

     • Local: especifique o local de configuração.

       • Repositório: se o arquivo de configuração estiver no repositório remoto, forneça o local do arquivo de configuração do build, do diretório Dockerfile ou do buildpacks. Se o tipo de configuração do build for um Dockerfile ou um buildpack, você precisará fornecer um nome para a imagem resultante e, opcionalmente, um tempo limite para o seu build. Depois de fornecer o nome da imagem Dockerfile ou do buildpack, você verá uma visualização do comando docker build ou pack que seu build executará.
       • Variáveis de ambiente de pacote (opcional): se você tiver selecionado buildpacks como tipo de configuração, clique em Adicionar variável de ambiente de pacote para especificar os valores e variáveis de ambiente do buildpack. Para saber mais sobre as variáveis de ambiente de buildpack, consulte Variáveis de ambiente.

       • Inline: se você selecionou o arquivo de configuração do Cloud Build (yaml ou json) como opção de configuração, pode especificar a configuração do build inline. Clique em Abrir Editor para gravar seu arquivo de configuração do build no Console do Google Cloud usando a sintaxe YAML ou JSON. Clique em Concluído para salvar a configuração do build.

         Observação: a compatibilidade com a configuração da compilação in-line não está disponível para Dockerfile ou pacotes de criação.

   • Usar pool privado: este campo aparecerá se você tiver selecionado Dockerfile como a opção de Configuração. Marque esta caixa de seleção se estiver executando seu build em um pool particular.

   • Pool particular: se você selecionou Usar pool particular, especifique o nome do recurso do pool particular no formato projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

   • Variáveis de substituição (opcional): se você selecionou o arquivo de configuração do Cloud Build como opção de configuração de build, escolha definir variáveis de substituição específicas do gatilho usando esse campo. Por exemplo, vamos supor que você esteja criando vários gatilhos em que cada um deles implanta seu app em um ambiente específico. É possível especificar que seu app seja implantado em um ambiente em seu arquivo de configuração da compilação e usar esse campo para definir variáveis de substituição especificando em qual ambiente esse gatilho deverá ser implantado. Para informações sobre como especificar valores de substituição em arquivos de configuração da compilação, consulte Como substituir valores de variável.

   • Aprovação (opcional): marque a caixa para exigir a aprovação antes da execução da versão.

   • Conta de serviço: selecione a conta de serviço a ser usada ao invocar seu gatilho. Se você não selecionar uma conta de serviço, a conta de serviço padrão do Cloud Build será usada.

     Observação: somente a conta de serviço especificada no gatilho será usada para builds executados por gatilhos. Se você tiver especificado uma conta de serviço na configuração da sua versão, ela será ignorada durante a execução da versão ao usar acionadores.

6. Clique em Criar para salvar o gatilho de compilação.

gcloud

Para criar um gatilho se seu código-fonte estiver no 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

Em que:

• REPO_NAME é o nome do repositório;
• BRANCH_PATTERN é o nome da ramificação no seu repositório para invocar a criação.
• TAG_PATTERN é o nome da tag no repositório para invocar o build.

• BUILD_CONFIG_FILE é o caminho para seu arquivo de configuração da compilação.

• SERVICE_ACCOUNT é o e-mail associado à conta de serviço. Se você não incluir essa sinalização, a conta de serviço padrão do Cloud Build será usada.

Observação: somente a conta de serviço especificada no comando gcloud builds triggers create é usada para builds invocados com gatilhos. Os acionadores de versão ignoram a conta de serviço especificada no arquivo de configuração da versão.

• [Opcional] --require-approval é a sinalização a ser incluída para configurar o gatilho para exigir aprovação.

Para uma lista completa de sinalizações, consulte a referência de gcloud sobre como criar gatilhos para o Cloud Source Repositories.

Para criar um gatilho se seu código-fonte estiver no 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

Em que:

• REGION é a região do gatilho.
• REPO_NAME é o nome do repositório;
• REPO_OWNER é o nome de usuário do proprietário do repositório.
• BRANCH_PATTERN é o nome da ramificação no seu repositório para invocar o build.
• TAG_PATTERN é o nome da tag no repositório para invocar o build.
• BUILD_CONFIG_FILE é o caminho para seu arquivo de configuração da compilação.
• SERVICE_ACCOUNT é o e-mail associado à conta de serviço. Se você não incluir essa sinalização, a conta de serviço padrão do Cloud Build será usada.
• [Opcional] --require-approval é a sinalização a ser incluída para configurar o gatilho para exigir aprovação.
• [Opcional] --include-logs-with-status é uma sinalização que pode ser especificada para mostrar registros de compilação dos repositórios. Essa sinalização é compatível com builds dos repositórios do GitHub e do GitHub Enterprise.

Observação :só é possível usar a sinalização --include-logs-with-status ao criar um gatilho do GitHub ou GitHub Enterprise com gcloud. No momento, o Cloud Build não é compatível com a funcionalidade de criar um gatilho usando o console do Google Cloud.

Para uma lista completa de sinalizações, consulte a referência de gcloud sobre como criar gatilhos para o GitHub.

Depois de executar o comando gcloud para criar um gatilho usando o Cloud Source Repositories ou o GitHub, você verá uma resposta semelhante à seguinte:

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

Observação: o nome do gatilho é gerado automaticamente para você. É possível alterar o nome do gatilho por meio do console do Google Cloud.

Como testar um gatilho de versão

Para testar manualmente um gatilhos de compilação:

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página "Gatilhos"

2. Localize o gatilho na lista e clique em Executar gatilho.

Como ignorar um gatilho de versão

Em alguns casos, convém fazer uma alteração no código-fonte, mas você não quer invocar uma build. Por exemplo, talvez você não queira invocar uma build quando atualizar a documentação ou os arquivos de configuração.

Nessas situações, é possível incluir [skip ci] ou [ci skip] na mensagem de confirmação, e uma build não será invocada.

Se você quiser executar um build nessa confirmação posteriormente, use o botão Executar gatilho na página Gatilhos.

Como incluir o histórico do repositório em uma compilação

Para criar sua fonte em um repositório do Git, o Cloud Build realiza um clone superficial do repositório. Isso significa que apenas a confirmação que iniciou a build foi verificada no espaço de trabalho a ser criado. O Cloud Build não registra nenhuma outra ramificação ou histórico. Isso é feito para aumentar a eficiência. Assim, as versões não precisam esperar para buscar todo o repositório e histórico apenas para criar um único commit.

Se você quiser incluir mais do histórico do seu repositório na versão, adicione uma etapa de versão no seu arquivo de configuração da versão para "desfazer" o clone. Exemplo:

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

Observação: se a origem estiver em um repositório Git privado, você precisará armazenar suas credenciais com segurança usando o Gerenciador de secrets para acessar comandos git como o comando acima para "desfazer" o clone superficial do seu repositório. Para mais instruções, consulte Como acessar repositórios particulares do GitHub.

Para mais informações sobre git fetch, consulte a referência do git (em inglês). Para instruções sobre como gravar um arquivo de configuração da versão ção, consulte Visão geral da configuração da versão.

Como reenviar um build para aprovação

Se o build for rejeitado, é possível reenviá-lo para aprovação seguindo estas etapas no console do Google Cloud:

1. Abra a página Histórico do Cloud Build no console do Google Cloud.

   Abrir a página Histórico do Cloud Build

2. Clique no ID do build que você quer reenviar para aprovação.

3. Clique em Recriar na parte superior da página para reenviar o build para aprovação.

Sua versão será iniciada quando um usuário com permissões aprová-la. Para saber mais sobre as aprovações do Cloud Build, consulte Builds do Gate.

Como atualizar um gatilho de compilação

Console

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página “Gatilhos de compilação”

2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

3. Clique em Abrir.

4. Localize a linha com o acionador que você quer atualizar.

5. Clique no menu (três pontos verticais) localizado na extremidade direita da linha.

6. Selecione Editar.

Observação :é possível atualizar todos os campos associados ao gatilho usando o console do Google Cloud, exceto mostrando os registros do build. Consulte as instruções do gcloud sobre como atualizar um gatilho de compilação para mostrar ou ocultar registros de build de gatilhos do GitHub ou do GitHub Enterprise.

gcloud

Para atualizar um acionador:

1. Exporte o gatilho que você quer atualizar:

    gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Em que:

   • TRIGGER_NAME é o nome do gatilho.
   • EXPORT_PATH é o caminho de arquivo para onde você quer exportar o gatilho. Por exemplo, é possível especificar o caminho do arquivo como examples/trigger.yaml. O nome do arquivo do gatilho precisa ter a extensão .yaml.

2. Abra o arquivo que contém o gatilho exportado.

   Seu arquivo será semelhante ao seguinte:

    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. Edite manualmente seu arquivo para atualizar o acionador.

   Para conferir os campos que você pode adicionar ou remover do acionador, consulte o recurso do acionador.

4. Salve o arquivo.

5. Importe o gatilho:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Em que:

   • IMPORT_PATH é o caminho do arquivo do gatilho que você quer importar.

Seu gatilho de compilação está atualizado.

Como desativar um gatilho de compilação

Console

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página “Gatilhos de compilação”

2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

3. Clique em Abrir.

4. Localize a linha com o gatilho que você quer desativar.

5. Clique no menu (três pontos verticais) localizado na extremidade direita da linha.

6. Selecione Disable.

gcloud

Para desativar um gatilho:

1. Exporte o gatilho que você quer desativar:

    gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Em que:

   • TRIGGER_NAME é o nome do gatilho.
   • EXPORT_PATH é o caminho de arquivo para onde você quer exportar o gatilho. Por exemplo, é possível especificar o caminho do arquivo como examples/trigger.yaml. O nome do arquivo do gatilho precisa ter a extensão .yaml.

2. Abra o arquivo que contém o gatilho exportado.

   Seu arquivo será semelhante ao seguinte:

    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. Adicione o campo disabled ao final do arquivo e defina o valor como True.

    disabled: True
   

4. Salve o arquivo.

5. Importe o gatilho:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Em que:

   • IMPORT_PATH é o caminho do arquivo do gatilho que você quer importar.

O gatilho de compilação agora está desativado.

Observação :a desativação de um acionador usando comandos gcloud pode não funcionar se você não tiver um arquivo de configuração do build associado a ele.

Desativar um gatilho não o exclui. Para excluir um gatilho, consulte Como excluir um gatilho de compilação. Um gatilho pode ser reativado alterando o status para Ativado.

Como excluir um gatilho de compilação

Console

1. Abra a página Gatilhos no console do Google Cloud.

   Abrir a página “Gatilhos de compilação”

2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

3. Clique em Abrir.

4. Localize a linha com o gatilho que você quer excluir.

5. Clique no menu (três pontos verticais) localizado na extremidade direita da linha.

6. Selecione Excluir.

gcloud

Para excluir um gatilho, execute o seguinte comando:

  gcloud builds triggers delete TRIGGER_NAME

Em que:

• TRIGGER_NAME é o nome do gatilho.

Para uma lista completa de sinalizações, consulte a referência de gcloud sobre como excluir gatilhos.

Implicações de segurança dos gatilhos de compilação

Observação: para melhorar a postura de segurança padrão dos projetos, o Cloud Build fará alterações que exigirão que você selecione explicitamente uma conta de serviço ao criar um gatilho em novos projetos. Para mais informações, consulte Alteração na conta de serviço do Cloud Build.

Por padrão, os gatilhos de compilação usam a conta de serviço do Cloud Build para executar builds, o que pode fornecer permissões de tempo de compilação para usuários que usam gatilhos para executar uma compilação. Considere as seguintes implicações de segurança ao usar gatilhos de compilação:

• Um usuário sem acesso ao projeto do Cloud, mas com acesso de gravação ao repositório associado aos gatilhos de compilação no projeto, terá permissões para alterar o código que está sendo criado.
• Se você estiver usando os gatilhos de solicitação de pull do GitHub, qualquer usuário com acesso de leitura ao repositório poderá enviar uma solicitação de pull, que pode executar um build que inclua alterações no código na solicitação de envio. Para saber como desativar esse comportamento para gatilhos de solicitação pull do GitHub, consulte Como criar gatilhos do GitHub.

É uma boa prática de segurança criar uma conta de serviço apenas com os papéis necessários para o gatilho. Para saber mais, consulte Configurar contas de serviço especificada pelo usuário. Para saber mais sobre a conta de serviço do Cloud Build e as permissões associadas a ela, consulte Conta de serviço do Cloud Build.

A seguir

• Saiba como iniciar builds manualmente ou configurar implantações que exigem invocação manual criando o código manualmente nos repositórios de origem.
• Saiba como criar gatilhos do GitHub.
• Saiba como automatizar builds em resposta a eventos do Pub/Sub.
• Saiba como automatizar builds em resposta a eventos de webhook.
• Saiba como ver os resultados da versão para gatilhos de compilação.
• Saiba como realizar implantações azul-verde no Compute Engine.
• Saiba como resolver erros de build.