{"meta":{"title":"Uso de la API REST para interactuar con comprobaciones","intro":"Puede usar la API REST para compilar GitHub Apps que ejecute comprobaciones eficaces en los cambios de código de un repositorio. Puedes crear apps que lleven a cabo integración contínua, limpieza de código, o servicios de escaneo de código y que proporcionen retroalimentación detallada en las confirmaciones.","product":"REST API","breadcrumbs":[{"href":"/es/enterprise-cloud@latest/rest","title":"REST API"},{"href":"/es/enterprise-cloud@latest/rest/guides","title":"Guías"},{"href":"/es/enterprise-cloud@latest/rest/guides/using-the-rest-api-to-interact-with-checks","title":"Introducción: Comprobaciones"}],"documentType":"article"},"body":"# Uso de la API REST para interactuar con comprobaciones\n\nPuede usar la API REST para compilar GitHub Apps que ejecute comprobaciones eficaces en los cambios de código de un repositorio. Puedes crear apps que lleven a cabo integración contínua, limpieza de código, o servicios de escaneo de código y que proporcionen retroalimentación detallada en las confirmaciones.\n\n## Información general\n\nEn 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.\n\nPara 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](/es/enterprise-cloud@latest/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app#step-26-automatically-fix-rubocop-errors).\n\nPuede usar estados con [ramas protegidas](/es/enterprise-cloud@latest/rest/repos#branches) 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](/es/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging).\n\n## Acerca de los conjuntos de verificaciones\n\nCuando 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](/es/enterprise-cloud@latest/rest/checks#check-runs) 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.\n\n`status` puede ser `queued`, `in_progress`, `requested`, `waiting`, `pending` o `completed`. Solo GitHub Actions puede establecer un estado de `requested`, `waiting`o `pending`.\n\nSi el estado es `completed`, la conclusión puede ser cualquiera de las siguientes:\n\n* `action_required`\n* `cancelled`\n* `timed_out`\n* `failure`\n* `neutral`\n* `skipped`\n* `stale`\n* `startup_failure`\n* `success`\n\nEl 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`.\n\nDe 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](/es/enterprise-cloud@latest/rest/checks#check-suites) correcto en función del repositorio de la ejecución de comprobación y SHA.\n\nSi 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](/es/enterprise-cloud@latest/rest/checks/suites#update-repository-preferences-for-check-suites). 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](/es/enterprise-cloud@latest/rest/checks/suites#create-a-check-suite). Debe seguir usando el punto de conexión [Crear una ejecución de comprobación](/es/enterprise-cloud@latest/rest/checks/runs#create-a-check-run) para proporcionar comentarios sobre una confirmación.\n\nEl 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](/es/enterprise-cloud@latest/rest/commits#commit-statuses).\n\nPara 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](/es/enterprise-cloud@latest/webhooks/webhook-events-and-payloads#check_suite).\n\nPara 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](/es/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app).\n\n## Acerca de las ejecuciones de comprobación\n\nUna 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.\n\n`status` puede ser `queued`, `in_progress`, `requested`, `waiting`, `pending` o `completed`. Solo GitHub Actions puede establecer un estado de `requested`, `waiting`o `pending`.\n\nSi el estado es `completed`, la conclusión puede ser cualquiera de las siguientes:\n\n* `action_required`\n* `cancelled`\n* `timed_out`\n* `failure`\n* `neutral`\n* `skipped`\n* `success`\n\nSi 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`](/es/enterprise-cloud@latest/rest/checks#create-a-check-run--parameters).\n\nEn cuanto reciba el webhook [`check_suite`](/es/enterprise-cloud@latest/webhooks/webhook-events-and-payloads#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.\n\nLas 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](/es/enterprise-cloud@latest/rest/checks/runs).\n\nUna comprobación también se puede volver a ejecutar manualmente en la interfaz de usuario de GitHub. Consulta [Comprobaciones de estado](/es/enterprise-cloud@latest/pull-requests/reference/status-checks#checks) para obtener más detalles. Cuando esto ocurre, el GitHub App que creó la ejecución de comprobación recibirá el [`check_run`](/es/enterprise-cloud@latest/webhooks/webhook-events-and-payloads#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.\n\nEl 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](/es/enterprise-cloud@latest/rest/commits#commit-statuses).\n\nPara usar los endpoints para gestionar las comprobaciones, GitHub App debe tener el permiso `checks:write` y también puede suscribirse al webhook [check\\_run](/es/enterprise-cloud@latest/webhooks/webhook-events-and-payloads#check_run).\n\n## Ejecuciones de verificación y acciones solicitadas\n\nCuando 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.\n\nPor 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.\n\nPara crear un botón que pueda solicitar acciones adicionales a la aplicación, use el [objeto `actions`](/es/enterprise-cloud@latest/rest/checks/runs#create-a-check-run--parameters) al [crear una ejecución de comprobación](/es/enterprise-cloud@latest/rest/checks#create-a-check-run). 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.\n\n```json\n\"actions\": [{\n \"label\": \"Fix this\",\n \"description\": \"Let us fix that for you\",\n \"identifier\": \"fix_errors\"\n}]\n```\n\nCuando un usuario hace clic en el botón, GitHub envía el [`check_run.requested_action` webhook](/es/enterprise-cloud@latest/webhooks/webhook-events-and-payloads#check_run) 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.\n\nPara 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](/es/enterprise-cloud@latest/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app).\n\n## Retención de los datos de las comprobaciones\n\nGitHub conserva los datos de comprobaciones durante 400 días. Después de 400 días, los datos se archivan. 10 días después del archivado, los datos se eliminan permanentemente.\n\nPara combinar una solicitud de incorporación de cambios con comprobaciones necesarias y archivadas, debe volver a ejecutar las comprobaciones."}