Compilar repositorios de Bitbucket Server

En esta página, se explica cómo compilar en Bitbucket Server mediante el uso de 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 Bitbucket Server, deberás crear una clave SSH a fin de autenticar la conexión a Bitbucket Server. 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, deberás 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 Llave SSH antes de crear un activador de webhook.

Crea una clave SSH

Para acceder a tu código en Bitbucket Server, deberás recuperar una llave SSH en la 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 clave SSH nueva del servidor de Bitbucket, en la que BITBUCKET_SERVER_HOST/REPOSITORY es la URL de tu repositorio de Bitbucket Server:

    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 Bitbucket Server

Deberás habilitar el acceso SSH en tu servidor de Bitbucket para permitir que los usuarios en 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 Bitbucket Server. Para aprender a usar SSH con Bitbucket Server, consulta Habilita el acceso SSH a los repositorios de Git en Bitbucket Server.

Agrega tu llave de acceso SSH pública a Bitbucket Server

Para proteger las operaciones que realizan otros sistemas en tus repositorios administrados en Bitbucket Server, deberás agregar tu clave de acceso SSH pública a Bitbucket Server y otorgar tu clave.Leer permisos. A fin de obtener información sobre cómo agregar tu clave, consulta Claves de acceso SSH para uso del sistema.

Crea y almacena tus credenciales en Secret Manager

Cuando creas una Llave SSH, se crea un archivo id_bitbucket 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 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 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_bitbucket.

  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_bitbucket*

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

Crea activadores de webhook

Console

Para crear un activador de webhook que se compile desde Bitbucket Server 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. Selecciona Create New.
        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 Bitbucket Server, consulta Crea un webhook en Bitbucket Server.

    • 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 Bitbucket Server con 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 -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 del repositorio de Bitbucket (generalmente, 7999).
      • BITBUCKET_REPO es la ruta de acceso para tu repositorio de Bitbucket.
      • 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.changes[0].refId)
      _TO_SHA $(body.changes[0].toHash)

      Para ver la carga útil asociada con los eventos de Bitbucket Server, consulta Carga útil del evento.

    • 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 de compilación.

gcloud

Para crear un activador de webhook que se compile desde Bitbucket Server, ejecuta el comando gcloud alpha. En el siguiente ejemplo, el activador está configurado para responder a las compilaciones con una rama que coincide con refs/heads/main en función de la carga útil especificada, como lo define 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 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.

Crea un webhook en Bitbucket Server

Para que Bitbucket Server realice solicitudes a Cloud Build, deberás crear un webhook en Bitbucket Server con las instrucciones que se describen en Crea webhooks.

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

¿Qué sigue?