Conectar ao Cloud Build

Nesta página, detalhamos como invocar builds automaticamente do Secure Source Manager usando arquivos de configuração do Cloud Build e um arquivo YAML de gatilhos no seu repositório do Secure Source Manager.

Antes de começar

  1. Crie uma instância do Secure Source Manager.
  2. Crie um repositório do Secure Source Manager.
  3. Configure uma conta de serviço especificada pelo usuário do Cloud Build.

Funções exigidas

Para receber as permissões necessárias para conectar um repositório do Secure Source Manager ao Cloud Build, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para informações sobre como conceder papéis do Secure Source Manager, consulte Controle de acesso com o IAM e Conceder acesso à instância aos usuários.

Papéis necessários da conta de serviço

Para criar builds e receber o status deles no Cloud Build, conceda ao agente de serviço do Secure Source Manager (service-PROJECT-NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com) os seguintes papéis do Identity and Access Management (IAM):

  • Papel de Editor do Cloud Build (roles/cloudbuild.builds.editor) no projeto em que você ativou o Cloud Build.
  • O papel Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço do Cloud Build ou no projeto em que a conta de serviço do Cloud Build foi criada.
  • Se o projeto em que você ativou o Cloud Build for diferente do projeto em que o Secure Source Manager está ativado, conceda o papel Consumidor do uso de serviços (roles/serviceusage.serviceUsageConsumer) no projeto do Cloud Build.
  • Se os builds estiverem sendo executados em pools de workers, conceda à conta de serviço do Secure Source Manager o papel de Usuário do WorkerPool do Cloud Build (roles/cloudbuild.workerPoolUser) no projeto do Cloud Build.

Para permitir que o Cloud Build leia do seu repositório do Secure Source Manager, conceda à conta de serviço do Cloud Build os seguintes papéis do IAM:

Dependendo do seu caso de uso, a conta de serviço do Cloud Build pode precisar de outros papéis do IAM para executar builds, por exemplo:

  • Para armazenar registros de build no Cloud Logging, conceda o papel de Gravador de registros à conta de serviço do Cloud Build.
  • Para acessar os secrets no Secret Manager, conceda o papel de Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) à conta de serviço do Cloud Build.

Para saber como conceder papéis do IAM a um agente de serviço, consulte Conceder ou revogar um único papel.

Para informações sobre registros de build, consulte Configurar registros de build.

Criar um arquivo de configuração do build

Um arquivo de configuração da build define os campos necessários para o Cloud Build executar suas tarefas de build. É possível gravar o arquivo de configuração de build usando a sintaxe YAML.

É possível criar arquivos de configuração de build nas ramificações que você quer usar para criar.

Para criar um arquivo de configuração de build, faça o seguinte:

  1. Na interface da Web do Secure Source Manager, selecione o repositório que você quer conectar ao Cloud Build.
  2. Selecione a ramificação que você quer criar usando o Cloud Build.

  3. Crie um arquivo de configuração do build. Para saber como criar arquivos de configuração de build, siga as instruções em criar um arquivo de configuração de build.

  4. Confirme as mudanças na ramificação.

Criar um arquivo de acionadores

O arquivo de configuração de gatilhos precisa ser criado na ramificação padrão do repositório.

Para criar um arquivo de configuração de gatilhos:

  1. No repositório local ou na interface da Web do Secure Source Manager, mude para a ramificação padrão.

  2. Crie um arquivo chamado .cloudbuild/triggers.yaml.

  3. Configure o acionador no arquivo .cloudbuild/triggers.yaml:

    triggers:
- name: TRIGGER_NAME
  project: PROJECT_ID
  configFilePath: CLOUD_BUILD_CONFIG_PATH
  eventType: EVENT_TYPE
  ignoredGitRefs: IGNORED_GIT_REFS
  includedGitRefs: INCLUDED_GIT_REFS
  serviceAccount: SERVICE_ACCOUNT
  includedFiles: INCLUDED_FILES
  ignoredFiles: IGNORED_FILES
  disabled: DISABLED_BOOL
  substitutions:
    _VARIABLE_NAME: VARIABLE_VALUE
    OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE

    Substitua:

    • TRIGGER_NAME com um nome para o gatilho. Os nomes de gatilho podem conter apenas caracteres alfanuméricos e traços, e não podem começar ou terminar com um traço. É preciso que os nomes dos gatilhos tenham menos de 64 caracteres.
    • PROJECT_ID pelo ID do projeto em que você ativou o Cloud Build. Google Cloud Este campo é opcional. O padrão é o projeto do Secure Source Manager.
    • CLOUD_BUILD_CONFIG_PATH com o caminho para o arquivo de configuração do Cloud Build que você quer usar para esse gatilho. Este campo é opcional. O valor padrão é .cloudbuild/cloudbuild.yaml

    • EVENT_TYPE com o tipo de evento que você quer usar para acionar o build. As opções são:

      • push para acionar o envio para os branches especificados
      • pull_request para acionar uma solicitação de envio para as ramificações especificadas

      Este campo é opcional. O valor padrão é push.

    • INCLUDED_GIT_REFS com um formato de expressão regular RE2 opcional que corresponde às referências do Git que você quer usar para acionar um build. O valor padrão é vazio. Um valor vazio indica que não há restrições.

    • IGNORED_GIT_REFS com uma expressão regular opcional usando o formato de expressão regular RE2 que corresponde às referências do Git que você não quer acionar um build. O valor padrão é vazio. Um valor vazio indica que não há restrições. O campo ignoredGitRefs é verificado antes do campo includedGitRefs. Para mais informações sobre esses campos, consulte Esquema do arquivo de acionadores.

    • SERVICE_ACCOUNT com a conta de serviço do Cloud Build a ser usada para o build no formato projects/PROJECT_ID/serviceAccounts/ACCOUNT. Substitua ACCOUNT pelo endereço de e-mail ou ID exclusivo da conta de serviço. Como prática recomendada, configure uma conta de serviço especificada pelo usuário. A conta de serviço legada do Cloud Build não pode ser usada devido às limitações dela.

    • INCLUDED_FILES com uma expressão regular opcional no formato RE2 que corresponda aos arquivos que você quer usar para acionar um build.

      Se algum dos arquivos mudados não corresponder ao campo de filtro ignoredFiles e corresponder ao campo de filtro includedFiles, uma build será acionada. O valor padrão é vazio. Um valor vazio indica que não há restrições.

    • IGNORED_FILES com uma expressão regular opcional no formato RE2 que corresponda aos arquivos que você não quer usar para acionar um build.

      Se todos os arquivos alterados em um commit corresponderem a esse campo de filtro, uma build não será acionada. O valor padrão é vazio. Um valor vazio indica que não há restrições.

    • DISABLED_BOOL com true para desativar o gatilho ou false para ativar o gatilho. Este campo é opcional. O valor padrão é false.

    • VARIABLE_NAME com o nome de uma variável que você quer introduzir no arquivo de gatilhos.

    • VARIABLE_VALUE com o valor da variável.

    • OVERRIDE_VARIABLE_NAME com o nome da variável de substituição padrão do Secure Source Manager. Para informações sobre as variáveis de substituição padrão disponíveis, consulte a seção de substituições do Esquema de arquivo de acionadores.

    • OVERRIDE_VARIABLE_VALUE com o valor que você quer usar para substituir o valor padrão da variável de substituição padrão.

  4. Faça commit do arquivo de configuração do acionador na ramificação padrão.

    Depois que o arquivo de gatilhos é confirmado, o Secure Source Manager aciona builds com base na configuração do arquivo de gatilhos.

    O Secure Source Manager lê os arquivos de configuração e o SHA de commit ou a referência Git associada dos seguintes tipos de eventos:

    • Para eventos push, o Secure Source Manager lê o SHA do commit ou a referência do Git quando o push é concluído.
    • Para eventos pull_request, o Secure Source Manager lê o SHA de commit ou a referência do Git quando as mudanças da solicitação de envio são extraídas.

Ver o status do build

Quando um build é acionado por um evento de solicitação push ou pull, o status do commit e do build é exibido na interface da Web do Secure Source Manager.

Os valores possíveis para o status do build são os seguintes:

  • sucessoSUCCESS: o build foi concluído com sucesso.
  • avisoAVISO: ocorreu um problema ao tentar criar.
  • falhaFAILURE: a criação falhou durante a execução.

É possível impedir que commits com builds sem êxito sejam mesclados em ramificações importantes se você configurar uma regra de proteção de ramificação para exigir uma verificação de status bem-sucedida de acionadores configurados no arquivo de acionadores. Para saber mais sobre a proteção de ramificações, leia a Visão geral da proteção de ramificações.

Para conferir o status do build de um evento de push:

  1. Na interface da Web do Secure Source Manager, navegue até o repositório.

    Se o evento de push mais recente tiver acionado um build, o status será exibido ao lado do SHA do commit. Para ver detalhes sobre esse status, clique nele.

  2. Para conferir o status de builds de commits anteriores, selecione Commits para ver o histórico de commits e clique no status para conferir os detalhes.

Para conferir o status do build de um evento de solicitação de envio:

  1. Na interface da Web do Secure Source Manager, clique em Solicitações de envio.

  2. Clique na solicitação de envio que você quer acessar.

    Se os builds foram acionados pela solicitação de envio, você vai ver uma seção intitulada Todas as verificações foram concluídas ou Algumas verificações informaram avisos.

Resolver problemas

Para encontrar métodos de diagnóstico e resolução de erros do Cloud Build ao se conectar com o Secure Source Manager, consulte O arquivo de gatilhos não aciona o build.

A seguir