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

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

В этой статье

Обзор

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

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

Вы можете использовать состояния с защищенная ветвь, чтобы предотвратить преждевременное объединение запросов на вытягивание. Дополнительные сведения см. в разделе Сведения о защищенных ветвях.

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

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

Может status бытьqueued, , , requested``in_progress``waiting, pendingили completed. Только GitHub Actions может задать состояние requested, waitingили pending.

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

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • stale
  • startup_failure
  • success

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

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

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

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

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

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

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

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

Может status бытьqueued, , , requested``in_progress``waiting, pendingили completed. Только GitHub Actions может задать состояние requested, waitingили pending.

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

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • 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 ниже объект отображает кнопку на вкладке "Проверки " запроса на вытягивание с меткой "Исправить это". Кнопка появляется после завершения выполнения проверки.

"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 с помощью приложения GitHub".

Хранение данных о проверках

GitHub сохраняет данные в течение 400 дней. Через 400 дней данные архивируются. Через 10 дней после архивации данные удаляются окончательно.

Чтобы объединить запрос на вытягивание с проверками, необходимыми и архивными, необходимо повторно запустить проверки.