Conectar ao Cloud Build

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

Por padrão, o Secure Source Manager usa um agente de serviço gerenciado pelo Google para interagir com o Cloud Build e outros recursos. Para isolar as permissões da equipe, recomendamos configurar uma identidade por repositório associando uma conta serviço gerenciado pelo usuário ao repositório. O Secure Source Manager usa a conta de serviço gerenciado pelo usuário associada ao repositório para acionar builds.

Ao contrário do agente de serviço padrão, é possível configurar uma conta de serviço gerenciado pelo usuário com a permissão iam.serviceAccounts.actAs em contas de serviço personalizadas do Cloud Build. Isso permite executar builds usando contas de serviço personalizadas, mantendo as permissões de build restritas a esse repositório.

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. Para permitir que o Cloud Build leia do repositório do Secure Source Manager, conceda à conta de serviço do Cloud Build (a conta de serviço padrão ou uma conta de serviço gerenciada pelo usuário) os seguintes papéis:

    • Acessador de instâncias do Secure Source Manager (roles/securesourcemanager.instanceAccessor) na instância do Secure Source Manager.
    • Leitor de repositórios do Secure Source Manager no repositório.

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

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

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

  4. Se os builds forem executados em pools de workers, conceda à conta de serviço gerenciado pelo usuário do repositório o papel Usuário do WorkerPool do Cloud Build (roles/cloudbuild.workerPoolUser) no projeto em que os builds são executados.

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 com 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 de instância aos usuários.

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

Para conectar o Secure Source Manager ao Cloud Build, é necessário configurar as permissões do IAM para uma identidade por repositório.

Configuração de identidade por repositório

Para usar uma identidade por repositório, é necessário configurar permissões.

  1. Usuário: o usuário que configura a conta de serviço do repositório precisa do papel Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço gerenciado pelo usuário. Essa permissão é verificada durante a criação ou atualização do repositório.

  2. Agente de serviço do Secure Source Manager: conceda ao agente de serviço do Secure Source Manager para o projeto do repositório o papel Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta serviço gerenciado pelo usuário.

    O e-mail do agente de serviço do Secure Source Manager tem o formato service-REPOSITORY_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com, em que REPOSITORY_PROJECT_NUMBER é o número do projeto que hospeda o repositório.

  3. Conta serviço gerenciado pelo usuário:

    • Conceda à conta de serviço gerenciado pelo usuário o papel Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada do Cloud Build (no projeto do repositório).
    • Conceda à conta de serviço gerenciado pelo usuário o papel Editor do Cloud Build (roles/cloudbuild.builds.editor) e o papel Consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer) no projeto em que os builds são executados.

Para informações sobre como conceder papéis do IAM, consulte Conceder ou revogar um único papel.

Criar um arquivo de configuração do build

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

É possível criar arquivos de configuração do build no branch ou nos branches em que você quer criar.

Para criar um arquivo de configuração do 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 o branch em que você quer criar usando o Cloud Build.

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

  4. Faça commit das mudanças no branch.

Criar um arquivo de gatilhos

O arquivo de configuração de gatilhos precisa ser criado no branch 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 o branch padrão.

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

  3. Configure o gatilho 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 por um nome para o gatilho. Os nomes de gatilho só podem conter caracteres alfanuméricos e traços, e não podem começar ou terminar com um traço. Os nomes de gatilho precisam ter menos de 64 caracteres.
    • PROJECT_ID pelo Google Cloud ID do projeto em que você ativou o Cloud Build. Este campo é opcional. O padrão é o projeto do Secure Source Manager.
    • CLOUD_BUILD_CONFIG_PATH pelo 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 pelo tipo de evento que você quer acionar o build. As opções são as seguintes:

      • push para acionar o envio para os branches especificados
      • pull_request para acionar uma solicitação de envio para os branches especificados

      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 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 gatilhos.

    • 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. É possível usar a conta de serviço padrão do Cloud Build ou uma conta serviço gerenciado pelo usuário. A conta de serviço legada do Cloud Build não pode ser usada devido às limitações.

    • INCLUDED_FILES com uma expressão regular de formato RE2 opcional que corresponde aos arquivos que você quer acionar um build.

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

    • IGNORED_FILES com uma expressão regular de formato RE2 opcional que corresponde aos arquivos que você não quer acionar um build.

      Se todos os arquivos alterados em um commit corresponderem a esse campo de filtro, um build não será acionado. 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 do arquivo de gatilhos.

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

  4. Faça commit do arquivo de configuração de gatilho no branch 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 associado ou a referência do Git dos seguintes tipos de eventos:

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

Ver o status do build

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

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

  • sucessoSUCESSO: o build foi concluído.
  • avisoAVISO: ocorreu um problema ao tentar criar.
  • falhaFALHA: o build falhou durante a execução.

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

Para ver o status do build de um evento de envio:

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

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

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

Para ver 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 extração.

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

    Se os builds foram acionados pela solicitação de envio, você verá uma seção intitulada either Todas as verificações foram bem-sucedidas, 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 ao Secure Source Manager, consulte O arquivo de gatilhos não aciona o build.

A seguir