Crie e faça a gestão de acionadores de compilação

Um trigger do Cloud Build inicia automaticamente uma compilação sempre que faz alterações ao seu código-fonte. Pode configurar o acionador para criar o seu código em quaisquer alterações ao repositório de origem ou apenas em alterações que correspondam a determinados critérios.

Esta página explica como estabelecer ligação a repositórios de origem, como o GitHub e o Bitbucket, e criar acionadores de compilação para compilar o código nos repositórios.

Antes de começar

Para receber as autorizações de que precisa para criar e gerir acionadores de compilação, peça ao seu administrador para lhe conceder a função de IAM de editor do Cloud Build (roles/cloudbuild.builds.editor) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Além disso, faça o seguinte:

  • Enable the Cloud Build API.

    Enable the API

Associe repositórios de origem

Primeiro, tem de associar o Cloud Build ao seu repositório de origem antes de criar o código nesse repositório. Os seus repositórios nos Cloud Source Repositories estão ligados ao Cloud Build por predefinição. Pode criar diretamente acionadores para os seus repositórios nos Cloud Source Repositories sem se ligar manualmente a eles.

Se estiver a associar um repositório externo, como um alojado no GitHub ou no Bitbucket, precisa de autorizações ao nível de administrador no repositório para associar inicialmente o repositório ao Cloud Build. As autorizações de administrador não são necessárias para criar acionadores num repositório que já esteja ligado ao Cloud Build.

Conclua os passos seguintes para estabelecer ligação ao GitHub ou ao Bitbucket:

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página de acionadores

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Clique em Associar repositório.

  4. Selecione a região onde quer criar o acionador no menu pendente Região.

  5. Selecione o repositório onde armazenou o código fonte.

    Se selecionar GitHub (espelhado) ou Bitbucket (espelhado) como o seu repositório de origem, o Cloud Build espelha o seu repositório no Cloud Source Repositories e usa o repositório espelhado para todas as suas operações.

  6. Clique em Continuar.

  7. Autentique-se no repositório de origem com o seu nome de utilizador e palavra-passe.

  8. Na lista de repositórios disponíveis, selecione um repositório e, de seguida, clique em Associar.

    Para repositórios externos, como o GitHub e o Bitbucket, tem de ter autorizações ao nível do proprietário para o Google Cloud projeto com o qual está a trabalhar.

  9. Clique em Criar um acionador para continuar a criar um acionador de compilação para automatizar compilações para o código-fonte no repositório ou clique em Concluído.

Crie um acionador de versão

Consola

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página Acionadores

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Clique em Criar acionador.

  4. Introduza as seguintes definições do acionador:

    • Nome: introduza um nome para o acionador.

    • Região: selecione a região para o seu acionador.

      Se o ficheiro de configuração de compilação associado ao acionador especificar um pool privado, a região que selecionar para o acionador tem de corresponder à região do pool privado.

      Se selecionar global como região, o Cloud Build usa a região especificada no ficheiro de configuração da compilação para executar a compilação. Pode ser a região do conjunto privado, se especificar um conjunto privado no ficheiro de configuração de compilação, ou o conjunto predefinido global se não especificar um conjunto privado.

    • Descrição (opcional): introduza uma descrição para o acionador.

    • Evento: selecione o evento do repositório para invocar o acionador.

      • Enviar para um ramo: defina o acionador para iniciar uma compilação em commits para um ramo específico.

      • Enviar nova etiqueta: defina o acionador para iniciar uma compilação em commits que contenham uma etiqueta específica.

      • Pedido de envio: defina o seu acionador para iniciar uma compilação em commits para um pedido de envio.

    • Origem: selecione 1.ª geração ou 2.ª geração como origem. Só pode associar repositórios do GitHub e GitHub Enterprise quando seleciona 2.ª geração como origem. Para saber mais, consulte o artigo Repositórios do Cloud Build.

      • Branch ou Tag: especifique uma expressão regular com o valor da ramificação ou da etiqueta a corresponder. Não é possível usar barras (/) em etiquetas. Para mais informações sobre a sintaxe de expressões regulares aceitável, consulte a sintaxe RE2.

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

        Para permitir apenas compilações de origens específicas, defina uma política organizacional para integrações permitidas (constraints/cloudbuild.allowedIntegrations) para negar a interação com a origem definida no seu acionador. A política da organização substitui o acionador e a sua compilação não é executada. Para saber mais, consulte o artigo O Gate baseia-se na política da organização para o seu projeto.

    • Ficheiros incluídos (opcional): as alterações que afetem, pelo menos, um destes ficheiros vão invocar uma compilação. Pode usar strings globais para especificar vários ficheiros com carateres universais. Os carateres universais aceitáveis incluem os carateres suportados pela função Go Match, ** e alternation.

    • Ficheiros ignorados (opcional): as alterações que afetam apenas ficheiros ignorados não invocam uma compilação. Pode usar strings glob para especificar vários ficheiros com carateres universais. Os carateres universais aceitáveis incluem os carateres suportados por Go Match, ** e alternation.

      Se especificar um ficheiro em Ficheiros incluídos e Ficheiros ignorados, as alterações a esse ficheiro não invocam uma compilação. Suponhamos que especifica **/README.md em Ficheiros ignorados para ignorar README.md em qualquer diretório e especifica src/* em Ficheiros incluídos para iniciar uma compilação em alterações a qualquer ficheiro na pasta src/. Agora, se fizer uma alteração a src/README.md, o Cloud Build não inicia uma compilação. Sempre que envia uma alteração para a sua origem, o Cloud Build procura nos ficheiros alterados ficheiros incluídos e ignorados para determinar se deve ser invocado um processo de compilação:

      • Se enviar uma alteração para o repositório num ramo existente, o Cloud Build analisa os ficheiros alterados entre a confirmação que acabou de enviar e a confirmação para a qual o ramo apontava anteriormente.
      • Se o seu repositório for um Cloud Source Repository e enviar uma alteração para um ramo recém-criado, o Cloud Build trata todos os ficheiros no repositório como ficheiros alterados.
      • Se eliminar um ramo, o Cloud Build não inicia uma compilação.

    • Configuração: selecione o ficheiro de configuração de compilação localizado no seu repositório remoto ou crie um ficheiro de configuração de compilação inline para usar na sua compilação.

      • Tipo: selecione o tipo de configuração a usar para a sua compilação.
        • Ficheiro de configuração do Cloud Build (YAML ou JSON): use um ficheiro de configuração de compilação para a sua configuração.
        • Dockerfile: use um Dockerfile para a sua configuração.
        • Buildpacks: use buildpacks para a sua configuração.

      • Localização: especifique a localização da configuração.

        • Repositório: se o ficheiro de configuração estiver localizado no seu repositório remoto, indique a localização do ficheiro de configuração de compilação, do Dockerfilediretório ou do diretório de pacotes de compilação. Se o seu tipo de configuração de compilação for Dockerfile ou um buildpack, tem de fornecer um nome para a imagem resultante e, opcionalmente, um limite de tempo para a compilação. Quando tiver indicado o nome da imagem Dockerfile ou do buildpack, é apresentada uma pré-visualização do comando docker build ou pack que a sua compilação vai executar.
        • Variáveis de ambiente do buildpack (opcional): se selecionou buildpacks como o tipo de configuração, clique em Adicionar variável de ambiente do pacote para especificar as variáveis de ambiente e os valores do buildpack. Para saber mais acerca das variáveis de ambiente do buildpack, consulte o artigo Variáveis de ambiente.

        • Inline: se selecionou Ficheiro de configuração do Cloud Build (YAML ou JSON) como opção de configuração, pode especificar a configuração de compilação inline. Clique em Abrir editor para escrever o ficheiro de configuração de compilação na Google Cloud consola com a sintaxe YAML ou JSON. Clique em Concluído para guardar a configuração de compilação.

    • Usar pool privado: este campo é apresentado se tiver selecionado Dockerfile como opção de Configuração. Selecione esta caixa de verificação se estiver a executar a compilação num conjunto privado.

    • Piscina privada: se selecionou Usar piscina privada, especifique o nome do recurso da piscina privada do formulário projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

    • Variáveis de substituição (opcional): se selecionou o ficheiro de configuração do Cloud Build como opção de configuração de compilação, pode optar por definir variáveis de substituição específicas do acionador através deste campo. Por exemplo, suponhamos que está a criar vários acionadores em que cada acionador implementa a sua app num ambiente específico. Pode especificar que a sua app é implementada num ambiente no ficheiro de configuração de compilação e, em seguida, usar este campo para definir variáveis de substituição que especificam o ambiente para o qual este acionador deve ser implementado. Para obter informações sobre como especificar valores de substituição em ficheiros de configuração de compilação, consulte o artigo Substituir valores de variáveis.

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

    • Conta de serviço: selecione a conta de serviço a usar quando invocar o acionador. Apenas a conta de serviço especificada no seu acionador é usada para compilações executadas por acionadores. Se especificou uma conta de serviço na configuração de compilação, esta é ignorada durante a execução da compilação quando usa acionadores.

  5. Clique em Criar para guardar o acionador de compilação.

gcloud

Para criar um acionador se o seu código-fonte estiver nos 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

Onde:

  • REPO_NAME é o nome do seu repositório.
  • BRANCH_PATTERN é o nome do ramo no seu repositório para invocar a compilação.
  • TAG_PATTERN é o nome da etiqueta no seu repositório para invocar a compilação.
  • BUILD_CONFIG_FILE é o caminho para o ficheiro de configuração de compilação.
  • SERVICE_ACCOUNT é a conta de serviço a usar para operações de acionamento e compilação.
  • Opcional: para configurar o acionador de modo a exigir aprovação, defina a flag --require-approval.

Para ver uma lista completa de flags, consulte a referência gcloud sobre como criar acionadores para os Cloud Source Repositories.

Para criar um acionador se o seu código fonte estiver no GitHub:

    gcloud builds triggers create github \
    --name=TRIGGER_NAME \
    --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

Onde:

  • REGION é a região do seu acionador.
  • REPO_NAME é o nome do seu repositório.
  • REPO_OWNER é o nome de utilizador do proprietário do repositório.
  • BRANCH_PATTERN é o nome do ramo no seu repositório para invocar a compilação.
  • TAG_PATTERN é o nome da etiqueta no seu repositório para invocar a compilação.
  • BUILD_CONFIG_FILE é o caminho para o ficheiro de configuração de compilação.
  • SERVICE_ACCOUNT é a conta de serviço a usar para operações de acionamento e compilação.
  • Opcional: --require-approval é a flag a incluir para configurar o acionador de modo a exigir aprovação.
  • Opcional: --include-logs-with-status é uma flag que pode especificar para mostrar os registos de compilação dos seus repositórios. Esta flag é suportada para compilações de repositórios do GitHub e do GitHub Enterprise.

Para ver uma lista completa de flags, consulte a referência gcloud sobre como criar acionadores para o GitHub.

Depois de executar o comando gcloud para criar um acionador através dos Cloud Source Repositories ou do GitHub, deve ver um resultado semelhante ao seguinte:

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

Teste um acionador de versão

Para testar manualmente um acionador de compilação:

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página de acionadores

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Localize o acionador na lista e, de seguida, clique em Executar.

Ignore um acionador de compilação

Em alguns casos, pode querer fazer uma alteração ao código-fonte, mas não quer invocar uma compilação. Por exemplo, pode não querer invocar uma compilação quando atualiza a documentação ou os ficheiros de configuração.

Nestes cenários, pode incluir [skip ci] ou [ci skip] na mensagem de commit e não é invocado um build.

Se quiser executar uma compilação nesse commit mais tarde, use o botão Executar na página Acionadores.

Inclua o histórico do repositório numa compilação

Para compilar a sua origem num repositório Git, o Cloud Build executa uma clonagem superficial do repositório. Isto significa que apenas a confirmação única que iniciou a compilação é extraída no espaço de trabalho para compilar. O Cloud Build não extrai outros ramos nem histórico. Isto é feito por motivos de eficiência, para que as compilações não tenham de esperar para obter todo o repositório e histórico apenas para compilar uma única confirmação.

Se quiser incluir mais do histórico do seu repositório na compilação, adicione um passo de compilação no ficheiro de configuração da compilação para "desfazer" a clonagem superficial. Por exemplo:

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

Para mais informações sobre o git fetch, consulte a referência git. Para ver instruções sobre como escrever um ficheiro de configuração de compilação, consulte o artigo Vista geral da configuração de compilação.

Reenvie uma compilação para aprovação

Se a sua compilação tiver sido rejeitada, pode reenviá-la para aprovação seguindo estes passos na Google Cloud consola:

  1. Abra a página Histórico do Cloud Build na Google Cloud consola.

    Abra a página Histórico do Cloud Build

  2. Clique no ID da compilação que quer reenviar para aprovação.

  3. Clique em Reconstruir na parte superior da página para reenviar a compilação para aprovação.

A compilação é iniciada quando um utilizador com autorizações a aprova. Para saber mais sobre as aprovações do Cloud Build, consulte o artigo Restrinja as compilações com aprovação.

Atualize um acionador de compilação

Consola

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página Acionadores de compilação

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Localize a linha com o acionador que quer atualizar.

  4. Clique no menu (reticências verticais) localizado na extremidade direita da linha.

  5. Selecione Editar.

gcloud

Para atualizar um acionador:

  1. Exporte o acionador que quer atualizar:

     gcloud beta builds triggers export TRIGGER_NAME --destination=EXPORT_PATH

    Onde:

    • TRIGGER_NAME é o nome do acionador.
    • EXPORT_PATH é o caminho para o qual quer exportar o seu acionador. Por exemplo, pode especificar o seu caminho como examples/trigger.yaml. Tenha em atenção que o nome do ficheiro do acionador deve ter a extensão YAML.

  2. Abra o ficheiro que contém o acionador exportado.

    O seu ficheiro terá um aspeto 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 o ficheiro para atualizar o acionador.

    Para ver os campos que pode adicionar ou remover do seu acionador, consulte o recurso trigger.

  4. Guarde o ficheiro.

  5. Importe o acionador:

     gcloud builds triggers import --source=IMPORT_PATH

    Onde:

    • IMPORT_PATH é o caminho do acionador que quer importar.

O seu acionador de compilação está agora atualizado.

Desative um acionador de compilação

Consola

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página Acionadores de compilação

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Localize a linha com o acionador que quer desativar.

  4. Clique no menu (reticências verticais) localizado na extremidade direita da linha.

  5. Selecione Desativar.

gcloud

Para desativar um acionador:

  1. Exporte o acionador que quer desativar:

     gcloud beta builds triggers export TRIGGER_NAME --destination=EXPORT_PATH

    Onde:

    • TRIGGER_NAME é o nome do acionador.
    • EXPORT_PATH é o caminho para o qual quer exportar o acionador. Por exemplo, pode especificar o seu caminho como examples/trigger.yaml. Tenha em atenção que o nome do ficheiro do acionador deve ter a extensão YAML.

  2. Abra o ficheiro que contém o acionador exportado.

    O seu ficheiro terá um aspeto 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 ficheiro e defina o valor como True.

     disabled: True

  4. Guarde o ficheiro.

  5. Importe o acionador:

     gcloud builds triggers import --source=IMPORT_PATH

    Onde:

    • IMPORT_PATH é o caminho do acionador que quer importar.

O seu acionador de compilação está agora desativado.

Desativar um acionador não o elimina. Para eliminar um acionador, consulte o artigo Eliminar um acionador de compilação. Pode reativar um acionador alterando o estado para Ativado.

Elimine um acionador de compilação

Consola

  1. Abra a página Acionadores na Google Cloud consola.

    Abra a página Acionadores de compilação

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto.

  3. Localize a linha com o acionador que quer eliminar.

  4. Clique no menu (reticências verticais) localizado na extremidade direita da linha.

  5. Selecione Eliminar.

gcloud

Para eliminar um acionador, execute o seguinte comando:

  gcloud builds triggers delete TRIGGER_NAME

Onde:

  • TRIGGER_NAME é o nome do acionador.

Para ver uma lista completa de flags, consulte a referência gcloud para saber como eliminar acionadores.

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

A conta de serviço configurada para um acionador de compilação pode fornecer autorizações de tempo de compilação elevadas aos utilizadores que usam acionadores para invocar uma compilação. Isto aplica-se à conta de serviço predefinida do Cloud Build e às contas de serviço especificadas pelo utilizador. Tenha em atenção as seguintes implicações de segurança ao usar acionadores de compilação:

  • Um utilizador sem acesso ao seu projeto do Google Cloud, mas com acesso de escrita ao repositório associado a acionadores de compilação no projeto, tem autorizações para alterar o código que está a ser compilado.
  • Se estiver a usar acionadores de pedidos de envio do GitHub, qualquer utilizador com acesso de leitura ao repositório pode enviar um pedido de envio, o que pode executar uma compilação que inclua alterações ao código no pedido de envio. Para saber como desativar este comportamento para acionadores de pedidos de envio do GitHub, consulte o artigo Criar acionadores do GitHub.

Recomendamos que crie uma conta de serviço com apenas as funções necessárias para o seu acionador. Para saber mais, consulte o artigo Configure contas de serviço especificadas pelo utilizador. Para saber mais sobre a conta de serviço predefinida do Cloud Build e as respetivas autorizações associadas, consulte o artigo Conta de serviço do Cloud Build.

O que se segue?