Compilar repositorios de GitLab

En esta página, se explica cómo compilar en GitLab mediante los 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 el SDK de Cloud.

Configuración

Antes de crear un activador de webhook para compilar en GitLab, deberás crear una Llave 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, deberás recuperar la llave SSH en la configuración de compilación intercalada.

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

Crea una clave SSH

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

Para crear una Llave 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 nueva llave SSH de GitLab, en la que gitlab.com es la URL para el repositorio de GitLab:

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

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

Habilita el acceso SSH en GitLab

Deberás habilitar el acceso SSH en GitLab para permitir que los usuarios de tu servidor agreguen sus propias Llaves SSH y las usen a fin de proteger las operaciones de Git entre su computadora y la instancia de GitLab. Para aprender a usar SSH con GitLab, consulta GitLab y Llaves SSH.

Agrega la clave de acceso SSH pública a GitLab

Para proteger las operaciones que otros sistemas realizan en los repositorios administrados en GitLab, deberás agregar tu clave de acceso SSH pública a GitLab. Para obtener información sobre cómo agregar la clave, consulta Agrega una clave SSH a tu cuenta de GitLab.

Crea y almacena tus credenciales en Secret Manager

Cuando creas una Llave SSH, se crea un archivo id_gitlab en tu entorno local. Dado que este archivo contiene información sensible asociada a la autenticación, debes almacenarlo 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 para 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 de Secret Manager en Cloud Console:

    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 el secreto o sube un archivo.

    Para subir el archivo de Llaves 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.

Después de crear el secreto, Google Cloud Console otorgará de forma automática la función de accesor secreto del administrador de secretos a la 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 descritos en Otorga funciones de Secret Manager a tu cuenta de servicio.

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

rm id_gitlab*

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

Crea activadores de webhook

Console

Para crear un activador de webhook que invoque compilaciones desde GitLab mediante Google Cloud Console, sigue estos pasos:

  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
    • Descripción (opcional): Una descripción para tu activador
    • Evento: Selecciona Evento de webhook para configurar tu activador a fin de que comience las compilaciones en respuesta a los eventos entrantes de webhook.
    • URL de webhook: Usa la URL de webhook para autenticar los eventos de webhook entrantes.

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

        Sigue estos pasos para crear un secreto nuevo:

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

          Verá el cuadro emergente Crear un secreto de webhook.

        3. Ingresa un nombre para tu secreto en el campo Nombre del secreto.

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

        Para usar un secreto existente, sigue estos pasos:

        1. Seleccione Utilizar existente.
        2. En el campo Secreto, selecciona el nombre del secreto que deseas usar del 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 de Secret Manager a tu cuenta de servicio de Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Para obtener más información, consulta Otorga una función de administrador de secretos 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 la clave de API, puedes agregar manualmente la clave de API a la URL o 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 mediante 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 obtener información sobre cómo puedes usar la URL cuando creas un webhook en GitLab, consulta Crea un webhook en GitLab.

    • Fuente (opcional): Es el repositorio que se compilará cuando se ejecute el activador de webhook. 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 llave SSH y accede al repositorio especificado. A continuación, comprueba 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
      

      Aquí:

      • GITLAB_REPO es la ruta de acceso para tu repositorio de GitLab.
      • PATH_TO_SECRET_VERSION es la ruta a la versión de tu secreto como se almacena en Secret Manager. Este es el secreto que contiene tu Llave 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 a tu secreto.
    • Sustituciones (opcional): Puedes optar por definir variables de sustitución específicas del activador mediante este campo.

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

      Especifique 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 el activador ejecutará o no una compilación en función de las 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 verificar si hay coincidencias exactas. También puedes usar la palabra clave “coincidentes” si quieres hacer coincidir por expresiones regulares.

      Especifique lo siguiente como filtros:

      • _BRANCH == refs/heads/main

      Si deseas ver más sintaxis de ejemplo de filtros 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 \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --substitutions=''
       --filter=''
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --branch=BRANCH_NAME # --tag=TAG_NAME

Aquí:

  • TRIGGER_NAME es el nombre del activador.
  • PATH_TO_REPO es la ruta al repositorio para invocar una compilación. Por ejemplo, https://www.github.com/owner/repo
  • PATH_TO_SECRET es la ruta a tu 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.

  • BRANCH_NAME es el nombre de tu rama si deseas configurar el activador para que compile sobre una rama.

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

Crea un webhook en GitLab

Para que GitLab realice solicitudes a Cloud Build, deberás crear un webhook en GitLab. Para ello, sigue las instrucciones descritas en la documentación de GitLab sobre Webhooks.

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

¿Qué sigue?