Notifications pour Cloud Source Repositories

Cloud Source Repositories publie des messages concernant votre dépôt dans des ressources nommées appelées sujets. Les applications abonnées à des sujets Pub/Sub peuvent recevoir ces messages. Par exemple, lorsque l'état de votre dépôt évolue, vous pouvez recevoir une alerte. En outre, vous pouvez configurer des rôles et des autorisations pour vos sujets Pub/Sub afin de contrôler la manière dont les utilisateurs interagissent avec les événements Pub/Sub générés par le dépôt.

Cette page présente les notifications Pub/Sub pour Cloud Source Repositories. Pour apprendre à configurer et utiliser cette fonctionnalité, consultez la section Configurer les notifications Pub/Sub.

Champ d'application

Vous pouvez configurer Cloud Source Repositories pour publier des événements dans un sujet Pub/Sub. Vous pouvez définir le champ d'application de cette configuration comme étant l'ensemble de votre projet Google Cloud ou un dépôt individuel.

Une fois configuré, Cloud Source Repositories publie des messages sur le sujet Pub/Sub spécifié à l'aide de votre compte de service. Vous devez d'abord autoriser le compte de service à publier sur le sujet. Si la journalisation d'audit est activée pour Pub/Sub, ce compte de service s'affiche en tant qu'appelant des API Pub/Sub.

Autorisations

La configuration de Cloud Source Repositories pour la publication de messages nécessite les éléments suivants :

  • Un projet ou un dépôt surveillé pour les événements. Si un projet est spécifié, tous les dépôts de ce projet sont surveillés.
  • Un sujet Pub/Sub dans lequel Cloud Source Repositories publie des messages.
  • Un compte de service permettant d'accéder au sujet Pub/Sub.
  • Un format de message (tel que JSON ou Protocol Buffers).

Lorsque vous configurez Cloud Source Repositories pour Pub/Sub, vous devez disposer des autorisations suivantes :

  • source.repos.updateRepo sur le dépôt spécifié ou source.repos.updateProjectConfig sur le projet spécifié
  • iam.serviceAccounts.actAs sur le compte de service spécifié

Une fois que le sujet Pub/Sub est enregistré, le compte de service spécifié doit disposer de l'autorisation pubsub.topics.publish pour publier un message.

Types d'événement

Pub/Sub peut vous envoyer une notification lorsqu'un utilisateur crée ou supprime un dépôt, ou lorsqu'il transfère un commit vers un dépôt. Chaque événement est associé à un type d'événement spécifique. Le tableau suivant répertorie les types et les définitions correspondantes.

Type d'événement Description
CreateRepo Se produit lorsqu'un utilisateur crée un dépôt.
RefUpdate Se produit lorsqu'un utilisateur exécute une commande git push.
DeleteRepo Se produit lorsqu'un utilisateur supprime un dépôt.

Format des notifications

Vous pouvez configurer Pub/Sub de manière à utiliser l'un des deux formats suivants pour les notifications :

  • JSON
  • Protocol Buffers

Données des notifications

Chaque notification Pub/Sub contient les informations suivantes sur un événement :

Nom de champ Description
name Nom du dépôt.
url URL du dépôt.
eventTime Heure à laquelle la modification s'est produite.
refUpdateEvent Informations sur la modification spécifique.
createRepoEvent Indique si un utilisateur a créé un dépôt.
deleteRepoEvent Indique si un utilisateur a supprimé un dépôt.

Si la notification concerne une commande git push, elle indique le champ refUpdateEvent contenant les informations suivantes :

Nom de champ Description
email Adresse e-mail de l'utilisateur qui a effectué la modification.
refUpdates Informations sur le commit.

Le champ refUpdates contient les informations suivantes sur la commande git push :

Nom de champ Description
refName Nom de la branche.
updateType Type de mise à jour. Pour plus d'informations, consultez la section Mettre à jour les types.
oldId ID du commit précédent du dépôt.
newId Nouvel ID du dépôt.

Mettre à jour les types

Un événement git push possède l'un des quatre types de mise à jour suivants : Vous pouvez trouver le type dans le champ updateType de la notification.

Mettre à jour le type Description
CREATE Se produit lorsque la commande crée une nouvelle référence.
UPDATE_FAST_FORWARD Se produit lorsque la commande met à jour un objet.
UPDATE_NON_FAST_FORWARD Se produit lorsque la commande utilise l'indicateur -f, tel que git push -f.
DELETE Se produit lorsque la commande supprime une référence.

Exemple de notification

Vous trouverez ci-dessous un exemple de données contenues dans une notification Pub/Sub. Cette notification utilise le format 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"
        }
      }
    }
  }

Exemple de configuration inter-projets

Vous pouvez configurer Cloud Source Repositories pour publier un message sur un sujet dans un autre projet. Dans ce cas, vous devez créer un compte de service dans le même projet contenant votre dépôt. Dans le projet contenant le sujet Pub/Sub, attribuez le rôle roles/pubsub.publisher à ce compte de service. Lorsque vous configurez Cloud Source Repositories avec ce compte et ce sujet Pub/Sub, les messages d'événement de votre dépôt apparaissent dans le sujet de l'autre projet.