Compila repositorios desde GitLab

En esta página, se explica cómo compilar en GitLab mediante activadores de webhook.

Antes de comenzar

  • Habilita las API de Cloud Build and Secret Manager.

    Habilita las API

  • Para usar los comandos de gcloud en esta página, instala la CLI de Google Cloud.

Configuración

Antes de crear un activador de webhook para compilar en GitLab, deberás crear una clave SSH a fin de autenticar tu conexión a GitLab. Cuando creas un activador sin un repositorio asociado y accedes a tu código en un sistema de administración de código fuente externo, como GitLab, debes recuperar tu llave SSH en la configuración de compilación intercalada.

En esta sección, se explica cómo puedes crear y almacenar tu clave SSH antes de crear un activador de webhook.

Crea una clave SSH

Para acceder a tu código en GitLab, deberás recuperar una clave SSH en tu configuración de compilación intercalada.

Para crear una clave SSH, sigue estos pasos:

  1. Abre una ventana de terminal.

  2. Crea un directorio nuevo llamado working-dir y navega hasta él:

    mkdir working-dir
    cd working-dir
    
  3. Crea una clave SSH de GitLab nueva, en la que gitlab.com es la URL de tu repositorio de GitLab:

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

    El comando crea una clave SSH nueva en working-dir/id_gitlab sin una frase de contraseña para tu clave SSH. Cloud Build no puede usar tu clave SSH si está protegida con una frase de contraseña.

Habilita el acceso SSH en GitLab

Deberás habilitar el acceso SSH en tu GitLab para permitir que los usuarios de tu servidor agreguen sus propias claves SSH y usen esas claves SSH a fin de proteger las operaciones de Git entre su computadora y la instancia de GitLab. Para obtener información sobre cómo usar SSH con GitLab, consulta GitLab y las claves SSH.

Agrega tu llave de acceso SSH pública a GitLab

Para proteger las operaciones que realizan otros sistemas en tus repositorios administrados en GitLab, deberás agregar tu clave de acceso SSH pública a GitLab. Para aprender a agregar tu clave, consulta Agrega una llave SSH a tu cuenta de GitLab.

Crea y almacena tus credenciales en Secret Manager

Cuando creas una clave SSH, se crea un archivo id_gitlab en tu entorno. Dado que este archivo contiene información sensible asociada con la autenticación, debes almacenar el archivo en Secret Manager antes de usarlo para invocar una compilación.

Además del secreto que se usa cuando creas un activador de webhook, también deberás crear un secreto en Secret Manager a fin de validar y autorizar los eventos de webhook entrantes en Cloud Build.

Para crear y almacenar tus credenciales en Secret Manager, haz lo siguiente:

  1. Ve a la página Administrador de secretos en la consola:

    Ir a la página Secret Manager

  2. En la página de Secret Manager, haz clic en Crear secreto.

  3. En la página Crear secreto, en Nombre, ingresa un nombre para tu secreto.

  4. En el campo Valor del secreto, ingresa un nombre para tu secreto o sube un archivo.

    Para subir el archivo de claves SSH, haz clic en Subir a fin de incluir el archivo working-dir/id_gitlab.

  5. Deja la sección Regiones sin modificar.

  6. Haz clic en el botón Crear secreto para crear tu secreto.

Después de crear tu secreto, Google Cloud Console otorgará automáticamente la función de Descriptor de acceso de administrador de secretos a tu cuenta de servicio de Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Si no ves esta función en tu cuenta de servicio, completa los siguientes pasos que se describen en Otorga función de Secret Manager a tu cuenta de servicio.

Ahora que almacenaste tu Llave SSH, también puedes borrar la Llave SSH de tu entorno mediante la ejecución del siguiente comando:

rm id_gitlab*

Ya estás listo para crear el activador de webhook.

Crea activadores de webhook

Console

Para crear un activador de webhook que invoque compilaciones desde GitLab con Google Cloud Console, haz lo siguiente:

  1. Abrir la página Activadores:

    Abrir la página Activadores de compilación

  2. Selecciona el proyecto en la parte superior de la página y haz clic en Abrir.

  3. Haz clic en Crear activador.

  4. Ingresa las siguientes opciones de configuración del activador:

    • Nombre: un nombre para tu activador
    • Región: selecciona la región para el activador.

      • Si seleccionas global como la región, Cloud Build usa el grupo predeterminado para ejecutar tu compilación.
      • Si seleccionas una región no global y el archivo de configuración de compilación asociado con el activador especifica un grupo privado, Cloud Build usa el grupo privado para ejecutar tu compilación. En este caso, la región que especifiques en el activador debe coincidir con la región en la que creaste el grupo privado.
      • Si seleccionas una región no global y el archivo de configuración de compilación asociado con el activador no especifica un grupo privado, Cloud Build usa el grupo predeterminado para ejecutar la compilación en la misma región que el activador.
    • Descripción (opcional): Una descripción para tu activador

    • Evento: Selecciona Evento de webhook para configurar tu activador a fin de que inicie compilaciones en respuesta a eventos de webhook entrantes.

    • URL de webhook: Usa la URL de webhook para autenticar los eventos de webhook entrantes.

      • Secret: Necesitarás un secreto para autenticar los eventos de webhook entrantes. Puedes crear un secreto nuevo o usar uno existente.

        Para crear un secreto nuevo, haz lo siguiente:

        1. Seleccione Crear nueva.
        2. Haz clic en Crear Secreto.

          Verás la ventana emergente Crear un secreto de webhook.

        3. En el campo Nombre del secreto, ingresa un nombre para tu secreto.

        4. Haz clic en Crear secreto para guardar el secreto, que se creará y almacenará automáticamente en Secret Manager.

        Para usar un secreto existente, sigue estos pasos:

        1. Selecciona Usar existente.
        2. En el campo Secreto, selecciona el nombre del secreto que deseas usar en el menú desplegable o sigue las instrucciones para agregar un secreto por ID de recurso.
        3. En el campo Versión del secreto, selecciona la versión del secreto en el menú desplegable.

        Si usas un secreto existente, es posible que debas otorgar de forma manual la función de descriptor de acceso a secretos de Secret Manager a tu cuenta de servicio de Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Para obtener más información, consulta Otorga función de Secret Manager a la cuenta de servicio.

      Después de crear o seleccionar tu secreto, verás una vista previa de la URL de webhook. Tu URL contendrá una clave de API generada por Cloud Build y tu secreto. Si Cloud Build no puede recuperar tu clave de API, puedes agregar manualmente tu clave de API a la URL o bien aprender a obtener una clave de API si no la tienes. uno todavía.

      Puedes usar la URL para invocar un evento de webhook mediante una solicitud HTTP con el 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 aprender a usar la URL cuando creas un webhook en GitLab, consulta Crea un webhook en GitLab.

    • Fuente: Es el repositorio que se compilará cuando se ejecute el activador de webhook (opcional). Deja este campo en blanco. En este ejemplo, la configuración de compilación es una configuración de compilación intercalada, por lo que no se necesita una fuente.

    • Configuración: Crea una configuración de compilación intercalada en Google Cloud Console.

      En el siguiente ejemplo, la configuración de compilación intercalada autentica tu conexión a GitLab mediante tu clave SSH y accede al repositorio especificado. A continuación, verifica la confirmación que invocó el 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
      

      Donde:

      • GITLAB_REPO es la ruta de acceso de tu repositorio de GitLab.
      • PATH_TO_SECRET_VERSION es la ruta de acceso a la versión del secreto como se almacena en Secret Manager. Este es el secreto que contiene tu clave SSH. Por ejemplo: projects/project-id/secrets/secret-name/versions/1.
      • SSHKEY es el nombre del entorno que se usa en este caso para almacenar la ruta de acceso al secreto.
    • Sustituciones (opcional): Puedes optar por definir variables de sustitución específicas del activador mediante este campo.

      En este ejemplo, supongamos que deseas observar un nombre de rama específico asociado con un ID de confirmación y, luego, cambiar a ese nombre de rama en la definición de la compilación. Para obtener estos datos, puedes crear variables de sustitución con vinculaciones de carga útil a fin de guardar el nombre de la rama.

      Especifica las siguientes variables y valores a continuación:

      Nombre de la variable Valor de la variable
      _BRANCH $(body.ref)
      _TO_SHA $(body.after)

      Para ver la carga útil asociada con los eventos de GitLab, consulta la página de documentación de GitLab en Eventos.

    • Filtros (opcional): Puedes crear una regla dentro de un activador que determine si este ejecutará una compilación según tus variables de sustitución.

      Si deseas que el activador ejecute una compilación si el nombre de la rama coincide con main, puedes usar el operador “==” para buscar coincidencias exactas. También puedes usar la palabra clave “coincidencias” si deseas hacer coincidir por expresión regular.

      Especifica los siguientes elementos como filtros:

      • _BRANCH == refs/heads/main

      Si deseas ver la sintaxis de ejemplo para filtrar que puedes aplicar a tus activadores de webhook, consulta Usa CEL para filtrar eventos de compilación.

  5. Haz clic en Crear para crear el activador.

gcloud

Para crear un activador de webhook que invoque compilaciones desde GitLab, haz lo siguiente:

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

Donde:

  • TRIGGER_NAME es el nombre del activador.
  • PATH_TO_SECRET es la ruta de acceso al secreto almacenada en Secret Manager. Por ejemplo, projects/my-project/secrets/my-secret/versions/2
  • PATH_TO_INLINE_BUILD_CONFIG es la ruta de acceso a tu configuración de compilación intercalada. Aunque la configuración de compilación se almacena intercalada en el activador que estás creando, la ruta de configuración aquí se extrae de un archivo local.
  • PATH_TO_REPO es la ruta al repositorio en la que se invoca una compilación. Por ejemplo, https://gitlab.com/project-namespace. La URL del repositorio debe ser un repositorio conectado a Cloud Build.

  • BRANCH_NAME es el nombre de la rama si deseas configurar el activador para que se compile en una rama.

  • TAG_NAME es el nombre de tu etiqueta si deseas configurar tu activador para compilar en una etiqueta.

Crea un webhook en GitLab

A fin de que GitLab realice solicitudes a Cloud Build, deberá crear un webhook en GitLab siguiendo las instrucciones de la documentación de GitLab para Webhooks.

Ahora, cada vez que las actualizaciones de tu repositorio coincidan con el evento activador que especificaste en tu webhook, los activadores de webhook de Cloud Build invocarán una compilación de forma automática.

¿Qué sigue?