Usa CEL para filtrar eventos de compilación

Cloud Build usa Common Expression Language (CEL), un lenguaje de código abierto que se usa para evaluar expresiones y filtrar eventos de compilación. Cloud Build proporciona compatibilidad con CEL para notificadores, activadores de Pub/Sub y activadores de webhook.

En esta página, se explica cómo puedes filtrar eventos de compilación mediante CEL.

Compatibilidad con CEL

En esta sección, se analizan las características de Cloud Build compatibles con CEL.

Activadores de Pub/Sub

Cloud Build proporciona asistencia de CEL cuando se define el activador de Pub/Sub. Puedes configurar filtros personalizados para invocar compilaciones en eventos de carga útil entrantes que coincidan con los criterios que especificas en tu filtro. Por ejemplo, puedes crear un activador de Pub/Sub que responda a los eventos de Container Registry cuando las imágenes se envíen a una etiqueta específica, como staging o prod, mediante un CEL. filtro en una variable de sustitución definida anteriormente. En el siguiente ejemplo, la variable _IMAGE_TAG hace referencia al cuerpo de un evento de carga útil entrante:

_IMAGE_TAG == `prod` || _IMAGE_TAG == `staging`

Para obtener más información sobre cómo se pueden usar los filtros en los activadores de Pub/Sub, consulta la página sobre cómo crear activadores de Pub/Sub.

Activadores de webhook

Cloud Build proporciona asistencia de CEL cuando se define el activador de webhook. Puedes configurar filtros personalizados para invocar compilaciones en eventos de carga útil entrantes que coincidan con los criterios que especificas en tu filtro. Por ejemplo, puedes crear un activador de webhook que invoque compilaciones en respuesta a una rama específica como refs/heads/main. En el siguiente ejemplo, la variable _BRANCH hace referencia al cuerpo de un evento de carga útil entrante:

_BRANCH == refs/heads/main

Para obtener más información sobre cómo se pueden usar los filtros en los activadores de webhook, consulta Crea activadores de webhook.

Notificadores de Cloud Build

Cloud Build proporciona compatibilidad con CEL en la string filter en archivos de configuración del notificador. En el archivo de configuración del notificador, puedes especificar la string filter para filtrar los eventos de compilación. En el siguiente ejemplo, se muestra un archivo de configuración de notificador que usa la string filter para filtrar eventos de compilación con el estado SUCCESS:


    apiVersion: cloud-build-notifiers/v1
    kind: my-notifier
    metadata:
      name: my-notifier-one
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        delivery:
          url: https://notifier.com/one
          

Si quieres ver un ejemplo completo de un archivo de configuración de notificador, consulta archivos de ejemplo para el notificador de Slack, SMTP o HTTP.

Ejemplos de filtros

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 notificador 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

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")

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

Aquí:

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