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 API REST para administrar las comprobaciones está disponible exclusivamente para las GitHub Apps.
Para ver un ejemplo de cómo usar la API REST con GitHub App, consulta Creación de comprobaciones de CI con una aplicación de GitHub.
Puede usar estados con ramas protegidas para impedir que los usuarios combinen solicitudes de incorporación de cambios antes de tiempo. Para más información, consulta Acerca de las ramas protegidas.
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.
status puede ser queued, in_progress, requested, waiting, pending o completed. Solo GitHub Actions pueden establecer un estado de requested, waiting o pending.
Si el estado es completed, la conclusión puede ser cualquiera de las siguientes:
action_requiredcancelledtimed_outfailureneutralskippedstalestartup_failuresuccess
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 que la API REST interactúe con comprobaciones solo está disponible para GitHub Apps. OAuth apps y los usuarios autenticados pueden ver las ejecuciones y los conjuntos de comprobación, pero no pueden crearlos. Si no va a crear GitHub App, es posible que le interese usar la API de REST para interactuar con los estados de confirmación.
Para usar los puntos de conexión para administrar conjuntos de pruebas, la aplicación de GitHub App 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, consulta "Acerca de la autenticación con una aplicación 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.
status puede ser queued, in_progress, requested, waiting, pending o completed. Solo GitHub Actions pueden establecer un estado de requested, waiting o pending.
Si el estado es completed, la conclusión puede ser cualquiera de las siguientes:
action_requiredcancelledtimed_outfailureneutralskippedsuccess
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.
Las anotaciones agregan información de la ejecución de comprobación a líneas de código específicas. Cada anotación incluye una propiedad annotation_level, que puede ser notice, warning o failure. La anotación también incluye path, start_line y end_line para especificar a qué ubicación hace referencia. La anotación incluye un objeto message para describir el resultado. Para más información, consulta Puntos de conexión de la API de REST para ejecuciones de comprobación.
Una verificación también puede volverse a ejecutar en la IU de GitHub. Consulta Acerca de las verificaciones de estado para obtener más detalles. Cuando esto ocurre, la la creará para ti automáticamente.
El permiso de escritura para que la API REST interactúe con comprobaciones solo está disponible para GitHub Apps. OAuth apps y los usuarios autenticados pueden ver las ejecuciones y los conjuntos de comprobación, pero no pueden crearlos. Si no va a crear GitHub App, es posible que le interese usar la API de REST para interactuar con los estados de confirmación.
Para usar los puntos de conexión para administrar ejecuciones de pruebas, la aplicación de GitHub App 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 la pestaña Comprobaciones de una solicitud de incorporación de cambios con la etiqueta "Arreglar esto". 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 ver un ejemplo detallado de cómo configurar acciones solicitadas con la API REST, consulta Creación de comprobaciones de CI con una aplicación de GitHub.
Retención de los datos de las comprobaciones
Los administradores del sitio pueden controlar la directiva de retención para comprobar los datos de tu instancia de GitHub Enterprise Server. Para obtener más información, vea «Configuración de aplicaciones».
Para combinar una solicitud de incorporación de cambios con comprobaciones necesarias y archivadas, debe volver a ejecutar las comprobaciones.