Automatizar compilaciones en respuesta a eventos de webhook

Cloud Build te permite definir webhooks activadores, que pueden autenticarse y aceptar eventos de webhook entrantes. Estos eventos, que se envían a una URL personalizada, te permiten conectar directamente sistemas externos y sistemas de administración de código fuente externo, como Bitbucket.com, Bitbucket Server o GitLab, a Cloud Build mediante 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 tu activador. La configuración de compilación intercalada te permite controlar las operaciones de Git y definir el resto de tu 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 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.

  Nota: Si instalaste la CLI de gcloud con anterioridad, ejecuta gcloud components update para asegurarte de tener la última versión disponible.

Crea activadores de webhook

Console

Para crear un activador de webhook con Google Cloud Console, siga 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 "{}"
     

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

   • Fuente (opcional): Selecciona el repositorio que se compilará cuando se ejecute el activador de webhook. Si especificas una configuración de compilación intercalada, no es necesario que especifiques la siguiente fuente.

   • Revisión (opcional): Selecciona la rama o etiqueta que se compilará cuando se ejecute el activador de webhook. Si especificas una configuración de compilación intercalada, no es necesario que especifiques las siguientes revisiones.

     • Rama (opcional): Configura un activador para compilar en esta rama. Debes especificar un valor literal. No se admiten expresiones regulares.
     • Etiqueta (opcional): Configura un activador para compilar esta etiqueta. Debes especificar un valor literal. No se admiten expresiones regulares.

   • 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 tu 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 la compilación de forma intercalada. Haz clic en Abrir editor para escribir tu archivo de configuración de compilación en Google Cloud Console con sintaxis YAML o JSON. Haz clic en Listo para guardar la configuración de tu compilación.

         Nota: La compatibilidad con la configuración de compilación intercalada no está disponible para Dockerfile ni los paquetes de compilación.

     En el siguiente ejemplo, el archivo de configuración de la compilación intercalada registra los ecos (Hello World):

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

   • Substitutions (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 usar este campo para definir variables de sustitución específicas del activador. También puedes obtener datos mediante 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.

     Si quieres 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, sigue estos pasos:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Advertencia: Es posible que veas un error INVALID_ARGUMENT cuando ejecutes este comando gcloud con la marca --filter especificada. Es posible que el activador de webhook aún se cree de forma correcta. Para verificar la creación del activador, ejecuta gcloud beta builds triggers list.

Donde:

• 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 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 al archivo de configuración de compilación intercalada si usas --inline-config.
• TAG_NAME es el nombre de tu etiqueta si deseas configurar tu activador para que se compile en una etiqueta.
• PATH_TO_BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación si usas --build-config.
• BRANCH_NAME es el nombre de la rama si deseas configurar el activador para que se compile en una rama.

(Opcional) Obtén una clave de API

Para autenticar tu evento de webhook entrante, necesitas una clave de API.

Para obtener una clave de API, haz lo siguiente:

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

   Abre la página Credenciales.

2. Haz clic en Crear credenciales.

3. Haz clic en Clave de API.

   Verás un diálogo con tu clave de API creada. Anota tu clave de API.

4. Si deseas restringir la clave para las aplicaciones de producto, haz clic en Restringir clave a fin de completar los pasos adicionales para proteger la clave. De lo contrario, haga clic en Cerrar.

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

Otorga la función de administrador de secretos a tu cuenta de servicio (opcional)

Cloud Build otorga de forma automática la función de accesorio de Secret Manager a las cuentas de servicio que requieren la función durante la configuración del Secret. Si no ves esta función otorgada automáticamente a la cuenta de servicio necesaria, completa los siguientes pasos para agregar la función de forma manual a fin de que tu cuenta de servicio tenga acceso a tu secreto:

1. Abre la página IAM en Console:

   Abrir la página IAM

2. Toma nota de la cuenta de servicio de Cloud Build a la que deseas otorgar la función.

3. Abre la página Secret Manager en la consola:

   Abrir la página Administrador de secretos

4. Haga clic en el nombre de su secreto.

   Verás la página Detalles del secreto.

   1. Haz clic en la pestaña Permisos del panel de información a la derecha.

   2. Haz clic en Agregar principal.

   3. En la sección Nueva principal, agrega el correo electrónico asociado con tu cuenta de servicio de Cloud Build.

   4. En la sección Selecciona una función, selecciona Secret Manager > Descriptor de acceso a secretos de Secret Manager.

   5. Haga clic en Agregar.

Usa CEL para filtrar eventos de compilación

Cloud Build usa CEL con la variable, build, en los campos enumerados en el recurso Build para acceder a los campos asociados con el evento de compilación, como el ID del activador, la lista de imágenes o los valores de sustitución. Puedes usar la string filter para filtrar los eventos de compilación en tu archivo de configuración de compilación con cualquier campo enumerado en el recurso compilación. Para encontrar la sintaxis exacta asociada con tu campo, consulta el archivo cloudbuild.proto.

Filtrado por ID de activador

Para filtrar por ID de activador, especifica ese valor en el campo filter mediante build.build_trigger_id, en el que trigger-id es tu ID de activador como una string:

filter: build.build_trigger_id == trigger-id

Nota: El ID de activador no es el nombre del activador. Para obtener tu ID de activador, ejecuta el siguiente comando: gcloud beta builds triggers describe trigger-name, donde trigger-name es el nombre de tu activador. El comando enumerará los campos asociados con tu activador, incluido tu ID de activador.

Cómo filtrar por estado

Para filtrar por estado, especifica el estado de compilación que deseas filtrar en el campo filter mediante build.status.

En el siguiente ejemplo, se muestra cómo filtrar eventos de compilación con un estado SUCCESS mediante el campo filter:

filter: build.status == Build.Status.SUCCESS

También puedes filtrar compilaciones con diferentes estados. En el siguiente ejemplo, se muestra cómo filtrar eventos de compilación que tengan un estado SUCCESS, FAILURE o TIMEOUT mediante el campo filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Para ver los valores de estado adicionales por los que puedes filtrar, consulta Estado en la referencia del recurso Compilar.

Filtrado por etiqueta

Para filtrar por etiqueta, especifica el valor de tu etiqueta en el campo filter con build.tags, en el que tag-name es el nombre de tu etiqueta:

filter: tag-name in build.tags

Puedes filtrar según la cantidad de etiquetas especificadas en tu evento de compilación mediante size. En el siguiente ejemplo, el campo filter filtra los eventos de compilación que tienen exactamente dos etiquetas especificadas con una etiqueta especificada como v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Filtrado por imágenes

Para filtrar por imágenes, especifica el valor de la imagen en el campo filter mediante build.images, en el que image-name es el nombre completo de tu imagen, como se muestra en Container Registry, como gcr.io/example/image-one:

filter: image-name in build.images

En el siguiente ejemplo, filter filtra en los eventos de compilación en los que se especificaron gcr.io/example/image-one o gcr.io/example/image-two como nombres de imagen:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Filtrado por tiempo

Puedes filtrar eventos de compilación en función de la hora de creación, de inicio o de finalización de la compilación si especificas una de las siguientes opciones en el campo filter: build.create_time, build.start_time o build.finish_time.

En el siguiente ejemplo, el campo filter usa timestamp con el fin de filtrar los eventos de compilación con un tiempo de solicitud para crear la compilación el 20 de julio de 2020 a las 6:00 a.m.

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

También puedes filtrar eventos de compilación por comparaciones de tiempo. En el siguiente ejemplo, el campo filter usa timestamp para filtrar los eventos de compilación con una hora de inicio entre el 20 de julio de 2020 a las 6:00 a.m. y el 30 de julio de 2020 a las 6:00 a.m.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Si deseas obtener más información sobre cómo se expresan las zonas horarias en CEL, consulta la definición del lenguaje para zonas horarias.

Para filtrar por duración de una compilación, puedes usar duration a fin de comparar marcas de tiempo. En el siguiente ejemplo, el campo filter usa duration para filtrar eventos de compilación con compilaciones que se ejecutan durante al menos cinco minutos:

filter: build.finish_time - build.start_time >= duration("5m")

Nota: Las marcas de tiempo están en formato RFC 3339 UTC y Zulú, con resolución de nanosegundos y hasta nueve dígitos fraccionarios.

Filtrado por sustituciones

Para filtrar por sustitución, especifica la variable de sustitución en el campo filter mediante build.substitutions. En el siguiente ejemplo, el campo filter enumera las compilaciones que contienen la variable de reemplazo substitution-variable y verifica si substitution-variable coincide con el substitution-value especificado:

filter: build.substitutions[substitution-variable] == substitution-value

Donde:

• substitution-variable es el nombre de tu variable de sustitución.
• substitution-value es el nombre de tu valor de reemplazo.

También puedes filtrar por valores de variable de sustitución predeterminados. En el siguiente ejemplo, el campo filter enumera las compilaciones que tienen el nombre de la rama master y las compilaciones que tienen el nombre del repositorio github.com/user/my-example-repo. Las variables de reemplazo predeterminadas BRANCH_NAME y REPO_NAME se pasan como claves a build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Si deseas filtrar en strings mediante expresiones regulares, puedes usar la función integrada matches. En el siguiente ejemplo, el campo filter filtra las compilaciones con un estado de FAILURE o TIMEOUT, y que también tiene una variable de sustitución de compilación TAG_NAME con un valor que coincide con la expresión regular. v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Para ver una lista de valores de sustituciones predeterminadas, consulta Usa sustituciones predeterminadas.

¿Qué sigue?

• Obtén más información sobre cómo crear y administrar activadores.
• Obtén información para compilar repositorios alojados en Bitbucket Server.
• Obtén más información para iniciar compilaciones de forma manual.
• Aprende a ver resultados de compilación.
• Obtén más información para solucionar errores de compilación.