Nota:
Los estados de incidencia están en Vista previa y solo están disponibles para las cuentas inscritas en la versión preliminar. Las cargas de webhook y el status_changed tipo de actividad están sujetos a cambios.
Acerca de los eventos de cambio de estado
Cuando cambia el estado de un problema, GitHub envía un issues evento de webhook con la status_changed acción . Las cargas de cada issues acción también incluyen el estado actual del problema en issue.status. Puede usar estos eventos para mantener otras herramientas sincronizadas con sus problemas o para ejecutar un GitHub Actions flujo de trabajo cuando un problema alcanza un estado determinado.
Los estados solo se incluyen en las incidencias de los repositorios que usan estados de las incidencias. Para otros problemas, los payloads no incluyen issue.status y GitHub no envía status_changed.
Para obtener el esquema de carga completa, consulte Eventos y cargas de webhook.
Objetos de estado
Las cargas de webhook describen cada estado con un objeto que tiene tres propiedades.
| Property | Type | Description |
|---|---|---|
id | Integer | Identificador del estado. |
name | String | Nombre para mostrar del estado, como In progress. El nombre puede cambiar. |
category | String | Categoría del estado, como duplicate, not_planned, completed, started, planned o backlog. Se pueden agregar más categorías en el futuro. |
Más de un estado puede pertenecer a la misma categoría. Por ejemplo, En curso y En revisión pertenecen a la started categoría . Para que coincida con un estado en el código o flujo de trabajo, use su id. Para hacer coincidir cada estado de una categoría, use su category. No coincida con en name.
issue.status es null cuando la incidencia no tiene un estado. Por ejemplo, un problema que se creó antes de que los estados estuvieran disponibles en su repositorio no tiene ningún estado hasta que alguien establezca uno o hasta que se cierre o vuelva a abrir el problema.
La carga útil de status_changed
Además issuede , repository, sendery las demás propiedades que incluye cada issues carga, una status_changed carga incluye las siguientes propiedades. Para esta acción, sender es la persona o aplicación que cambió el estado.
| Property | Description |
|---|---|
status | Estado al que cambió el problema. |
changes.status.from | El estado que tenía el problema antes del cambio o null si no tenía uno. |
changes.state.from | |
El state anterior del problema, open o closed. Solo se incluye cuando el cambio de estado también cerró o reabrió el problema. | |
changes.state_reason.from | El state_reason anterior de la incidencia. Solo se incluye cuando el cambio de estado también cambió el motivo del estado, por ejemplo, cerrando o reabrindo el problema, o cambiando por qué está cerrado. |
Es null cuando el problema no tenía un motivo de estado, por ejemplo la primera vez que se cierra. |
Valores capturados y la incidencia actual
Las propiedades status y changes describen el cambio en el momento en que se guardó. La issue propiedad , incluida issue.status, describe el problema cuando se creó la entrega, igual que para todas las demás issues acciones. Si el problema cambia de nuevo antes de entonces, issue.status puede diferir de status. Por ejemplo, si alguien mueve una incidencia de In progress a In review (En curso) y, a continuación, a Done (Listo), la entrega del primer cambio puede tener un issue.status valor de Listo.
Para averiguar qué ha hecho un cambio determinado, use status y changes. Una carga retrasada, reintentada o reenviada puede ser obsoleta, por lo que es posible que issue.status no sea el estado más reciente del problema. Para obtener más información, vea Entrega, más adelante en este artículo.
Cuándo status_changed se envía
GitHub envía status_changed cada vez que cambia el estado de un problema, incluidos los cambios que realiza GitHub cuando se crea, cierra o vuelve a abrir un problema.
- Establecer un estado: alguien elige un estado diferente para un problema.
- Creación de una incidencia: una incidencia nueva obtiene el estado Trabajo pendiente, a menos que la persona que la crea elija otro estado.
changes.status.fromesnull. GitHub envíaopened, así comostatus_changed. - Establecer un primer estado: un problema existente sin un estado obtiene uno.
changes.status.fromesnull. - Cerrar o volver a abrir un problema: Al cerrar un problema como completado, se establece el estado Listo; cerrarlo como no planificado establece No planificado y cerrarlo como duplicado establece Duplicado. Volver a abrir un problema sin elegir un estado establece Backlog.
GitHub envía
closedoreopened, así comostatus_changed. - Vinculación de una solicitud de incorporación de cambios: la vinculación de una solicitud de incorporación de cambios abierta a un problema abierto que no tiene ningún estado, o que tiene el estado Trabajo pendiente o Pendiente, mueve el problema a En curso.
senderes la persona o aplicación que vinculó la solicitud de incorporación de cambios. Si no pueden elegir un estado para el problema, el estado no cambia.
GitHub no envía status_changed en estos casos:
- El estado no cambia, por ejemplo, cuando alguien elige el estado que el problema ya tiene.
- La incidencia se transfiere a otro repositorio. La nueva incidencia mantiene su estado, que la
transferredpayload incluye enchanges.new_issue.status.
Cambios de estado que cierran o vuelven a abrir un problema
Los estados de completed, not_planned y duplicate son para incidencias cerradas. Elegir uno de estos estados para un problema abierto cierra el problema y elegir un estado en cualquier otra categoría para un problema cerrado lo vuelve a abrir.
Cuando un cambio de estado cierra o vuelve a abrir un problema, GitHub envía dos entregas: status_changedy closed o reopened. Las dos entregas pueden llegar en cualquier orden.
Cambiar un problema cerrado a un estado con un motivo de cierre diferente, por ejemplo, de Listo a No planeado, envía status_changed con changes.state_reason pero sin changes.state.
GitHub también envía otra closed entrega con el nuevo state_reason.
Si la integración también controla status_changed así como closed o reopened, asegúrese de que puede controlar el mismo cambio notificado por ambas entregas.
Entrega
GitHub entrega status_changed de la misma manera que otros eventos de webhook. La entrega no está garantizada.
GitHub no garantiza que cada cambio se entregue exactamente una vez o que las entregas lleguen en el orden en que se produjeron los cambios.
- Entregas fallidas: una entrega puede fallar, por ejemplo, si el servidor no está disponible. GitHub no vuelve a entregar automáticamente las entregas con error, pero usted puede volver a entregarlas. Para obtener más información, vea Gestión de entregas fallidas de webhooks.
- Entregas repetidas: puede recibir la misma entrega más de una vez, por ejemplo, cuando se vuelve a entregar. Una reentrega tiene el mismo
X-GitHub-Deliveryencabezado que la entrega original, por lo que puede usar el encabezado para omitir las entregas que ya ha procesado. - Pedido: Las entregas pueden llegar fuera de orden y las cargas retrasadas, reintentadas o reenviadas pueden ser obsoletas, incluidas
issue.status. No use el orden en el que llegan las entregas para determinar el estado más reciente de una incidencia.
Para obtener el estado más reciente de un problema, recupere el problema con la API REST. Para obtener más información, vea Puntos de conexión de la API de REST para incidencias. En los repositorios propiedad de una organización, la respuesta incluye status para cualquier solicitud autenticada, incluidas las solicitudes autenticadas como una GitHub App instalación y las solicitudes que usan GITHUB_TOKEN en un flujo de trabajo. Durante el Vista previa, en repositorios propiedad de una cuenta personal, la respuesta solo incluye status cuando la solicitud se realiza en nombre de un usuario que tiene acceso a la versión preliminar. Si la respuesta no incluye status, use el estado de las entregas con cuidado, ya que una entrega que llega más adelante puede llevar un estado anterior.
Quién puede cambiar un estado
Las personas con acceso de triaje o superior a un repositorio pueden elegir el estado de sus incidencias. Se aplican reglas de permisos adicionales a roles personalizados, aplicaciones, flujos de trabajo y cuentas personales:
- Roles de repositorio personalizados: en repositorios propiedad de una organización, las personas con un rol personalizado que hereda el rol Triage, Write o Maintain pueden elegir los estados. Las personas con un rol personalizado que hereda el rol Read no pueden elegir los estados, incluso si el rol puede establecer tipos de problema.
- Aplicaciones y flujos de trabajo: En repositorios propiedad de una organización, GitHub Apps con acceso de escritura para el permiso de repositorio "Issues" también pueden elegir estados, incluidos los flujos de trabajo que usan
GITHUB_TOKENcon el permisoissues: write. - Cuentas personales: durante Vista previa, en repositorios propiedad de una cuenta personal, solo las personas que tienen acceso a la versión preliminar pueden elegir los estados.
Elegir un estado que cierre o vuelva a abrir un problema también requiere permiso para cerrar o volver a abrir el problema. Cambiar por qué se cierra un problema cerrado, por ejemplo, de Listo a No planeado, requiere permiso para cerrarlo y volver a abrirlo.
Las personas que no pueden elegir un estado todavía pueden cambiarlo cerrando o reabriendo un problema. Por ejemplo, el autor de una incidencia puede cerrarla y volver a abrirla con acceso de lectura al repositorio, lo que establece el estado predeterminado para el nuevo estado. Estos cambios también envían status_changed, y sender es la persona que cerró o volvió a abrir el problema.
Ejecutar un flujo de trabajo cuando cambia el estado
Para ejecutar un GitHub Actions flujo de trabajo cuando cambie el estado de un problema, use el status_changed tipo de actividad del issues evento. El flujo de trabajo se ejecuta cada vez que cambia el estado de una incidencia. En el flujo de trabajo, las siguientes propiedades del github.event contexto describen el cambio.
github.event.statuscontiene el estado al que cambió el problema.github.event.changes.status.fromcontiene el estado anterior onullsi el problema no tenía uno.github.event.issue.statuscontiene el estado de la incidencia cuando se creó la carga. Las cargas de cada tipo de actividadissuesincluyen esta propiedad.
Importante
Flujos de trabajo que usan el evento issues sin types también se ejecutan para status_changed. Estos flujos de trabajo se ejecutan cada vez que alguien cambia el estado de una incidencia y se ejecutan una vez más cuando se crea, cierra o vuelve a abrir una incidencia, ya que GitHub envía status_changed, así como closed, opened o reopened. Para evitar ejecuciones inesperadas, enumere los tipos de actividad que necesita el flujo de trabajo.
Durante el Vista previa, los editores que validan los archivos de flujo de trabajo, como el editor de flujo de trabajo en GitHub, pueden informar status_changed como un tipo de actividad no válido. Puede omitir este error.
Para ver flujos de trabajo de ejemplo que coinciden con un estado por su identificador y cada estado de una categoría, consulte Eventos que desencadenan flujos de trabajo.
Cargas útiles de ejemplo
Los siguientes extractos muestran las propiedades de los payloads de status_changed que describen el cambio. Las cargas completas también incluyen los objetos repository, sender y issue completos, y otras propiedades.
Crear un problema
Cuando alguien crea un problema sin elegir un estado, el problema obtiene el estado Backlog.
changes.status.from es nully changes no incluye state ni state_reason.
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "open",
"state_reason": null,
"status": {
"id": 2,
"name": "Backlog",
"category": "backlog"
}
},
"status": {
"id": 2,
"name": "Backlog",
"category": "backlog"
},
"changes": {
"status": {
"from": null
}
}
}
Cambiar a un estado en la misma categoría
Mover un problema de In progress a In review no cambia su estado o su categoría, por lo que changes solo incluye status.
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "open",
"state_reason": null,
"status": {
"id": 8,
"name": "In review",
"category": "started"
}
},
"status": {
"id": 8,
"name": "In review",
"category": "started"
},
"changes": {
"status": {
"from": {
"id": 4,
"name": "In progress",
"category": "started"
}
}
}
}
Cerrar una incidencia cambiando su estado
Al mover un problema de In review a Done, se cierra el problema.
changes.state.from es open, y changes.state_reason.from es null porque el problema no tenía un motivo de estado antes.
GitHub también envía una closed implementación para este cambio.
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "closed",
"state_reason": "completed",
"status": {
"id": 5,
"name": "Done",
"category": "completed"
}
},
"status": {
"id": 5,
"name": "Done",
"category": "completed"
},
"changes": {
"status": {
"from": {
"id": 8,
"name": "In review",
"category": "started"
}
},
"state": {
"from": "open"
},
"state_reason": {
"from": null
}
}
}