Notifiche per Cloud Source Repositories

Cloud Source Repositories pubblica messaggi relativi al tuo repository in risorse denominate argomenti. Le app iscritte agli argomenti Pub/Sub possono ricevere questi messaggi. Ad esempio, quando lo stato del repository cambia, puoi ricevere un avviso. Inoltre, puoi configurare ruoli e autorizzazioni per gli argomenti Pub/Sub per controllare in che modo gli utenti interagiscono con gli eventi Pub/Sub generati dal repository.

Questa pagina fornisce una panoramica delle notifiche Pub/Sub per Cloud Source Repositories. Per scoprire come impostare e utilizzare le notifiche Pub/Sub, consulta Configurazione delle notifiche Pub/Sub.

Ambito

Puoi configurare Cloud Source Repositories per pubblicare eventi in un argomento Pub/Sub. Puoi impostare l'ambito di questa configurazione in modo che sia l'intero progetto Google Cloud o un singolo repository.

Una volta configurato, Cloud Source Repositories pubblica i messaggi nell'argomento Pub/Sub specificato utilizzando il tuo account di servizio. Devi prima concedere all'account di servizio le autorizzazioni per pubblicare nell'argomento. Se è abilitato l'audit logging per Pub/Sub, questo account di servizio viene visualizzato come chiamante delle API Pub/Sub.

Autorizzazioni

La configurazione di Cloud Source Repositories per la pubblicazione di messaggi richiede quanto segue:

• Un progetto o un repository controllato per gli eventi. Se è specificato un progetto, vengono monitorati tutti i repository al di sotto di quel progetto.
• Un argomento Pub/Sub in cui Cloud Source Repositories pubblica messaggi.
• Un account di servizio per accedere all'argomento Pub/Sub.
• Un formato di messaggio (ad esempio JSON o buffer di protocollo).

Quando configuri Cloud Source Repositories per Pub/Sub, devi disporre delle seguenti autorizzazioni:

• source.repos.updateRepo nel repository specificato o source.repos.updateProjectConfig nel progetto specificato
• iam.serviceAccounts.actAs sull'account di servizio specificato

Dopo la registrazione dell'argomento Pub/Sub, l'account di servizio specificato deve avere l'autorizzazione pubsub.topics.publish per pubblicare un messaggio.

Tipi di evento

Pub/Sub può inviare una notifica quando un utente crea un repository, elimina un repository o esegue il push di un commit in un repository. Ogni evento è un tipo specifico. La tabella seguente elenca i tipi e le definizioni corrispondenti.

Tipo di evento	Descrizione
CreateRepo	Si verifica quando un utente crea un repository.
RefUpdate	Si verifica quando un utente esegue un comando push git.
DeleteRepo	Si verifica quando un utente elimina un repository.

Formato delle notifiche

Puoi configurare Pub/Sub in modo da utilizzare uno dei due formati per le notifiche:

• JSON
• Buffer di protocollo

Dati delle notifiche

Ogni notifica Pub/Sub contiene le seguenti informazioni su un evento:

Nome campo	Descrizione
name	Nome del repository.
url	L'URL del repository.
eventTime	L'ora in cui è avvenuta la modifica.
refUpdateEvent	Informazioni sulla modifica specifica.
createRepoEvent	Indica se un utente ha creato un repository.
deleteRepoEvent	Indica se un utente ha eliminato un repository.

Se la notifica riguarda un comando git push, la notifica contenente il campo refUpdateEvent contiene le seguenti informazioni:

Nome campo	Descrizione
email	L'indirizzo email dell'utente che ha apportato la modifica.
refUpdates	Informazioni sul commit.

Nota: se esegui il mirroring dei repository in Cloud Source Repositories, l'indirizzo email nelle notifiche Pub/Sub viene sempre visualizzato come [e-mail].

Il campo refUpdates contiene i seguenti dettagli sul comando git push:

Nome campo	Descrizione
refName	Il nome del ramo.
updateType	Il tipo di aggiornamento. Per ulteriori informazioni, vedi Tipi di aggiornamento.
oldId	L'ID commit precedente per il repository.
newId	Il nuovo ID per il repository.

Tipi di aggiornamento

Un evento git push può avere uno dei quattro tipi di aggiornamento disponibili. Puoi trovare il tipo nel campo updateType della notifica.

Tipo aggiornamento	Descrizione
CREA	Si verifica quando il comando crea un nuovo riferimento.
UPDATE_FAST_FORWARD	Si verifica quando il comando aggiorna un oggetto.
UPDATE_NON_FAST_FORWARD	Si verifica quando il comando utilizza il flag -f, ad esempio git push -f.
ELIMINA	Si verifica quando il comando elimina un riferimento.

Esempio di notifica

Di seguito è riportato un esempio di dati contenuti in una notifica Pub/Sub. Questa notifica utilizza il 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"
        }
      }
    }
  }

Esempio di configurazione tra progetti

Puoi configurare Cloud Source Repositories per pubblicare un messaggio in un argomento in un altro progetto. In questo caso, devi creare un account di servizio nello stesso progetto in cui si trova il repository. Nel progetto che contiene l'argomento Pub/Sub, assegna il ruolo roles/pubsub.publisher a questo account di servizio. Quando configuri Cloud Source Repositories con questo account e questo argomento Pub/Sub, i messaggi di evento per il tuo repository vengono visualizzati nell'argomento dell'altro progetto.