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

Nota: Si duplicas repositorios en Cloud Source Repositories, la dirección de correo electrónico en las notificaciones de Pub/Sub siempre aparecerá como [e-mail].

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": "[e-mail]",
      "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.