Automatiza las compilaciones en respuesta a eventos de webhook

Cloud Build te permite definir activadores de webhook, que pueden autenticar y aceptar eventos de webhook entrantes. Estos eventos, que se envían a una URL personalizada, te permiten conectar directamente sistemas externos y sistemas externos de administración de código fuente, como Bitbucket.com, Bitbucket Server o GitLab, a Cloud Build a través de eventos de webhook.

Con los activadores de webhook, puedes definir un archivo de configuración de compilación intercalado en lugar de especificar una fuente cuando creas el activador. La configuración de compilación intercalada te permite controlar las operaciones de Git y definir el resto de la compilación.

En esta página, se describe cómo puedes crear activadores de webhook para automatizar compilaciones en respuesta a eventos de webhook.

Antes de comenzar

  • Habilita las APIs de Cloud Build y Secret Manager.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

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

  • Si tu activador de webhook usa un repositorio de Cloud Build como fuente, asegúrate de conocer los repositorios de Cloud Build.

Crea activadores de webhook

Console

Para crear un activador de webhook con la Google Cloud consola, 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 tu activador.

      • Si el archivo de configuración de compilación asociado con el activador especifica un grupo privado, Cloud Build usará ese grupo 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 tu grupo privado.
      • Si el archivo de configuración de compilación asociado al activador no especifica un grupo privado, Cloud Build usa el grupo predeterminado para ejecutar tu compilación en la misma región que tu 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. Necesitarás un secreto para autenticar los eventos de webhook entrantes. Puedes crear un secreto nuevo o usar uno existente. Este secreto es independiente del secreto asociado a tu clave SSH.

      Para crear un secreto, sigue estos pasos:

      1. Selecciona Usar un secreto nuevo (generado por Cloud Build).

      2. Haz clic en Crear secreto.

        Verás el diálogo 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 un secreto existente o crear uno propio.
      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 tu 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 agregarla manualmente a la URL o bien aprender a obtener una clave de API si no la tienes.

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

        Después de completar estos pasos, la función descriptor de acceso a secretos de Secret Manager se otorga automáticamente a tu agente de servicio de Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Si no ves este rol que se agregó automáticamente a tu agente de servicio, completa los siguientes pasos que se describen en Otorga el rol de Secret Manager a tu cuenta de servicio.

    • Fuente (opcional): Si especificas una configuración de compilación intercalada, no es necesario que especifiques una fuente. De lo contrario, haz lo siguiente:

      • Generación de repositorios: Selecciona 2ª generación.

      • Repositorio: En la lista de repositorios disponibles, selecciona el repositorio desde el que deseas compilar. La región de tu repositorio debe coincidir con la región de tu activador.

      • Rama o Etiqueta: Especifica una expresión regular con la rama o el valor de la etiqueta que deben coincidir. Para obtener información acerca de la sintaxis de expresión regular aceptable, consulta Sintaxis RE2.

      • Control de comentarios: Si seleccionaste Solicitud de extracción como tu Evento, elige una de las siguientes opciones para controlar si el activador invoca automáticamente una compilación:

        • Es obligatorio excepto para los propietarios y colaboradores: Cuando un propietario o colaborador del repositorio crea o actualiza una solicitud de extracción, las compilaciones se ejecutan automáticamente. Si un colaborador externo inicia la acción, las compilaciones solo se ejecutan después de que el propietario o colaborador comente /gcbrun en la solicitud de extracción.

        • Obligatorio: Cuando algún colaborador cree o actualice una solicitud de extracción, las compilaciones solo se ejecutarán después de que el propietario o el colaborador comente /gcbrun en la solicitud de extracción. Las compilaciones se ejecutan cada vez que se realiza un cambio en una solicitud de extracción.

        • No obligatorio: Cuando cualquier colaborador crea o actualiza una solicitud de extracción, las compilaciones se ejecutan de forma automática.

    • Configuración: Selecciona el archivo de configuración de compilación ubicado en tu repositorio remoto o crea un archivo de configuración de compilación intercalado para usarlo en tu compilación. Si no especificaste un repositorio de código fuente, debes seleccionar un archivo de configuración de compilación intercalado como opción de configuración:

      • Tipo: Selecciona el tipo de configuración que usarás para la compilación.

        • Archivo de configuración de Cloud Build (YAML o JSON): Usa un archivo de configuración de compilación para la configuración.
        • Dockerfile: Usa Dockerfile para la configuración.
        • Paquetes de compilación: Usa paquetes de compilación para tu configuración.

      • Ubicación: Especifica la ubicación de tu configuración.

        • Repositorio: Si tu archivo de configuración se encuentra en tu repositorio remoto, proporciona la ubicación de tu archivo de configuración de compilación, el directorio Dockerfile o el directorio del paquete de compilación. Si el tipo de configuración de compilación es Dockerfile o un paquete de compilación, deberás proporcionar un nombre para la imagen resultante y, de forma opcional, un tiempo de espera para tu compilación. Cuando proporciones el Dockerfile o el nombre de la imagen del paquete de compilación, verás una vista previa del comando docker build o pack que ejecutará tu compilación.
        • Variables de entorno de paquete de compilación (opcional): Si seleccionaste buildpacks como el tipo de configuración, haz clic en Agregar variable de entorno del paquete para especificar las variables de entorno y los valores del paquete de compilación. Para obtener más información sobre las variables de entorno del paquete de compilación, consulta Variables de entorno.

        • En línea: Si seleccionaste Archivo de configuración de Cloud Build (YAML o JSON) como tu opción de configuración, puedes especificar tu configuración de compilación intercalada. Haz clic en Abrir editor para escribir tu archivo de configuración de compilación en la consola deGoogle Cloud con la sintaxis de YAML o JSON. Haz clic en Listo para guardar la configuración de tu compilación.

      En el siguiente ejemplo, el archivo de configuración de compilación intercalado registra los ecos de "hello world":

       steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']

    • Sustituciones (opcional): Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación o creaste un archivo de configuración de compilación intercalado, puedes definir variables de sustitución específicas del activador con este campo. También puedes obtener datos con vinculaciones de carga útil cuando defines valores de variables de sustitución.

    • 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.

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

gcloud

Para crear un activador de webhook, haz lo siguiente:

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Aquí:

  • TRIGGER_CONFIG_PATH es la ruta de acceso a un archivo de configuración de activador. Si usas un archivo de configuración del activador, los campos name, description, region, secret, service-account, subscription-filter y substitution deben permanecer sin definir. Para obtener más información, consulta BuildTrigger en la documentación de referencia de Cloud Build.
  • TRIGGER_NAME es el nombre del activador.
  • DESCRIPTION (opcional) es una descripción para tu activador.
  • REGION es la región del activador. Este valor debe ser una región que no sea "global".
  • SECRET_NAME es el nombre de tu secreto tal como se almacena en Secret Manager.
  • SECRET_VERSION es la versión asociada con tu secreto tal como se almacena en Secret Manager.
  • SERVICE_ACCOUNT es la cuenta de servicio que se usa para ejecutar todas las operaciones controladas por el usuario relacionadas con el activador de compilación. Si no defines una cuenta de servicio, Cloud Build usa la cuenta de servicio predeterminada de Cloud Build.
  • PROJECT_ID es el ID de tu proyecto de Google Cloud .
  • CONNECTION_NAME es el nombre de tu conexión de host.
  • REPO_NAME es el nombre de tu repositorio.
  • PATH_TO_BUILD_CONFIG es la ruta de acceso a un archivo de configuración de compilación. Usa este parámetro si el activador hace referencia a un archivo de configuración de compilación en un repositorio de Cloud Build. Si configuras este parámetro, no puedes definir un inline-config ni usar parámetros para un Dockerfile.
  • PATH_TO_INLINE_BUILD_CONFIG es la ruta de acceso a una configuración de compilación intercalada. Usa este parámetro si el activador hace referencia a un archivo de configuración de compilación local. Si configuras este parámetro, no puedes definir un build-config ni usar parámetros para un Dockerfile.
  • DOCKERFILE es la ruta de acceso a un Dockerfile. Usa este parámetro si el activador hace referencia a un Dockerfile. Si configuras parámetros de Dockerfile, no puedes definir un build-config ni un inline-config.
  • DOCKERFILE_DIR es el directorio del Dockerfile.
  • DOCKERFILE_IMAGE es el nombre de la imagen de Docker que compila Cloud Build.
  • BRANCH_NAME es el nombre de la rama si deseas configurar el activador para que se compile en una rama. Si estableces este parámetro, no puedes definir un tag.
  • TAG_NAME es el nombre de tu etiqueta si deseas configurar tu activador para compilar en una etiqueta. Si estableces este parámetro, no puedes definir un branch.
  • SUBSTITUTION (opcional) son parámetros que se sustituirán en la especificación de compilación. Por ejemplo, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
  • FILTER (opcional) es una expresión de filtro de CEL para el activador, como '_SUB_ONE == "prod"'.
  • (Opcional) Cuando --require-approval está presente en el comando, Cloud Build requiere la aprobación manual para las compilaciones activadas.

Invoca un evento de webhook

Usa el siguiente comando para invocar un evento de webhook:

curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

(Opcional) Otorga el rol de Secret Manager a tu cuenta de servicio

Cuando configuras tu secreto durante la creación del activador de webhook, en la mayoría de los casos, Cloud Build otorga automáticamente el rol de Usuario con acceso a secretos de Secret Manager a las cuentas de servicio que lo requieren. Sin embargo, si usas un secreto existente, es posible que también debas otorgar de forma manual el rol de Secret Manager Secret Accessor a tu cuenta de servicio de Cloud Build:

  1. Abre la página de IAM en la consola de Google Cloud :

    Abrir la página IAM

  2. Opcional: Para ver las cuentas proporcionadas por Google, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas por Google.

  3. Toma nota de la cuenta de servicio de compilación a la que deseas otorgar el rol.

  4. Abre la página Secret Manager en la consola de Google Cloud :

    Abre la página de Secret Manager

  5. Haz clic en el nombre de tu secreto.

    Verás la página Detalles del secreto.

    1. Haz clic en la pestaña Permisos.

    2. Haz clic en Otorgar acceso.

      Verás el panel Otorgar acceso.

    3. En la sección Agregar principales, agrega el correo electrónico asociado con la cuenta de servicio de compilación.

    4. En la sección Asignar roles, selecciona Secret Manager > Descriptor de acceso a secretos de Secret Manager.

    5. Haz clic en Guardar.

(Opcional) Obtén una clave de API

Para autenticar un evento de webhook entrante, necesitas una clave de API. Esta clave de API forma parte del secreto que eliges cuando configuras el activador de webhook. Si aún no tienes una clave de API o Cloud Build no pudo recuperar una cuando configuraste tu secreto en la consola de Google Cloud , puedes crear una clave de API de forma manual:

Para obtener una clave de API, haz lo siguiente:

  1. Abre la página Credenciales en la consola de Google Cloud :

    Abre la página Credenciales.

  2. Haz clic en Crear credenciales.

  3. Haz clic en Clave de API.

    Verás un diálogo con la clave de API que creaste. Toma nota de tu clave de API.

  4. Si deseas restringir tu clave para aplicaciones de productos, haz clic en Restringir clave para completar los pasos adicionales para proteger tu clave. De lo contrario, haz clic en Cerrar.

    Para obtener información sobre cómo restringir tu clave, consulta Aplica restricciones de claves de API.

¿Qué sigue?