Использование REST API для взаимодействия с проверками

Общие сведения

Вместо двоичных состояний выполнения и сбоя сборки GitHub Apps может сообщать о расширенных состояниях, примечать строки кода с подробными сведениями и повторно выполнять тесты. REST API для управления проверками доступен исключительно для приложений GitHub.

Пример использования REST API с GitHub App см. в разделе Создание тестов CI с помощью API проверок.

Сведения о наборах проверок

Когда кто-нибудь отправляет код в репозиторий, GitHub создает набор проверок для последней фиксации. Набор проверок — это коллекция запусков проверок, созданных одним приложением GitHub для определенной фиксации. Набор проверок позволяет получить общее заключение о состоянии выполнения проверок, входящих в состав набора.

Может status иметь значение queued, in_progressили complete.

Если состояние равно complete, вывод может быть любым из следующих:

• action_required
• cancelled
• timed_out
• failure
• neutral
• success

Набор проверок сообщает значение conclusion выполнения проверки с наивысшим приоритетом из всех значений conclusion набора проверок. Например, если для трех выполнений проверок получены заключения timed_out, success и neutral, заключением для набора проверок будет timed_out.

По умолчанию GitHub автоматически создает набор проверок при отправке кода в репозиторий. В рамках этого процесса по умолчанию событие check_suite (с действием requested) отправляется всем приложениям GitHub с разрешением checks:write. Когда приложение GitHub получает событие check_suite, оно может создать новые выполнения проверок для последней фиксации. GitHub автоматически добавляет новые выполнения проверок в соответствующий набор проверок с учетом репозитория и SHA.

Если вы не хотите использовать автоматический процесс по умолчанию, то можете управлять созданием наборов проверок. Чтобы изменить параметры по умолчанию для создания наборов проверок, используйте конечную точку обновления параметров наборов проверок для репозитория. Все изменения параметров автоматического процесса записываются в журнал аудита репозитория. Если вы отключили автоматический процесс, набор проверок можно создать с помощью конечной точки создания набора проверок. Далее следует использовать конечную точку создания выполнения проверки для предоставления отзывов о фиксации.

Разрешение на запись для REST API для взаимодействия с проверками доступно только для GitHub Apps. OAuth Apps и пользователи, прошедшие проверку подлинности, могут просматривать проверки и наборы проверок, но не могут создавать их. Если вы не создаете GitHub App, вас может заинтересовать использование REST API для взаимодействия с состояниями фиксации.

Чтобы использовать конечные точки для управления наборами проверок, GitHub App должен иметь checks:write разрешение и также может подписаться на веб-перехватчик check_suite .

Сведения о том, как пройти проверку подлинности в качестве приложения GitHub, см. в разделе Сведения о проверке подлинности с помощью приложения GitHub.

Сведения о выполнениях проверок

Выполнение проверки — это отдельный тест, входящий в состав набора проверок. Каждое выполнение имеет состояние и заключение.

Состояние может быть queued, in_progressили complete.

Если состояние равно completed, вывод может быть любым из следующих:

• action_required
• cancelled
• timed_out
• failure
• neutral
• success

Если выполнение проверки находится в незавершенном состоянии дольше 14 дней, его значение conclusion становится равным stale и выполнение отображается на GitHub как устаревшее со значком . Выполнения проверок могут помечаться как stale только на GitHub. Дополнительные сведения о возможных заключениях для выполнения проверки см. в описании параметра conclusion.

Как только вы получите веб-перехватчик check_suite, вы можете создать выполнение проверки, даже если проверка не завершена. Вы можете изменить состояние (status) выполнения проверки после его завершения на значение queued, in_progress или completed, а также обновлять output по мере получения дополнительных сведений. Выполнение проверки может содержать метки времени, ссылку на дополнительные сведения на внешнем сайте, подробные заметки для определенных строк кода и сведения о проведенном анализе.

Заметки добавляют сведения из выполнения проверки в определенные строки кода. Каждая заметка annotation_level содержит свойство , которое может иметь значение notice, warningили failure. Заметка также включает path, start_lineи end_line , чтобы указать, на какое расположение ссылается заметка. Заметка содержит для message описания результата. Дополнительные сведения см. в разделе Проверка запусков справочной документации по REST API.

Проверку также можно выполнить повторно вручную в пользовательском интерфейсе GitHub. Дополнительные сведения см. в разделе Сведения о проверках состояния. В этом случае приложение GitHub, создавшее выполнение проверки, получит веб-перехватчик check_run, запрашивающий новое выполнение проверки. Если вы создаете выполнение проверки без набора проверок, GitHub создает набор проверок автоматически.

Разрешение на запись для REST API для взаимодействия с проверками доступно только для GitHub Apps. OAuth Apps и пользователи, прошедшие проверку подлинности, могут просматривать проверки и наборы проверок, но не могут создавать их. Если вы не создаете GitHub App, вас может заинтересовать использование REST API для взаимодействия с состояниями фиксации.

Чтобы использовать конечные точки для управления проверками, GitHub App должен иметь checks:write разрешение и также может подписаться на веб-перехватчик check_run .

Выполнения проверок и запрошенные действия

При настройке выполнения проверки с запрошенными действиями (не путать с GitHub Actions) в представлении запроса на вытягивание на GitHub можно отобразить кнопку, с помощью которой пользователь может запросить у GitHub App выполнение дополнительных задач.

Например, приложение для анализа кода может использовать запрошенные действия с целью отображения в запросе на вытягивание кнопки для автоматического исправления обнаруженных синтаксических ошибок.

Чтобы создать кнопку для запроса дополнительных действий в приложении, используйте объект actions при создании выполнения проверки. Например, приведенный ниже объект actions отображает в запросе на вытягивание кнопку с меткой Fix this (Исправить). Кнопка появляется после завершения выполнения проверки.

"actions": [{
   "label": "Fix this",
   "description": "Let us fix that for you",
   "identifier": "fix_errors"
 }]

Когда пользователь нажимает эту кнопку, GitHub отправляет в приложение веб-перехватчик check_run.requested_action. Когда приложение получает событие веб-перехватчика check_run.requested_action, оно может найти ключ requested_action.identifier в полезных данных веб-перехватчика, чтобы определить, какая кнопка была нажата, и выполнить запрошенную задачу.

Подробный пример настройки запрошенных действий с помощью REST API см. в разделе Создание тестов CI с помощью API проверок.