Skip to main content
Skip to content

Uso de flujos de eventos de GitHub

GitHub Event Streams permite a los agentes e integraciones suscribirse a cambios en un recurso en lugar de sondearlos.

Nota:

GitHub Event Streams está en versión preliminar pública vista previa y está sujeto a cambios. Es posible que realicemos cambios incompatibles en la API, los tipos de eventos y los límites con breve aviso durante la versión preliminar.

Acerca de GitHub Event Streams

GitHub Event Streams permite a los agentes e integraciones suscribirse a cambios en un recurso en lugar de sondearlos. Actualmente admite eventos para solicitudes de incorporación de cambios.

Crea una suscripción para una solicitud de incorporación de cambios una vez, mantén una secuencia abierta en ella y GitHub te envía un evento cuando cambia algo a lo que te has suscrito. Después, el cliente puede obtener el estado más reciente de la API REST.

Los eventos se entregan mediante Server-Sent Events (SSE), por lo que el cliente no necesita un punto de conexión público como lo hacen los webhooks. Esto hace que Event Streams sea una buena opción para agentes y herramientas que se ejecutan en la máquina de un desarrollador.

Event Streams solo está disponible en GitHub.com. Aún no está disponible en GHE.com.

Antes de comenzar

  • Acceso: estamos implementando esta característica en una lista de espera. Para unirse a la lista de espera, rellene el formulario de lista de espera y nos pondrá en contacto con usted cuando se le haya concedido acceso a su cuenta. Habilitamos secuencias de eventos por cuenta:

    • Para los tokens de usuario, habilitamos su cuenta de usuario.
    • Para los tokens de instalación de GitHub App, habilitamos al usuario, a la organización o a la empresa en la que está instalada la aplicación. Esto cubre todas las aplicaciones instaladas allí, incluido el GITHUB_TOKEN en GitHub Actions, pero no los tokens de usuario propios de los miembros.

    Las solicitudes de otras cuentas devuelven 403 Forbidden con el mensaje "Las suscripciones de eventos no están habilitadas para esta cuenta".

  • Token: use un token de usuario (un personal access token código de dispositivo, un token de OAuth o un GitHub App token de acceso de usuario) o un GitHub App token de acceso de instalación. Las aplicaciones que se autentican como sí mismas no se admiten.

  • Permisos: el usuario o la instalación necesitan acceso de lectura a la solicitud de incorporación de cambios a la que se suscribe.

Quickstart

En estos ejemplos se usa GitHub CLI (gh) para las llamadas API y curl para el flujo.

1. Crear una suscripción

Reemplace OWNER, REPOy NUMBER por el propietario, el nombre del repositorio y el número de la solicitud de incorporación de cambios.

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)

La respuesta incluye expires_at, events_url y id de la suscripción. La opción --jq .events_url imprime solo events_url, que necesitará en el paso siguiente. Una nueva suscripción devuelve 201 Created. Si ya tiene una suscripción con la misma solicitud de incorporación de cambios y tipos de eventos, volverá a obtener esa suscripción con 200 OK.

2. Abrir el flujo de eventos

Abra el flujo en events_url. gh api espera a la respuesta completa antes de imprimir cualquier cosa, por lo que usa un 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 el flujo antes de desencadenar la actividad que desea ver. El flujo solo entrega eventos que se producen mientras está abierto.

3. Capturar el estado más reciente

Cada evento indica que se ha producido un cambio y proporciona un identificador api_url. Obtén api_url con tu token para leer el estado actual de la revisión o pull request.

4. Eliminar la suscripción

Cuando haya terminado, cierre el flujo. La eliminación de una suscripción no cierra sus flujos abiertos, así que cierre primero el flujo. Enumere las suscripciones activas con gh api /event-subscriptions para encontrar el id de la suscripción. A continuación, elimine la suscripción y reemplace ID por ese valor:

gh api -X DELETE /event-subscriptions/ID

Referencia de las API

Todas las rutas están en https://api.github.com.

MethodRouteDescripción
POST/event-subscriptionsCree una suscripción.
GET/event-subscriptionsEnumere sus suscripciones activas, primero las más recientes.
GET/event-subscriptions/{subscription_id}Suscribirse
DELETE/event-subscriptions/{subscription_id}Elimina una suscripción.
GET/event-subscriptions/{subscription_id}/eventsTransmitir los eventos de la suscripción a través de SSE.

Creación de una suscripción

El cuerpo de la solicitud tiene dos campos:

  • resource_url: la dirección URL web de la solicitud de incorporación de cambios, con el formato https://github.com/OWNER/REPO/pull/NUMBERo su dirección URL de la API REST, en el formulario https://api.github.com/repos/OWNER/REPO/pulls/NUMBER, sin ruta de acceso adicional, consulta o fragmento. Ambas formas designan la misma suscripción y la respuesta siempre devuelve la dirección URL web. Las direcciones URL de una parte de una solicitud de incorporación de cambios, como una revisión, no se aceptan.
  • event_types: uno o varios de los tipos de evento. Los tipos de eventos desconocidos devuelven 422 Unprocessable Content y el mensaje de error los menciona.

Las respuestas de suscripción incluyen id, resource_url, event_types, created_at, expires_at, url y events_url.

Límites

  • Una suscripción cubre una pull request.
  • Las suscripciones expiran 24 horas después de crearse. Para seguir recibiendo eventos, cree una nueva suscripción.
  • Cada usuario, aplicación e token de instalación puede tener hasta 100 suscripciones activas. Crear más devuelve 422 con el mensaje "Límite de suscripción superado". Elimine las suscripciones que ya no necesite.

Tipos de evento

| Tipo de evento | Enviado cuando | api_url apunta a | | --- | --- | --- | | com.github.pull_request.check_suite.status.changed.v1 | Se completa un conjunto de comprobaciones en el commit principal del pull request, independientemente de su conclusión. | El conjunto de comprobación | | com.github.pull_request.head.changed.v1 | El commit HEAD del pull request cambia, por ejemplo, después de un push. | Solicitud de incorporación de cambios | | com.github.pull_request.merge_conflict.v1 | GitHub detecta que la solicitud de incorporación de cambios tiene un conflicto de combinación. | pull request | | com.github.pull_request.review.submitted.v1 | Alguien envía una revisión que aprueba, solicita cambios o deja un comentario. | La revisión | | com.github.pull_request.state.changed.v1 | La solicitud de incorporación de cambios se fusiona, cierra, vuelve a abrir, está marcada como lista para su revisión o se convierte en un borrador. | solicitud de extracción |

Normalmente, una solicitud de incorporación de cambios tiene varios conjuntos de comprobación, uno por aplicación, por lo que una inserción puede producir varios eventos del conjunto de comprobaciones y una nueva ejecución genera otro cuando se completa.

Cada comentario de revisión único y cada respuesta a un comentario de revisión también cuenta como revisión.

Los eventos le indican actualmente que algo ha cambiado, no lo que ha cambiado. Por ejemplo, un evento de revisión no incluye el estado de la revisión y un evento de cambio de estado no indica si la solicitud de incorporación de cambios se ha combinado o cerrado. Recupera api_url para averiguarlo.

Los eventos de check suite son la excepción: su campo data.conclusion siempre está presente, por lo que puede distinguir entre aprobado y fallido sin recuperarlo. Es uno de failure, timed_out, stale, action_required, cancelled, neutral, skipped, startup_failure, unknown o success (una conclusión fuera de esta lista).

GitHub solo comprueba si hay conflictos de combinación después de que alguien vea o solicite la solicitud de incorporación de cambios, por lo que los eventos de conflicto de combinación pueden tardar más tiempo en llegar que otros eventos.

Formato de evento

Cada evento de la secuencia tiene tres campos:

  • id: el identificador del evento
  • event: el tipo de evento
  • data: el evento completo como un elemento JSON CloudEvent de una sola línea

Control del flujo

Los flujos de eventos son conexiones de larga duración, por lo que el cliente debe controlar los huecos, los eventos repetidos o desordenados y los flujos que terminan. Siga estos procedimientos para evitar perder eventos o gestionarlos incorrectamente.

  • Eventos perdidos: los flujos solo entregan eventos mientras están abiertos, sin reproducción. No recibirá eventos que se produzcan:

    • Antes de abrir el flujo
    • Durante una ventana corta inmediatamente después de crear la suscripción
    • Mientras estás desconectado

    Después de suscribirse, recupere la pull request una vez para detectar todo lo que perdió.

  • Duplicados y pedidos: puede recibir el mismo evento más de una vez y los eventos de una solicitud de incorporación de cambios pueden llegar fuera del orden. Recupere el estado actual de api_url en lugar de basarse en el orden de los eventos. Para los eventos de revisión y del conjunto de comprobaciones, api_url identifica la revisión o el conjunto de comprobaciones, por lo que puede usarlo para desduplicar.

  • Latidos: mientras la secuencia está inactiva, el servidor envía una línea de comentario a partir : de 15 segundos del último evento o comentario. Omita estas líneas.

  • Finalizar una secuencia: cuando el servidor finaliza una secuencia, su último evento es github.stream.end, con un outcome en data. Actúe en función de outcome, no del campo opcional reason, ya que se pueden añadir nuevos valores de reason.

    • subscription_ended: la suscripción expiró o perdió el acceso a la solicitud de incorporación de cambios. Detenga y cree una suscripción si necesita una.
    • reconnect: vuelva a abrir la secuencia en la misma suscripción. Desactive con vibración y actualice el token primero si puede haber expirado.
  • Desconexiones inesperadas: si un flujo finaliza sin que se produzca un evento github.stream.end, vuelva a conectar.

  • Tokens de instalación: los tokens de instalación caducan al cabo de una hora, y las transmisiones abiertas con un token de instalación se cierran en la siguiente comprobación de acceso después de su vencimiento. Cree un token nuevo antes de volver a conectarse. GITHUB_TOKEN No se puede renovar , por lo que elimine las suscripciones que creó antes de que finalice el trabajo.

Errors

Las respuestas de error incluyen message, documentation_urly status.

StatusQué hacer
400El cuerpo de la solicitud no es un objeto JSON. Corrija la solicitud.
401El token no es válido o ha expirado. Actualícelo y vuelva a intentarlo una sola vez.
403Los flujos de eventos no están habilitados para esta cuenta o se autentica como una aplicación en lugar de como usuario o instalación. No vuelva a intentarlo.
404La suscripción no existe, ha expirado o pertenece a otro usuario o no puede acceder a la solicitud de incorporación de cambios. No vuelva a intentarlo.
422El resource_url o event_types no es válido, o has alcanzado el límite de suscripciones. Corrija la solicitud o elimine las suscripciones que ya no necesite.
503Temporalmente. Vuelva a intentarlo después del número de segundos indicado en el encabezado Retry-After.
500, 504Vuelva a intentarlo con retroceso.

Limitaciones conocidas

  • Ningún evento "todas las comprobaciones completadas": obtiene un evento por conjunto de comprobaciones. Para saber si se realizan todas las comprobaciones, capture los conjuntos de comprobación de la solicitud de incorporación de cambios después de cada evento.
  • Comentarios de la conversación de la solicitud de incorporación de cambios: los comentarios de la pestaña de conversación de la solicitud de incorporación de cambios aún no generan eventos. Los comentarios de revisión sí lo hacen, como eventos de revisión.
  • Abrir secuencias después de la eliminación: la eliminación de una suscripción aún no cierra sus flujos abiertos. Cierre usted mismo el flujo antes de eliminar la suscripción.
  • Sin repetición: consulte Gestión del flujo.

Enviar comentarios

Nos encantaría escuchar lo que funciona y lo que no funciona. Comparta comentarios en la discusión de la Comunidad de GitHub.