Skip to main content
Skip to content

Usando fluxos de eventos GitHub

GitHub Os Fluxos de Eventos permitem que agentes e integrações assinem alterações em um recurso em vez de sondar para eles.

Observação

GitHub Os Fluxos de Eventos estão dentro prévia pública e sujeitos a alterações. Podemos fazer alterações incompatíveis na API, nos tipos de evento e nos limites com pouca antecedência durante a prévia.

Sobre GitHub Event Streams

GitHub Os Fluxos de Eventos permitem que agentes e integrações assinem alterações em um recurso em vez de sondar para eles. Atualmente, ele dá suporte a eventos para pull requests.

Você cria uma assinatura para uma solicitação pull uma vez, mantém um fluxo aberto nele e GitHub envia um evento quando algo que você assinou muda. Em seguida, seu cliente pode buscar o estado mais recente da API REST.

Os eventos são entregues por Server-Sent Events (SSE), portanto, seu cliente não precisa de um ponto de extremidade público, como acontece com webhooks. Isso torna o Event Streams uma boa opção para agentes e ferramentas em execução no computador de um desenvolvedor.

Os Fluxos de Eventos só estão disponíveis em GitHub.com. Ainda não está disponível em GHE.com.

Antes de começar

  • Acesso: estamos disponibilizando esse recurso por meio de uma lista de espera. Para ingressar na lista de espera, preencha o formulário de lista de espera e entraremos em contato com você quando sua conta tiver recebido acesso. Habilitamos fluxos de eventos por conta:

    • Para tokens de usuário, habilitamos sua conta de usuário.
    • Para GitHub App tokens de instalação, habilitamos o usuário, a organização ou a empresa em que o aplicativo está instalado. Isso abrange todos os aplicativos instalados lá, incluindo o GITHUB_TOKEN em GitHub Actions, mas não os próprios tokens de usuário dos membros.

    As solicitações de outras contas retornam 403 Forbidden com a mensagem "As assinaturas de evento não estão habilitadas para essa conta".

  • Token: use um token de usuário (um personal access tokentoken OAuth ou um GitHub App token de acesso do usuário) ou um GitHub App token de acesso de instalação. Não há suporte para aplicativos que se autenticam como eles mesmos.

  • Permissões: o usuário ou a instalação precisa de acesso de leitura à solicitação de pull à qual você assina.

Início Rápido

Esses exemplos usam o GitHub CLI (gh) para as chamadas à API e curl para o fluxo.

1. Criar uma assinatura

Substitua OWNER, REPO e NUMBER pelo proprietário, pelo nome do repositório e pelo número da pull request.

EVENTS_URL=$(gh api -X POST /event-subscriptions \
  -f resource_url=https://github.com/OWNER/REPO/pull/NUMBER \
  -f 'event_types[]=com.github.pull_request.review.submitted.v1' \
  -f 'event_types[]=com.github.pull_request.state.changed.v1' \
  --jq .events_url)

A resposta inclui id, expires_at e events_url da assinatura. A opção --jq .events_url imprime apenas events_url, o que você precisa na próxima etapa. Uma nova assinatura retorna 201 Created. Se você já tiver uma assinatura com o mesmo pull request e tipos de evento, receberá essa assinatura novamente com 200 OK.

2. Abra o fluxo de eventos

Abra o fluxo em events_url. gh api aguarda toda a resposta antes de imprimir qualquer coisa, portanto, use um cliente de streaming, como curl -N:

curl -sS -N -H 'Accept: text/event-stream' \
  -H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
  "$EVENTS_URL"

Abra o stream antes de disparar a atividade que deseja ver. O fluxo só fornece eventos que acontecem enquanto ele está aberto.

3. Buscar o estado mais recente

Cada evento indica que ocorreu uma alteração e fornece uma api_url atualização. Busque api_url com seu token para ler o estado atual da solicitação de revisão ou pull request.

4. Excluir a assinatura

Quando terminar, feche o stream. A exclusão de uma assinatura não fecha seus fluxos abertos, portanto, feche o fluxo por conta própria primeiro. Liste suas assinaturas ativas com gh api /event-subscriptions para encontrar o id da assinatura. Em seguida, exclua a assinatura, substituindo ID por esse valor:

gh api -X DELETE /event-subscriptions/ID

Referência de API

Todas as rotas estão em https://api.github.com.

MethodRotaDescription
POST/event-subscriptionsCrie uma assinatura.
GET/event-subscriptionsListe suas assinaturas ativas, as mais recentes primeiro.
GET/event-subscriptions/{subscription_id}Faça uma assinatura.
DELETE/event-subscriptions/{subscription_id}Exclua uma assinatura.
GET/event-subscriptions/{subscription_id}/eventsTransmita os eventos da assinatura pela SSE.

Criando uma assinatura

O corpo da solicitação tem dois campos:

  • resource_url: a URL da Web da pull request, na forma https://github.com/OWNER/REPO/pull/NUMBER, ou sua URL da API REST, na forma https://api.github.com/repos/OWNER/REPO/pulls/NUMBER, sem nenhum caminho, consulta ou fragmento extra. Ambas as formas nomeiam a mesma assinatura, e a resposta sempre retorna a URL da Web. As URLs de uma parte de um pull request, como uma revisão, não são aceitas.
  • event_types: um ou mais dos tipos de evento. Tipos de evento desconhecidos retornam 422 Unprocessable Contente a mensagem de erro os nomeia.

As respostas da assinatura incluem id, resource_url, event_types, created_at, expires_at, url e events_url.

Limits

  • Uma assinatura abrange uma pull request.
  • As assinaturas expiram 24 horas depois de serem criadas. Para continuar recebendo eventos, crie uma nova assinatura.
  • Cada usuário, aplicativo e token de instalação pode ter até 100 assinaturas ativas. Criar mais resulta em 422 com a mensagem "Limite de assinatura excedido". Exclua assinaturas que você não precisa mais.

Tipos de evento

| Tipo de evento | Enviado quando | api_url aponta para | | --- | --- | --- | | com.github.pull_request.check_suite.status.changed.v1 | Um conjunto de verificações no commit mais recente da solicitação de pull é concluído, independentemente do resultado. | A suíte de verificações | | com.github.pull_request.head.changed.v1 | O commit de head do pull request é alterado, por exemplo, após um push. | O pull request | | com.github.pull_request.merge_conflict.v1 | GitHub descobre que o pull request tem um conflito de mesclagem. | A pull request | | com.github.pull_request.review.submitted.v1 | Alguém envia uma revisão que aprova, solicita alterações ou comenta. | A análise | | com.github.pull_request.state.changed.v1 | A pull request é mesclada, fechada, reaberta, marcada como pronta para revisão ou convertida em um rascunho. | O pull request |

Um pull request geralmente tem vários conjuntos de verificação, um por aplicativo, portanto, um push pode produzir vários eventos de conjunto de verificação, e uma nova execução produz outro quando é concluída.

Cada comentário individual de revisão, e cada resposta a um comentário de revisão, também conta como uma revisão.

Os eventos atualmente dizem que algo mudou, não o que mudou. Por exemplo, um evento de revisão não inclui o estado da revisão e um evento de alteração de estado não diz se a solicitação de pull foi mesclada ou fechada. Buscar api_url para descobrir.

Os eventos de check suite são a exceção: o campo deles data.conclusion está sempre presente, para que você possa distinguir aprovação de falha sem buscar. É um de success, failure, neutral, cancelled, timed_out, action_required, stale, skipped, startup_failure ou unknown (uma conclusão fora desta lista).

GitHub verifica apenas se há conflitos de mesclagem após alguém exibir ou solicitar o pull request, portanto, eventos de conflito de mesclagem podem levar mais tempo para chegar do que outros eventos.

Formato de evento

Cada evento no fluxo tem três campos:

  • id: a ID do evento
  • event: o tipo de evento
  • data: o evento completo como um CloudEvent JSON de linha única

Lidando com o fluxo

Os fluxos de eventos são conexões de longa duração, portanto, seu cliente precisa lidar com lacunas, eventos repetidos ou fora de ordem e fluxos que terminam. Siga estas práticas para evitar eventos ausentes ou mal tratados.

  • Eventos perdidos: os fluxos entregam eventos somente enquanto estão abertos, sem reprodução. Você não receberá eventos que ocorram:

    • Antes de abrir o fluxo
    • Durante uma breve janela imediatamente após você criar a assinatura
    • Enquanto você está desconectado

    Depois de se inscrever, busque o pull request uma vez para capturar tudo o que você perdeu.

  • Duplicatas e ordenações: você pode receber o mesmo evento mais de uma vez e os eventos de uma solicitação de pull podem chegar fora de ordem. Busque o estado atual de api_url em vez de depender da ordem dos eventos. Para eventos de revisão e de conjunto de verificações, api_url identifica a revisão ou o conjunto de verificações, para que você possa usá-lo para eliminação de duplicação.

  • Pulsações: enquanto o fluxo está ocioso, o servidor envia uma linha de comentário começando com : dentro de 15 segundos do último evento ou comentário. Ignore essas linhas.

  • Encerrando um fluxo: quando o servidor termina um fluxo, seu último evento é github.stream.end, com um outcome em data. Aja com base em outcome, não no campo opcional reason, porque novos valores de reason podem ser adicionados.

    • subscription_ended: a assinatura expirou ou você perdeu o acesso à solicitação de pull. Pare e crie uma nova subscrição se precisar de uma.
    • reconnect: reabra o stream na mesma assinatura. Aguarde com backoff e jitter, e atualize o token primeiro, se ele puder ter expirado.
  • Desconexões inesperadas: se um fluxo terminar sem um github.stream.end evento, reconecte-se.

  • Tokens de instalação: os tokens de instalação expiram após uma hora e os fluxos são abertos com uma extremidade na próxima verificação de acesso após a expiração. Crie um token novo antes de se reconectar. Um GITHUB_TOKEN não pode ser renovado, portanto, exclua as assinaturas que ele criou antes da conclusão do trabalho.

Errors

As respostas de erro incluem message, documentation_urle status.

StatusO que fazer
400O corpo da solicitação não é um objeto JSON. Corrija a solicitação.
401Seu token é inválido ou expirou. Atualize-o e tente novamente uma vez.
403O Event Streams não está habilitado para esta conta, ou você está se autenticando como um aplicativo em vez de como um usuário ou instalação. Não tente novamente.
404A assinatura não existe, expirou ou pertence a outro usuário, ou você não pode acessar o pull request. Não tente novamente.
422O resource_url ou event_types é inválido ou você atingiu o limite de assinaturas. Corrija a solicitação ou exclua assinaturas que você não precisa mais.
503Temporário. Tente novamente após o número de segundos no Retry-After cabeçalho.
500, 504Tente novamente com tempo de espera progressivo.

Limitações conhecidas

  • Nenhum evento de "todas as verificações concluídas": você recebe um evento por conjunto de verificações. Para saber se todas as verificações foram feitas, busque as suítes de verificação do pull request após cada evento.
  • Comentários da conversa da pull request: os comentários na guia de conversa da pull request ainda não produzem eventos. Os comentários de revisão produzem eventos, como eventos de revisão.
  • Fluxos abertos após a exclusão: a exclusão de uma assinatura ainda não fecha seus fluxos abertos. Feche o stream por conta própria antes de excluir a assinatura.
  • Sem reexecução: consulte Manipulando o stream.

Fornecendo comentários

Adoraríamos ouvir o que está funcionando e o que não está. Compartilhe comentários na discussão da Comunidade GitHub.