Configura las notificaciones de problemas de GitHub

Cloud Build puede notificarte sobre actualizaciones de compilación enviarte notificaciones a los canales que quieras. En esta página, se explica cómo configurar notificaciones con el Notificador de problemas de GitHub.

Antes de comenzar

  • Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

    Enable the APIs

Configura las notificaciones de problemas de GitHub

En la siguiente sección, se explica cómo puedes configurar manualmente las notificaciones de problemas de GitHub con el Notificador de problemas de GitHub. En cambio, si deseas automatizar la configuración, consulta Automatiza la configuración para las notificaciones.

Para configurar los problemas de GitHub, sigue estos pasos:

  1. Crea un token de acceso personal de GitHub:

    1. Ve a la configuración de GitHub para crear un token nuevo.
    2. Selecciona el permiso repo.

    3. Haz clic en Generar token.

  2. Almacena tu token de GitHub en Secret Manager:

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

      Abrir la página Administrador de secretos

    2. Haz clic en Crear secreto.

    3. Ingresa un nombre para tu secreto.

    4. En Valor del secreto, agrega tu token de GitHub.

    5. Para guardar el secreto, haz clic en Crear secreto.

  3. Aunque tu cuenta de servicio de Cloud Run tenga Editor de tu proyecto, no el rol Editor suficientes para acceder a tu Secret en Secret Manager. Deberás asignarle a tu cuenta de servicio de Cloud Run acceso a tu secreto:

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

      Abrir la página IAM

    2. Busca la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto:

      La cuenta de servicio predeterminada de Compute Engine tendrá un aspecto similar al siguiente:

      project-number-compute@developer.gserviceaccount.com
      

      Anota tu cuenta de servicio predeterminada de Compute Engine.

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

      Abrir la página Administrador de secretos

    4. Haz clic en el nombre del Secret que contiene el token de GitHub.

    5. En la pestaña Permisos, haz clic en Agregar miembro.

    6. Agrega la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto como miembro.

    7. Selecciona el permiso Administrador y descriptor de acceso a secretos como la función.

    8. Haz clic en Guardar.

  4. Otorga permiso de lectura a tu cuenta de servicio de Cloud Run Buckets de Cloud Storage:

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

      Abrir la página IAM

    2. Busca la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto:

      La cuenta de servicio predeterminada de Compute Engine tendrá un aspecto similar al siguiente:

      project-number-compute@developer.gserviceaccount.com
      
    3. Haz clic en el ícono de lápiz en la fila que contiene tu cuenta de servicio predeterminada de Compute Engine. Verás la pestaña Editar acceso.

    4. Haz clic en Agregar otra función.

    5. Agrega la siguiente función:

      • Visualizador de objetos de almacenamiento
    6. Haz clic en Guardar.

  5. Escribe un archivo de configuración de plantilla para describir el formato creado que debe tener los problemas de GitHub:

    En el siguiente archivo de configuración de plantilla de ejemplo, los campos title y body usan variables de sustitución de la compilación:

    {
        "title": "Build {{.Build.BuildTriggerId}}: {{.Build.Status}}",
        "body": "[{{.Build.ProjectId}}] {{.Build.BuildTriggerId}} status: **{{.Build.Status}}**\n\n[View Logs]({{.Build.LogUrl}})"
    }
    

    Si quieres ver el ejemplo, consulta el archivo de configuración de plantilla para el notificador de problemas de GitHub.

    Se pueden configurar campos adicionales a partir de los parámetros del cuerpo disponibles desde el extremo de la extremo de API GitHub para crear un problema.

  6. Escribe un archivo de configuración del notificador para configurar tu notificador de problemas de GitHub y filtrar compilar eventos:

    En el siguiente ejemplo de archivo de configuración del notificador, el campo filter usa Common Expression Language con la variable disponible, build, para filtrar los eventos de compilación con un estado SUCCESS:

    apiVersion: cloud-build-notifiers/v1
    kind: GitHubIssuesNotifier
    metadata:
      name: example-githubissues-notifier
    spec:
      notification:
        filter: build.status == Build.Status.FAILURE
        template: 
          type: golang
          uri: gs://bucket_name/template-file-name
        delivery:
          githubToken:
            secretRef: github-token
          githubRepo: myuser/myrepo
      secrets:
      - name: github-token
        value: projects/project-id/secrets/secret-name/versions/latest
    

    Aquí:

    • githubToken es la variable de configuración que se usa en este ejemplo para hacer referencia al token de GitHub almacenado en Secret Manager. El nombre de la variable que especifiques aquí debe coincidir con el campo name debajo de secrets.
    • bucket-name es el nombre de tu depósito.
    • template-file-name es el nombre de tu archivo de plantilla.
    • myuser/myrepo es el nombre del repositorio en el que se crearán los problemas.
    • project-id es el ID de tu proyecto de Google Cloud.
    • secret-name es el nombre del secreto que contiene el token de GitHub.

    Si deseas ver el ejemplo, consulta el archivo de configuración del notificador para los problemas de GitHub. notificador.

    Para ver campos adicionales por los que puedes filtrar, consulta el recurso Compilar. Si deseas ver ejemplos de filtrado adicionales, consulta Usa CEL para filtrar eventos de compilación.

  7. Sube el archivo de configuración y el archivo de plantilla del notificador a un bucket de Cloud Storage:

    1. Si no tienes un depósito de Cloud Storage, ejecuta el siguiente comando para crear un depósito, en el que bucket-name es el nombre que deseas asignar a tu depósito, sujeto a los requisitos de nombres.

      gcloud storage buckets create gs://bucket-name/
      
    2. Sube el archivo de configuración del notificador y el archivo de plantilla a tu bucket:

      gcloud storage cp config-file-name gs://bucket-name/config-file-name
      
      gcloud storage cp config-file-name gs://bucket-name/config-file-name
      

      Aquí:

      • bucket-name es el nombre de tu depósito.
      • config-file-name es el nombre de tu archivo de configuración.
      • template-file-name es el nombre de tu archivo de plantilla.
  8. Implementa tu notificador en Cloud Run.

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/githubissues:latest \
       --no-allow-unauthenticated \
       --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
    

    Aquí:

    • service-name es el nombre del servicio de Cloud Run en el que se implementa la imagen.

    • config-path es la ruta de acceso al archivo de configuración del notificador para tus problemas de GitHub. notificador, gs://bucket-name/config-file-name.

    • project-id es el ID de tu proyecto de Google Cloud.

    El comando gcloud run deploy extrae la última versión de la imagen alojada de Artifact Registry de Cloud Build. Cloud Build es compatible con imágenes de notificador durante nueve meses. Después de nueve meses, Cloud Build borra la versión con imágenes. Si deseas usar una versión con imágenes anterior, deberás especificar la versión semántica completa de la etiqueta de imagen en el atributo image de tu comando gcloud run deploy. Puedes encontrar etiquetas y versiones con imágenes anteriores en Artifact Registry.

  9. Otorga permisos de Pub/Sub para crear tokens de autenticación en tu proyecto:

     gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
    

    Aquí:

    • project-id es el ID de tu proyecto de Google Cloud.
    • project-number es el número de proyecto de Google Cloud.
  10. Crea una cuenta de servicio para representar tu identidad de suscripción de Pub/Sub:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
      --display-name "Cloud Run Pub/Sub Invoker"
    

    Puedes usar cloud-run-pubsub-invoker o un nombre único dentro de tu proyecto de Google Cloud.

  11. Otorga el permiso Invoker de Cloud Run a la cuenta de servicio de cloud-run-pubsub-invoker:

    gcloud run services add-iam-policy-binding service-name \
       --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
       --role=roles/run.invoker
    

    Aquí:

    • service-name es el nombre del servicio de Cloud Run en el que se implementa la imagen.
    • project-id es el ID de tu proyecto de Google Cloud.
  12. Crea el tema cloud-builds a fin de recibir mensajes de actualización de compilación para tu notificador:

    gcloud pubsub topics create cloud-builds
    
  13. Crea un suscriptor de envío de Pub/Sub para tu notificador:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=service-url \
       --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
    

    Aquí:

    • subscriber-id es el nombre que quieres darle a tu suscripción.
    • service-url es la URL generada por Cloud Run para tu nuevo servicio.
    • project-id es el ID de tu proyecto de Google Cloud.

Las notificaciones de tu proyecto de Cloud Build ya están configuradas. Los siguientes Cuando invoques una compilación, se creará un problema en el repositorio de GitHub definido si la compilación coincida con el filtro que configuraste.

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 la 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 su valor en el campo filter con build.images, donde image-name es el nombre completo de la imagen como se muestra en Artifact Registry, como us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

En el siguiente ejemplo, filter filtra los eventos de compilación que tienen ya sea us-east1-docker.pkg.dev/my-project/docker-repo/image-one o us-east1-docker.pkg.dev/my-project/docker-repo/image-two especificado como Nombres de imágenes:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" 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?