Notificaciones de Cloud Source Repositories

Cloud Source Repositories publica mensajes sobre tu repositorio en recursos con nombre llamados temas. Las aplicaciones suscritas a temas de Pub/Sub pueden recibir estos mensajes. Por ejemplo, cuando cambia el estado de tu repositorio, puedes recibir una alerta. Además, puedes configurar roles y permisos para tus temas de Pub/Sub con el fin de controlar cómo interactúan los usuarios con los eventos de Pub/Sub que genera tu repositorio.

En esta página se ofrece 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 utilizar las notificaciones de Pub/Sub, consulta Configurar notificaciones de Pub/Sub.

Ámbito

Puedes configurar Cloud Source Repositories para que publique eventos en un tema de Pub/Sub. Puedes definir el ámbito de esta configuración para todo el Google Cloud proyecto o para un repositorio concreto.

Una vez configurado, Cloud Source Repositories publica mensajes en el tema de Pub/Sub especificado mediante su cuenta de servicio. Primero debes dar permisos a la cuenta de servicio para publicar en el tema. Si tienes habilitado el registro de auditoría de Pub/Sub, esta cuenta de servicio se muestra como la que llama a las APIs de Pub/Sub.

Permisos

Para configurar Cloud Source Repositories para que publique mensajes, se necesita lo siguiente:

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

Cuando configures Cloud Source Repositories para Pub/Sub, debes tener estos permisos:

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

Una vez registrado el tema de Pub/Sub, la cuenta de servicio especificada debe tener permiso pubsub.topics.publish para publicar un mensaje.

Tipos de eventos

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

Tipo de evento Descripción
CreateRepo Se produce cuando un usuario crea un repositorio.
RefUpdate Se produce cuando un usuario ejecuta un comando git push.
DeleteRepo Se produce cuando un usuario elimina un repositorio.

Formato de las notificaciones

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

  • JSON
  • Búferes de protocolo

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 la que se produjo el cambio.
refUpdateEvent Información sobre el cambio específico.
createRepoEvent Indica si un usuario ha creado un repositorio.
deleteRepoEvent Indica si un usuario ha eliminado un repositorio.

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

Nombre del campo Descripción
correo electrónico La dirección de correo 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 Nombre de la sucursal.
updateType El tipo de actualización. Para obtener más información, consulta Tipos de actualizaciones.
oldId El ID de la confirmación anterior del repositorio.
newId El nuevo ID del repositorio.

Tipos de actualizaciones

Un evento git push puede tener uno de estos cuatro tipos de actualización. Puedes encontrar el tipo en el campo updateType de la notificación.

Actualizar tipo Descripción
CREAR Se produce cuando el comando crea una referencia.
UPDATE_FAST_FORWARD Se produce cuando el comando actualiza un objeto.
UPDATE_NON_FAST_FORWARD Se produce cuando el comando usa la marca -f, como git push -f.
ELIMINAR Se produce cuando el comando elimina una referencia.

Ejemplo de notificación

A continuación, se muestra un ejemplo de los datos que contiene 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 entre 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 encuentre tu repositorio. En el proyecto que contiene el tema de Pub/Sub, asigna el rol 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 eventos de tu repositorio aparecerán en el tema del otro proyecto.