Skip to main content

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

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

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

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

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

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

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

Рабочий процесс набора проверок

Набор проверок сообщает значение 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.

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

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

Рабочий процесс выполнения проверки

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

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

Заметки выполнения проверки

Проверку также можно выполнить повторно вручную в пользовательском интерфейсе 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 проверок.

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

Проверяет, что данные старше 400 дней архивируются. В процессе архивации GitHub создает состояние фиксации свертки, которое представляет состояние всех проверок для этой фиксации. Как следствие, поле слияния в любом запросе на вытягивание с обязательными проверками архивации будет находиться в заблокированном состоянии, и перед слиянием такого запроса на вытягивание придется повторно запустить эти проверки.