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

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

В этой статье

Обзор

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

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

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

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

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

Может status бытьqueued, , , in_progress``requested``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) всем GitHub приложениям, имеющим разрешение checks:write. Когда ваше приложение GitHub получает событие check_suite, оно может создавать новые проверочные забеги для последнего коммита. GitHub автоматически добавляет новые проверочные пробеги в правильный пакет check suite на основе репозитория и SHA проверки.

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

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

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

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

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

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

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

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

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

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

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

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

Проверку также можно вручную запустить в интерфейсе GitHub. Дополнительные сведения см. в разделе Сведения о проверках состояния . При этом GitHub App созданный запуск проверки получит 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 Enterprise Server. Дополнительные сведения см. в разделе Настройка приложений.

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