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.

Définition du 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.

Remarque :Si vous mettez en miroir des dépôts vers Cloud Source Repositories, l'adresse e-mail dans les notifications Pub/Sub apparaît toujours sous la forme [e-mail].

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