Como criar repositórios do GitLab

Nesta página, explicamos como criar no GitLab usando gatilhos de webhook.

Antes de começar

  • Ative as APIs Cloud Build and Secret Manager.

    Ative as APIs

  • Para usar os comandos gcloud nesta página, instale o SDK do Cloud.

Configuração

Antes de criar um gatilho do webhook para a criação no GitLab, você precisará criar uma chave SSH para autenticar sua conexão com o GitLab. Quando você cria um gatilho sem um repositório associado e acessa seu código em um sistema de gerenciamento de código-fonte externo, como o GitLab, precisará recuperar sua chave SSH na configuração da compilação in-line.

Nesta seção, veremos como criar e armazenar sua chave SSH antes de criar um gatilho de webhook.

Como criar uma chave SSH

Para acessar o código no GitLab, você precisará recuperar uma chave SSH na configuração da compilação in-line.

Para criar uma chave SSH:

  1. Abra uma janela de terminal.

  2. Crie um novo diretório chamado working-dir e navegue até ele:

    mkdir working-dir
    cd working-dir
    
  3. Crie uma nova chave SSH do GitLab, em que gitlab.com é o URL do seu repositório GitLab:

    ssh-keygen -t rsa -b 4096 -N '' -C gitlab.com -f id_gitlab
    

    O comando cria uma nova chave SSH no working-dir/id_gitlab sem uma senha para sua chave SSH. O Cloud Build não poderá usar sua chave SSH se ela estiver protegida com uma senha longa.

Como ativar o acesso SSH no GitLab

Você precisará ativar o acesso SSH no GitLab para permitir que os usuários no servidor adicionem as próprias chaves SSH e as usem para proteger operações Git entre o computador e a instância do GitLab. Para saber como usar o SSH com o GitLab, consulte GitLab e chaves SSH.

Como adicionar sua chave de acesso SSH pública ao GitLab

Para proteger operações realizadas por outros sistemas nos repositórios gerenciados no GitLab, será necessário adicionar sua chave de acesso SSH pública ao GitLab. Para saber como adicionar sua chave, consulte Adicionar uma chave SSH à sua conta do GitLab.

Como criar e armazenar suas credenciais no Secret Manager

Quando você cria uma chave SSH, um arquivo id_gitlab é criado no ambiente local. Como esse arquivo contém informações confidenciais associadas à autenticação, armazene o arquivo no Gerenciador de secrets antes de usá-lo para invocar uma versão.

Além da chave secreta usada ao criar um gatilho de webhook, você também precisará criar uma chave secreta no Gerenciador de secrets para validar e autorizar eventos de webhook de entrada no Cloud Build.

Para criar e armazenar suas credenciais no Gerenciador de secrets:

  1. Acesse a página "Gerenciador de secrets" no Console do Cloud:

    Acessar a página "Gerenciador de secrets"

  2. Na página Gerenciador de secrets, clique em Criar secret.

  3. Na página Criar secret, em Nome, insira um nome para o secret.

  4. No campo Valor do secret, insira um nome para o secret ou faça upload de um arquivo.

    Para fazer upload do arquivo da chave SSH, clique em Fazer upload para incluir o arquivo working-dir/id_gitlab.

  5. Deixe a seção Regiões inalterada.

  6. Clique no botão Criar secret para criá-lo.

Depois de criar seu secret, o Console do Google Cloud concederá automaticamente o papel de Acessador do secret do Secret Manager à sua conta de serviço do Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se você não vir esse papel na sua conta de serviço, conclua as etapas a seguir descritas em Como conceder o papel Secret Manager à sua conta de serviço.

Agora que a chave SSH está armazenada, também é possível excluí-la do ambiente executando o seguinte comando:

rm id_gitlab*

Agora você está pronto para criar seu gatilho do webhook.

Como criar gatilhos de webhook

Console

Para criar um gatilho de webhook que invoque builds do GitLab usando o Console do Google Cloud:

  1. Acesse a página Gatilhos:

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

  2. Selecione seu projeto na parte superior da página e clique em Abrir.

  3. Clique em Criar gatilho.

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

    • Nome: nome do gatilho.
    • Descrição (opcional): uma descrição do gatilho.
    • Evento: selecione Evento de webhook para configurar o gatilho para iniciar builds em resposta a eventos de webhook recebidos.
    • URL do webhook: use o URL do webhook para autenticar eventos de webhook recebidos.

      • Secret: você precisará de um secret para autenticar eventos de webhook recebidos. É possível criar um novo secret ou usar um existente.

        Para criar um novo secret:

        1. Selecione Criar novo.
        2. Clique em Criar secret.

          Você verá a caixa pop-up Criar um secret do webhook.

        3. No campo Nome do secret, insira um nome para o secret.

        4. Clique em Criar secret para salvar seu secret, que será criado e armazenado automaticamente para você no Secret Manager.

        Para usar um secret existente:

        1. Selecione Usar existente.
        2. No campo Secret, selecione o nome do secret que você quer usar no menu suspenso ou siga as instruções para adicionar um secret por ID do recurso.
        3. No campo Versão do secret, selecione sua versão do secret no menu suspenso.

        Se você usar um secret existente, talvez seja necessário conceder manualmente o papel de acessador do secret do Secret Manager à sua conta de serviço do Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Para saber mais, consulte Como conceder o papel de Secret Manager à conta de serviço.

      Depois de criar ou selecionar o secret, você verá uma visualização do URL do webhook. O URL vai conter uma chave de API gerada pelo Cloud Build e o secret. Se o Cloud Build for incapaz de recuperar a chave de API, será possível adicioná-la manualmente ao URL ou aprender a conseguir uma chave de API se você não tiver uma ainda.

      É possível usar o URL para invocar um evento de webhook fazendo uma solicitação HTTP com o método POST.

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

      Para saber como você pode usar o URL ao criar um webhook no GitLab, consulte Como criar um webhook no GitLab (em inglês).

    • Origem (opcional): o repositório a ser criado quando o gatilho do webhook é executado. Deixe esse campo em branco. Neste exemplo, a configuração da compilação é uma configuração de compilação in-line, portanto, uma origem não é necessária.

    • Configuração: crie uma configuração de build in-line no Console do Google Cloud.

      No exemplo a seguir, a configuração da compilação in-line autentica a conexão com o GitLab usando a chave SSH e acessa o repositório especificado. Em seguida, ele verifica a confirmação que invocou o webhook.

      steps:
      # first, setup SSH:
      # 1- save the SSH key from Secret Manager to a file
      # 2- add the host key to the known_hosts file
      - name: gcr.io/cloud-builders/git
        args:
          - '-c'
          - |
            echo "$$SSHKEY" > /root/.ssh/id_rsa
            chmod 400 /root/.ssh/id_rsa
            ssh-keyscan gitlab.com > /root/.ssh/known_hosts
        entrypoint: bash
        secretEnv:
          - SSHKEY
        volumes:
          - name: ssh
            path: /root/.ssh
      # second, clone the repository
      - name: gcr.io/cloud-builders/git
        args:
          - clone
          - '-n'
          - 'git@gitlab.com/GITLAB_REPO'
          - .
        volumes:
          - name: ssh
            path: /root/.ssh
      # third, checkout the specific commit that invoked this build
      - name: gcr.io/cloud-builders/git
        args:
          - checkout
          - $_TO_SHA
      availableSecrets:
        secretManager:
        - versionName: PATH_TO_SECRET_VERSION
          env: SSHKEY
      

      Em que:

      • GITLAB_REPO é o caminho para o repo do GitLab.
      • PATH_TO_SECRET_VERSION é o caminho para a versão do secret, conforme armazenado no Secret Manager. Esse é o secret que contém sua chave SSH. Por exemplo, projects/project-id/secrets/secret-name/versions/1
      • SSHKEY é o nome do ambiente usado nesse caso para armazenar o caminho para o secret.
    • Substituições (opcional): é possível escolher definir variáveis de substituição específicas do gatilho usando esse campo.

      Neste exemplo, digamos que você queira observar um nome de branch específico associado a um ID de commit e, em seguida, alternar para esse nome de branch na definição do build. Para receber esses dados, crie variáveis de substituição usando vinculações de payload para salvar o nome da ramificação.

      Especifique as seguintes variáveis e valores:

      Nome da variável Valor da variável
      _BRANCH $(body.ref)
      _TO_SHA $(body.after)

      Para ver o payload associado aos eventos do GitLab, consulte a página de documentação do GitLab em Eventos.

    • Filtros (opcional): é possível criar uma regra em um gatilho que determina se o gatilho executará um build com base nas variáveis de substituição.

      Como você quer que o gatilho execute uma versão se o nome da ramificação corresponder a main, use o operador "==" para verificar correspondências exatas. Você também pode usar a palavra-chave "corresponde" se quiser fazer a correspondência por expressão regular.

      Especifique o seguinte como seus filtros:

      • _BRANCH == refs/heads/main

      Para ver mais exemplos de sintaxe de filtragem que podem ser aplicados aos seus gatilhos de webhook, consulte Como usar a CEL para filtrar eventos de compilação.

  5. Clique em Criar para criar seu gatilho de compilação.

gcloud

Para criar um gatilho de webhook que invoca builds do GitLab:

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --substitutions=''
       --filter=''
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --branch=BRANCH_NAME # --tag=TAG_NAME

Em que:

  • TRIGGER_NAME é o nome do gatilho.
  • PATH_TO_REPO é o caminho para invocar o build no repositório. Por exemplo, https://www.github.com/owner/repo.
  • PATH_TO_SECRET é o caminho para o secret, conforme armazenado no Secret Manager. Por exemplo, projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG é o caminho para sua configuração de compilação in-line.

  • BRANCH_NAME é o nome da ramificação, caso você queira que o gatilho seja criado em uma ramificação.

  • TAG_NAME é o nome da tag, se você quiser definir o gatilho para criação em uma tag.

Como criar um webhook no GitLab

Para fazer solicitações ao Cloud Build para o GitLab, você precisará criar um webhook no GitLab seguindo as instruções descritas na documentação do GitLab para Webhooks (em inglês).

Agora, sempre que as atualizações do repositório corresponderem ao evento do gatilho especificado no webhook, uma versão será invocada automaticamente pelos gatilhos do webhook do Cloud Build.

A seguir