Compila repositorios desde Bitbucket Cloud

En esta página, se explica cómo compilar en Bitbucket Cloud con 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 Bitbucket Cloud, deberás crear una clave SSH a fin de autenticar tu conexión a Bitbucket Cloud. 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 Cloud, deberás recuperar tu clave SSH en tu 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 Bitbucket Cloud, 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 Bitbucket Cloud nueva, en la que bitbucket.org es la URL para tu repositorio de Bitbucket Cloud:

    ssh-keygen -t rsa -b 4096 -N '' -C bitbucket.org -f id_bitbucket
    

    El comando crea una clave SSH nueva en working-dir/id_bitbucket 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.

Agrega tu clave de acceso SSH pública a Bitbucket Cloud

Para proteger las operaciones que realizan otros sistemas en tus repositorios administrados en Bitbucket Cloud, deberás agregar tu clave de acceso SSH pública en Bitbucket Cloud y otorgar tus permisos de Lectura clave. Si deseas obtener información para agregar la clave, consulta Agrega claves de acceso.

Crea y almacena tus credenciales en Secret Manager

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

  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 el secreto, Google Cloud Console otorgará de forma automática la función de acceso a Secreto de Secret Manager 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 que se describen en Otorga función de Secret Manager a tu cuenta de servicio.

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

rm id_bitbucket*

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 Bitbucket Cloud con 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
    • Región: Selecciona la región para el activador.

      • Si seleccionas global como 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 "{}"
      

      Si deseas obtener información para usar la URL cuando creas un webhook en Bitbucket Server, consulta Crea un webhook en Bitbucket Server.

    • 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 Bitbucket Cloud con 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 bitbucket.org > /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@bitbucket.org/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_REPO es la ruta de tu repositorio de Bitbucket.
      • 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 de la variable de 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.push.changes[0].new.name)
      _TO_SHA $(body.push.changes[0].new.target.hash)

      Para ver la carga útil asociada con los eventos de Bitbucket Cloud, consulta Cargas útiles de 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 Bitbucket Cloud, sigue estos pasos:

     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://bitbucket.org/username/repo-slug. 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 Bitbucket Cloud

Para que Bitbucket Cloud realice solicitudes a Cloud Build, deberás seguir las instrucciones que se describen en Crea y activa un webhook a fin de crear un webhook en Bitbucket Cloud.

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

¿Qué sigue?