Notificaciones para Cloud Source Repositories

Cloud Source Repositories publica mensajes sobre tu repositorio en recursos que tienen nombre llamados temas. Las apps suscritas a temas de Pub/Sub pueden recibir estos mensajes. Por ejemplo, puedes recibir una alerta cuando cambia el estado del repositorio. Además, puedes configurar funciones y permisos para tus temas de Pub/Sub a fin de controlar la interacción de los usuarios con los eventos de Pub/Sub que genera tu repositorio.

Esta página proporciona una descripción general de las notificaciones de Pub/Sub para Cloud Source Repositories. Para obtener más información sobre cómo configurar y usar las notificaciones de Pub/Sub, consulta cómo configurar las notificaciones de Pub/Sub.

Alcance

Puedes configurar Cloud Source Repositories para publicar eventos en un tema de Pub/Sub. Puedes definir el alcance de esta configuración para que se incluya todo tu proyecto de Google Cloud o un repositorio individual.

Una vez configurado, Cloud Source Repositories publica mensajes para el tema especificado de Pub/Sub mediante tu cuenta de servicio. Primero debes otorgar permisos a la cuenta de servicio para publicar en el tema. Si habilitaste el registro de auditoría para Pub/Sub, esta cuenta de servicio figurará como emisora de las API de Pub/Sub.

Permisos

Necesitarás lo siguiente a fin de configurar Cloud Source Repositories para publicar mensajes:

  • Un proyecto o repositorio cuyos eventos se observarán (si se especifica un proyecto, se observarán todos los repositorios de ese proyecto)
  • Un tema de Pub/Sub en el que Cloud Source Repositories publique mensajes
  • Una cuenta de servicio para acceder al tema de Pub/Sub
  • Un formato de mensaje (como JSON o Protocol Buffers)

Debes tener estos permisos si deseas configurar Cloud Source Repositories para Pub/Sub:

  • source.repos.updateRepo en el repositorio especificado o source.repos.updateProjectConfig en el proyecto especificado
  • iam.serviceAccounts.actAs en la cuenta de servicio especificada

Después de registrar el tema de Pub/Sub, la cuenta de servicio especificada debe tener el permiso pubsub.topics.publish para publicar un mensaje.

Tipos de eventos

Pub/Sub puede notificarte cuando un usuario cree o borre un repositorio, o envíe una confirmación a un repositorio. Cada evento es de un tipo específico. En la siguiente tabla, se enumeran los tipos y sus definiciones correspondientes.

Tipo de evento Descripción
CreateRepo Ocurre cuando un usuario crea un repositorio.
RefUpdate Ocurre cuando un usuario ejecuta un comando de Git push.
DeleteRepo Ocurre cuando un usuario borra un repositorio.

Formato de las notificaciones

Puedes configurar Pub/Sub para que use uno de estos dos formatos de notificaciones:

  • JSON
  • Protocol Buffers

Datos de notificaciones

Cada notificación de Pub/Sub contiene la siguiente información sobre un evento:

Nombre del campo Descripción
name Nombre del repositorio
url La URL del repositorio
eventTime La hora en que se produjo el cambio
refUpdateEvent Información sobre el cambio específico
createRepoEvent Indica si un usuario creó un repositorio
deleteRepoEvent Indica si un usuario borró un repositorio

Si la notificación corresponde a un comando git push, la notificación que contiene el campo refUpdateEvent incluye la siguiente información:

Nombre del campo Descripción
email La dirección de correo electrónico del usuario que realizó el cambio
refUpdates Información sobre la confirmación

El campo refUpdates contiene los siguientes detalles sobre el comando git push:

Nombre del campo Descripción
refName El nombre de la rama
updateType El tipo de actualización (para obtener más información, consulta Tipos de actualización)
oldId El ID de confirmación anterior del repositorio
newId El nuevo ID para el repositorio

Tipos de actualización

Un evento git push puede tener uno de cuatro tipos de actualizaciones. Encontrarás el tipo en el campo updateType de la notificación.

Tipo de actualización Descripción
CREATE Ocurre cuando el comando crea una nueva referencia.
UPDATE_FAST_FORWARD Ocurre cuando el comando actualiza un objeto.
UPDATE_NON_FAST_FORWARD Se produce cuando el comando usa la marca -f, como git push -f.
DELETE Ocurre cuando el comando borra una referencia.

Ejemplo de notificación

El siguiente es un ejemplo de los datos que se incluyen en una notificación de Pub/Sub. Esta notificación usa el formato JSON.

"name": "projects/test-project/repos/pubsub-test",
"url": "[URL_PATH]",
"eventTime": "2018-02-21T21:23:25.566175Z",
"refUpdateEvent": {
  "email": "someone@somecompany.com",
  "refUpdates": {
    "refs/heads/master": {
    "refName": "refs/heads/master",
    "updateType": "UPDATE_FAST_FORWARD",
    "oldId": "c7a28dd5de3403cc384a025834c9fce2886fe763",
    "newId": "f00768887da8de62061210295914a0a8a2a38226"
    }
  }
}

Ejemplo de configuración de varios proyectos

Puedes configurar Cloud Source Repositories para que publique un mensaje en un tema de otro proyecto. En este caso, debes crear una cuenta de servicio en el mismo proyecto en el que se encuentra el repositorio. En el proyecto que contiene el tema de Pub/Sub, asigna la función roles/pubsub.publisher a esta cuenta de servicio. Cuando configures Cloud Source Repositories con esta cuenta y este tema de Pub/Sub, los mensajes de evento de tu repositorio aparecerán en el tema del otro proyecto.