# 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.

> [!NOTE]
> 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](https://gh.io/event-streams-signup) 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](https://cli.github.com/) (`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.

```shell
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`:

```shell
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:

```shell
gh api -X DELETE /event-subscriptions/ID
```

## Referência de API

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

| Method | Rota | Description |
| --- | --- | --- |
| `POST` | `/event-subscriptions` | Crie uma assinatura. |
| `GET` | `/event-subscriptions` | Liste 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}/events` | Transmita 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 Content`e 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](https://cloudevents.io/) 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_url`e `status`.

| Status | O que fazer |
| --- | --- |
| `400` | O corpo da solicitação não é um objeto JSON. Corrija a solicitação. |
| `401` | Seu token é inválido ou expirou. Atualize-o e tente novamente uma vez. |
| `403` | O 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. |
| `404` | A assinatura não existe, expirou ou pertence a outro usuário, ou você não pode acessar o pull request. Não tente novamente. |
| `422` | O `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. |
| `503` | Temporário. Tente novamente após o número de segundos no `Retry-After` cabeçalho. |
| `500`, `504` | Tente 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](#handling-the-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](https://github.com/orgs/community/discussions/211595).