Compila repositorios alojados en el servidor de Bitbucket

En esta página, se explica cómo puedes invocar compilaciones en Bitbucket Server 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 el SDK de Cloud.

Configuración

Antes de crear un activador de webhook para invocar compilaciones en Bitbucket Server, deberás crear una Llave SSH a fin de autenticar tu conexión al servidor de Bitbucket. 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 Bitbucket Server, necesitarás recuperar la llave SSH en la configuración de compilación intercalada.

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

Crea una clave SSH

Para acceder a tu código en el servidor de Bitbucket, 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 Llave SSH del servidor de Bitbucket nueva, en la que BITBUCKET_SERVER_HOST/REPOSITORY es la URL del repositorio de tu servidor de Bitbucket:

    ssh-keygen -t rsa -b 4096 -N '' -C BITBUCKET_SERVER_HOST/REPOSITORY -f id_bitbucket
    

    El comando crea una Llave SSH nueva en working-dir/id_bitbucket 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 el servidor de Bitbucket

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

Agrega tu llave de acceso SSH pública en el servidor de Bitbucket

Para proteger las operaciones que otros sistemas realizan en tus repositorios administrados en el servidor de Bitbucket, deberás agregar tu clave de acceso SSH pública en el servidor de Bitbucket y otorgar tu claveLectura. Si deseas obtener información sobre cómo agregar tu clave, consulta Llaves de acceso SSH para el uso del sistema.

Crea y almacena tus credenciales en el Administrador de secretos

Cuando creas una Llave SSH, se crea un archivo id_bitbucket en tu entorno local. Dado que este archivo contiene información sensible asociada con la autenticación, debes almacenar el archivo en el Administrador de secretos antes de usarlo para invocar una compilación.

Además del secreto que se usó al crear un activador de webhook, también deberás crear un secreto en el administrador de secretos para validar y autorizar eventos de webhook entrantes en Cloud Build.

Para crear y almacenar tus credenciales en el Administrador de secretos, haz lo siguiente:

  1. Ve a la página de Secret Manager en Cloud Console:

    Ir a la página de 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 el secreto.

  4. En el campo Valor del secreto, ingresa un nombre para tu 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_bitbucket.

  5. Deja la sección Regiones sin modificar.

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

Después de crear tu secreto, Google Cloud Console otorgará automáticamente la función Administrador de secretos del 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 descritos en Otorga una función de administrador de secretos a tu cuenta de servicio.

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

rm id_bitbucket*

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

Crear activadores de webhook

Console

Para crear un activador de webhook que invoque compilaciones desde el servidor de Bitbucket 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 el activador a fin de comenzar a compilar compilaciones en respuesta a eventos de webhook entrantes.
    • URL de webhook: Usa la URL de webhook para autenticar eventos de webhooks entrantes.

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

        Sigue estos pasos para crear un secreto nuevo:

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

          Verás la casilla 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á automáticamente en Secret Manager.

        Para usar un secreto existente, sigue estos pasos:

        1. Seleccione Usar existentes.
        2. En el campo Secreto, selecciona el nombre del secreto que quieres 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 tu versión del secreto en el menú desplegable.

      Después de crear o seleccionar tu secreto, verás una vista previa de 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 tu clave de API manualmente a la URL o aprender cómo obtener una clave de API si no tienes. uno por uno.

      Puedes usar la URL para invocar un evento de webhook mediante una solicitud HTTP con el método POST.

       https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}
      

      Para obtener más información sobre cómo usar la URL cuando creas un webhook en el servidor de Bitbucket, consulta Crear un webhook en el servidor de Bitbucket.

    • Fuente (opcional): 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 con el servidor de Bitbucket mediante tu Llave SSH y accede a tu repositorio especificado. Luego, 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 -p BITBUCKET_PORT BITBUCKET_HOST > /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'
          - 'ssh://BITBUCKET_HOST:BITBUCKET_PORT/BITBUCKET_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í:

      • BITBUCKET_HOST es el nombre de host de tu repositorio de Bitbucket.
      • BITBUCKET_PORT es el puerto SSH de tu repositorio de Bitbucket (por lo general, 7999).
      • BITBUCKET_REPO es la ruta de acceso a tu repositorio de Bitbucket.
      • PATH_TO_SECRET_VERSION es la ruta a tu versión del secreto como está almacenada en el administrador de secretos. 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 de acceso a tu secreto.
    • Sustituciones (opcional): Puedes usar este campo para definir variables de sustitución específicas de los activadores.

      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 compilación. Para obtener estos datos, puedes crear variables de sustitución con vinculaciones de carga útil para 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.changes[0].refId)
      _TO_SHA $(body.changes[0].toHash)

      Para ver la carga útil asociada con los eventos de servidor de Bitbucket, consulta Carga útil de 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.

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

      Especifica lo siguiente como tus filtros:

      • _BRANCH == refs/heads/main

      Para ver más sintaxis de ejemplo de filtrado que podrías aplicar a tus activadores de webhook, consulta Cómo usar CEL para filtrar eventos de compilación.

  5. Haz clic en Crear para crear el activador de compilación.

gcloud

Para crear un activador de webhook que invoque compilaciones desde el servidor de Bitbucket, ejecuta el comando gcloud alpha. En el siguiente ejemplo, el activador se configura para responder a compilaciones con una rama que coincida con refs/heads/main basada en la carga útil especificada, según lo definido por la variable de sustitución, _BRANCH.

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --subtitutions=\
         _BRANCH='$(body.changes[0].refId)', TO_SHA='$(body.changes[0].refId)'
       --filter='_BRANCH == refs/heads/main'
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --branch=BRANCH_NAME

Aquí:

  • TRIGGER_NAME es el nombre del activador.
  • PATH_TO_REPO es la ruta al repositorio en la que se invoca una compilación. Por ejemplo, https://www.github.com/owner/repo.
  • PATH_TO_SECRET es la ruta a tu secreto, tal como se almacena en el administrador de secretos. 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 tu activador para que se compile en una rama.

Crea un webhook en el servidor de Bitbucket

Para que el servidor de Bitbucket haga solicitudes a Cloud Build, deberás crear un webhook en el servidor de Bitbucket mediante las instrucciones que se describen en Crear webhooks.

Ahora, cada vez que tu actualización se actualice al evento activador que especificaste en tu webhook, se invocarán de forma automática una compilación mediante activadores de webhook de Cloud Build.

¿Qué sigue?