Notificações do Cloud Source Repositories

O Cloud Source Repositories publica mensagens sobre seu repositório em recursos nomeados, chamados de tópicos. Os apps inscritos nos tópicos do Pub/Sub podem receber essas mensagens. Por exemplo, quando seu estado de repositório for alterado, será possível receber um alerta. Além disso, é possível configurar papéis e permissões para seus tópicos do Pub/Sub para controlar como os usuários interagem com os eventos do Pub/Sub gerados pelo seu repositório.

Nesta página, fornecemos uma visão geral das notificações de Pub/Sub para o Cloud Source Repositories. Para saber como configurar e usar notificações do Pub/Sub, consulte este link.

Escopo

É possível configurar o Cloud Source Repositories para publicar eventos em um tópico do Pub/Sub. É possível definir o escopo dessa configuração como todo o projeto do Google Cloud ou como um repositório individual.

Depois de configurado, o Cloud Source Repositories publica mensagens no tópico do Pub/Sub especificado usando sua conta de serviço. Primeiro, conceda permissões à conta de serviço para publicar no tópico. Se o registro de auditoria estiver ativado para Pub/Sub, essa conta de serviço será mostrada como o autor da chamada das APIs do Pub/Sub.

Permissões

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

  • Um projeto ou um repositório que é assistido para eventos. Se um projeto for especificado, todos os repositórios desse projeto serão assistidos.
  • Um tópico do Pub/Sub em que o Cloud Source Repositories publica mensagens.
  • Uma conta de serviço para acessar o tópico do Pub/Sub.
  • Um formato de mensagem (como JSON ou Buffers de protocolo).

Ao configurar o Cloud Source Repositories para Pub/Sub, é preciso ter estas permissões:

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

Depois que o tópico do Pub/Sub é registrado, a conta de serviço especificada precisa ter a permissão pubsub.topics.publish para publicar uma mensagem.

Tipos de evento

O Pub/Sub pode notificá-lo quando um usuário cria um repositório, exclui um repositório ou envia uma confirmação para um repositório. Cada evento é um tipo de evento específico. Na tabela a seguir, listamos os tipos e as definições correspondentes.

Tipo de evento Descrição
CreateRepo Ocorre quando um usuário cria um repositório.
RefUpdate Ocorre quando um usuário executa um comando “git push”.
DeleteRepo Ocorre quando um usuário exclui um repositório.

Formato da notificação

É possível configurar o Pub/Sub para usar um dos dois formatos de notificações:

  • JSON
  • Buffers de protocolo

Dados da notificação

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

Nome do campo Descrição
name O nome do repositório.
url O URL do repositório.
eventTime O horário em que a alteração ocorreu.
refUpdateEvent Informações sobre uma alteração específica.
createRepoEvent Indica se um usuário criou um repositório.
deleteRepoEvent Indica se um usuário excluiu um repositório.

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

Nome do campo Descrição
email O endereço de e-mail do usuário que fez a alteração.
refUpdates Informações sobre a confirmação.

O campo refUpdates contém os seguintes detalhes sobre o comando git push:

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

Atualizar tipos

Um evento git push pode ter um dos quatro tipos de atualização. Veja o tipo no campo updateType da notificação.

Atualizar tipo Descrição
CREATE Ocorre quando o comando cria uma referência nova.
UPDATE_FAST_FORWARD Ocorre quando o comando atualiza um objeto.
UPDATE_NON_FAST_FORWARD Ocorre quando o comando usa a sinalização -f, como git push -f.
DELETE Ocorre quando o comando exclui uma referência.

Exemplo de notificação

Veja a seguir um exemplo dos dados contidos em uma 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 entre projetos

É possível configurar o Cloud Source Repositories para publicar uma mensagem em um tópico em um projeto diferente. Nesse caso, crie uma conta de serviço no mesmo projeto em que seu repositório está. No projeto que contém o tópico do Pub/Sub, forneça o papel roles/pubsub.publisher a esta conta de serviço. Quando você configura o Cloud Source Repositories com esta conta e este tópico do Pub/Sub, as mensagens de evento para seu repositório aparecem no tópico no outro projeto.