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.updateRepoen el repositorio especificado osource.repos.updateProjectConfigen el proyecto especificadoiam.serviceAccounts.actAsen 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 |
|---|---|
| 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.