Información general
En lugar de los estados binarios de éxito/error de la compilación, GitHub Apps puede informar de estados más completos, anotar líneas de código con información detallada y volver a ejecutar las pruebas. La API REST para administrar comprobaciones está disponible exclusivamente para las aplicaciones de GitHub.
Para ver un ejemplo de cómo usar la API REST con un GitHub App, consulte 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 los conjuntos de verificaciones
Cuando alguien inserta código en un repositorio, GitHub crea un conjunto de comprobaciones 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 puede establecer un estado de requested, waitingo 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.
De forma predeterminada, GitHub crea automáticamente un conjunto de comprobaciones cuando el código se inserta en el repositorio. Este flujo predeterminado envía el evento check_suite (con la acción requested) a todas las aplicaciones de GitHub que tienen el permiso checks:write. Cuando la aplicación de GitHub recibe el evento check_suite, puede crear nuevas ejecuciones de comprobación para la confirmación más reciente. 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 endpoints para administrar suites de comprobación, GitHub App debe tener el permiso checks:write y también puede suscribirse 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 comprobació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 puede establecer un estado de requested, waitingo 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, el conclusion de la ejecución de comprobación pasa a 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 la comprobación, incluso si ésta no ha finalizado. Puede actualizar el status de la ejecución de comprobación a medida que se completa con los valores queued, in_progress o completed, y puede actualizar el output cuando haya más detalles disponibles. Una ejecución de verificación puede contener marcas de tiempo, un enlace para encontrar más detalles en tu sitio externo, anotaciones detalladas para líneas de código específicas, 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 comprobación también se puede volver a ejecutar manualmente en la interfaz de usuario de GitHub. Consulta Acerca de las verificaciones de estado para obtener más detalles. Cuando esto ocurre, el GitHub App que creó la ejecución de comprobación recibirá el check_run webhook que solicita una nueva ejecución de comprobación. Si creas un check run sin crear una check suite, GitHub crea la check suite 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 endpoints para gestionar las comprobaciones, GitHub App debe tener el permiso checks:write y también puede suscribirse al webhook check_run.
Ejecuciones de verificación y acciones solicitadas
Cuando configuras una ejecución de comprobación con acciones solicitadas (no debe confundirse con GitHub Actions), puedes mostrar un botón en la vista de pull request en GitHub que permite a los usuarios solicitar a tu GitHub App que realice 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 la 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 check_run.requested_action webhook 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 más información, consulta Configuración de aplicaciones.
Para combinar una solicitud de incorporación de cambios con comprobaciones necesarias y archivadas, debe volver a ejecutar las comprobaciones.