Información general
En vez de proporcionar estados de creación de pase/fallo, las GitHub Apps pueden reportar estados enriquecidos, anotar información detallada en las líneas de código y re-ejecutar las pruebas. La funcionalidad de la API de Verificaciones se encuentra disponible exclusivamente para tus GitHub Apps.
Para obtener un ejemplo de cómo usar Checks API con un GitHub App, vea "Creación de pruebas de CI con Checks API".
Acerca de las suites de verificaciones
Cuando alguien carga código a un repositorio, GitHub crea una suite de verificación para la última confirmación. Un conjunto de comprobaciones es una colección de ejecuciones de comprobación creada por una única aplicación de GitHub para una confirmación concreta. Las suites de Verificación resumen el estado y la conclusión de la ejecución de verificación que incluye dicha suite.
El conjunto de comprobaciones notifica el valor conclusion de prioridad más alta de la ejecución de comprobación del valor conclusion del conjunto de comprobaciones. Por ejemplo, si tres ejecuciones de comprobación tienen las conclusiones timed_out, success y neutral, la conclusión del conjunto de comprobaciones será timed_out.
Predeterminadamente, GitHub crea una suite de verificación automáticamente cuando se carga el código al repositorio. Este flujo predeterminado envía el evento check_suite (con la acción requested) a todas las aplicaciones de GitHub que tengan el permiso checks:write. Cuando la aplicación de GitHub recibe el evento check_suite, puede crear ejecuciones de comprobación para la última confirmación. GitHub agrega automáticamente nuevas ejecuciones de comprobación al conjunto de comprobaciones correcto en función del repositorio de la ejecución de comprobación y SHA.
Si no quieres utilizar el flujo automático predeterminado, puedes controlar cuando creas las suites de verificación. A fin de cambiar la configuración predeterminada para la creación de conjuntos de comprobación, use el punto de conexión Actualización de las preferencias del repositorio para conjuntos de comprobación. Todos los cambios que se realicen en la configuración del flujo automático se registran en la bitácora de auditoría del repositorio. Si ha deshabilitado el flujo automático, puede crear un conjunto de comprobaciones mediante el punto de conexión Crear un conjunto de comprobaciones. Debe seguir usando el punto de conexión Crear una ejecución de comprobación para proporcionar comentarios sobre una confirmación.
El permiso de escritura para la API de Verificaciones solo está disponible para las Github Apps. Las Apps de OAuth y los usuarios autenticados pueden ver las ejecuciones de verificación y las suites de verificación, pero no pueden crearlas. Si no está creando una aplicación de GitHub, puede que le interese la API de estados.
Para usar la API de conjuntos de comprobaciones, la aplicación de GitHub debe tener el permiso checks:write y también se puede suscribir al webhook check_suite.
Para obtener información sobre cómo autenticarse como una aplicación de GitHub, vea "Opciones de autenticación para aplicaciones de GitHub".
Acerca de las ejecuciones de verificación
Una ejecución de verificación es una prueba individual que forma parte de una suite de verificación. Cada ejecución incluye un estado y una conclusión.
Si una ejecución de comprobación permanece en un estado incompleto durante más de 14� días, su valor conclusion se convierte en stale y aparece en GitHub como obsoleta con . Solo GitHub puede marcar las ejecuciones de comprobación como stale. Para más información sobre las posibles conclusiones de una ejecución de comprobación, vea el parámetro conclusion.
En cuanto reciba el webhook check_suite, puede crear la ejecución de comprobación, incluso si la comprobación no está completa. Puede actualizar el valor status de la ejecución de comprobación a medida que se completa con los valores queued, in_progress o completed, y puede actualizar output a medida que haya más detalles disponibles. Una ejecución de verificación puede contener estampas de tiempo, un enlace para encontrar más detalles en tu sitio externo, anotaciones detalladas para líneas de código específcas, e información acerca del análisis que se llevó a cabo.
Una verificación también puede volverse a ejecutar en la IU de GitHub. Vea "Acerca de las comprobaciones de estado" para más información. Cuando esto ocurre, la aplicación de GitHub que ha creado la ejecución de comprobación recibirá el webhook check_run que solicita una nueva ejecución de comprobación. Si creas una ejecución de verificación sin crear una suite de verificación, GitHub la creará para tí automáticamente.
El permiso de escritura para la API de Verificaciones solo está disponible para las Github Apps. Las Apps de OAuth y los usuarios autenticados pueden ver las ejecuciones de verificación y las suites de verificación, pero no pueden crearlas. Si no está creando una aplicación de GitHub, puede que le interese la API de estados.
Para usar Check Runs API, la aplicación de GitHub debe tener el permiso checks:write y también se puede suscribir al webhook check_run.
Ejecuciones de verificación y acciones solicitadas
Cuando configuras una ejecución de verificación con las acciones solicitadas (no se debe confundir esto con GitHub Actions), puedes mostrar un botón en la vista de la solicitud de extracción en GitHub que permita a las personas solicitar tu GitHub App para llevar a cabo tareas adicionales.
Por ejemplo, una app de limpieza de código puede utilizar las acciones solicitadas para mostrar un botón en una solicitud de extracción para arreglar automáticamente los errores de sintaxis detectados.
Para crear un botón que pueda solicitar acciones adicionales a la aplicación, use el objeto actions al crear una ejecución de comprobación. Por ejemplo, el objeto actions siguiente muestra un botón en una solicitud de incorporación de cambios con la etiqueta "Fix this". El botón aparece después de que se completa la ejecución de verificación.
"actions": [{
"label": "Fix this",
"description": "Let us fix that for you",
"identifier": "fix_errors"
}]
Cuando un usuario hace clic en el botón, GitHub envía el webhook check_run.requested_action a la aplicación. Cuando la aplicación recibe un evento de webhook check_run.requested_action, puede buscar la clave requested_action.identifier en la carga del webhook para determinar en qué botón se ha hecho clic y realizar la tarea solicitada.
Para obtener un ejemplo detallado de cómo configurar acciones solicitadas con Checks API, vea "Creación de pruebas de CI con Checks API".