Notificações para Cloud Source Repositories

Os Cloud Source Repositories publicam mensagens sobre o seu repositório em recursos denominados tópicos. As apps subscritas em tópicos do Pub/Sub podem receber estas mensagens. Por exemplo, quando o estado do repositório muda, pode receber um alerta. Além disso, pode configurar funções e autorizações para os seus tópicos do Pub/Sub de modo a controlar a forma como os utilizadores interagem com os eventos do Pub/Sub que o seu repositório gera.

Esta página oferece uma vista geral das notificações do Pub/Sub para o Cloud Source Repositories. Para saber como configurar e usar as notificações do Pub/Sub, consulte o artigo Configurar notificações do Pub/Sub.

Âmbito

Pode configurar o Cloud Source Repositories para publicar eventos num tópico do Pub/Sub. Pode definir o âmbito desta configuração para ser todo o seu Google Cloud projeto ou um repositório individual.

Depois de configurado, o Cloud Source Repositories publica mensagens no tópico Pub/Sub especificado através da sua conta de serviço. Primeiro, tem de conceder autorizações à conta de serviço para publicar no tópico. Se tiver o registo de auditoria ativado para o Pub/Sub, esta conta de serviço é apresentada como o autor das chamadas das APIs Pub/Sub.

Autorizações

A configuração dos Cloud Source Repositories para publicar mensagens requer o seguinte:

  • Um projeto ou um repositório monitorizado para eventos. Se for especificado um projeto, todos os repositórios desse projeto são monitorizados.
  • Um tópico do Pub/Sub para o qual o Cloud Source Repositories publica mensagens.
  • Uma conta de serviço para aceder ao tópico do Pub/Sub.
  • Um formato de mensagem (como JSON ou Protocol Buffers).

Quando configura os Cloud Source Repositories para o Pub/Sub, tem de ter as seguintes autorizações:

  • source.repos.updateRepo no repositório especificado ou source.repos.updateProjectConfig no projeto especificado
  • iam.serviceAccounts.actAs na conta de serviço especificada

Após o registo do tópico Pub/Sub, a conta de serviço especificada tem de ter autorização pubsub.topics.publish para publicar uma mensagem.

Tipos de eventos

O Pub/Sub pode enviar-lhe uma notificação quando um utilizador cria um repositório, elimina um repositório ou envia uma confirmação para um repositório. Cada evento é um tipo de evento específico. A tabela seguinte lista os tipos e as respetivas definições.

Tipo de evento Descrição
CreateRepo Ocorre quando um utilizador cria um repositório.
RefUpdate Ocorre quando um utilizador executa um comando git push.
DeleteRepo Ocorre quando um utilizador elimina um repositório.

Formato de notificação

Pode configurar o Pub/Sub para usar um de dois formatos para notificações:

  • JSON
  • Buffers de protocolo

Dados de notificação

Cada notificação do Pub/Sub contém as seguintes informações sobre um evento:

Nome do campo Descrição
nome Nome do repositório.
url O URL do repositório.
eventTime A hora em que a alteração ocorreu.
refUpdateEvent Informações sobre a alteração específica.
createRepoEvent Indica se um utilizador criou um repositório.
deleteRepoEvent Indica se um utilizador eliminou um repositório.

Se a notificação for para um comando git push, a notificação que contém o campo refUpdateEvent contém as seguintes informações:

Nome do campo Descrição
email O endereço de email do utilizador que fez a alteração.
refUpdates Informações sobre a confirmação.

O campo refUpdates contém os seguintes detalhes acerca do comando git push:

Nome do campo Descrição
refName O nome da ramificação.
updateType O tipo de atualização. Para mais informações, consulte o artigo Tipos de atualizações.
oldId O ID de confirmação anterior do repositório.
newId O novo ID do repositório.

Tipos de atualizações

Um evento git push pode ter um de quatro tipos de atualizações. Pode encontrar o tipo no campo updateType da notificação.

Atualizar tipo Descrição
CRIAR Ocorre quando o comando cria uma nova referência.
UPDATE_FAST_FORWARD Ocorre quando o comando atualiza um objeto.
UPDATE_NON_FAST_FORWARD Ocorre quando o comando usa a flag -f, como git push -f.
ELIMINAR Ocorre quando o comando elimina uma referência.

Exemplo de notificação

Segue-se um exemplo dos dados contidos numa notificação do Pub/Sub. Esta notificação usa o 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"
        }
      }
    }
  }

Exemplo de configuração em vários projetos

Pode configurar os Cloud Source Repositories para publicar uma mensagem num tópico num projeto diferente. Neste caso, tem de criar uma conta de serviço no mesmo projeto onde reside o seu repositório. No projeto que contém o tópico do Pub/Sub, atribua a função roles/pubsub.publisher a esta conta de serviço. Quando configura o Cloud Source Repositories com esta conta e este tópico do Pub/Sub, as mensagens de eventos do seu repositório aparecem no tópico do outro projeto.