Примечание.
GitHub Потоки событий включено Публичный предварительный просмотр и подлежит изменению. Мы можем внести критические изменения в API, типы событий и ограничения с коротким уведомлением во время предварительной версии.
Сведения о GitHub потоках событий
GitHub Потоки событий позволяют агентам и интеграции подписываться на изменения ресурса вместо опроса. В настоящее время он поддерживает события для запросов на вытягивание.
Вы создаете подписку для запроса на вытягивание один раз, держите поток открытым в нем и GitHub отправляет событие, когда вы подписаны на изменения. Затем клиент может получить последнее состояние из REST API.
События доставляются по Server-Sent событиям (SSE), поэтому клиенту не нужна общедоступная конечная точка таким образом, как выполняются веб-перехватчики. Это делает Потоки событий хорошим подходом для агентов и инструментов, работающих на компьютере разработчика.
Потоки событий доступны только в GitHub.com. Он еще недоступен GHE.com .
Перед началом
-
Доступ: мы развертываем эту функцию на основе списка ожидания. Чтобы присоединиться к списку ожидания, заполните форму списка ожидания и обратитесь к вам, когда ваша учетная запись была предоставлена. Мы включите потоки событий для каждой учетной записи:
- Для маркеров пользователей мы включите учетную запись пользователя.
- Для GitHub App маркеров установки мы включаем пользователя, организацию или предприятие, в котором установлено приложение. Это касается всех установленных там приложений, включая
GITHUB_TOKENGitHub Actionsего, но не собственные маркеры пользователей.
Запросы из других учетных записей возвращаются
403 Forbiddenс сообщением "Подписки на события не включены для этой учетной записи". -
Маркер: используйте маркер пользователя (маркер personal access tokenOAuth или маркер доступа пользователя) или GitHub App GitHub App маркер доступа к установке. Приложения, проверяющие подлинность как сами по себе, не поддерживаются.
-
Разрешения: пользователю или установке требуется доступ на чтение к запросу на вытягивание, на который вы подписаны.
Quickstart
В этих примерах используется GitHub CLI (gh) для вызовов API и curl потока, чтобы вы могли видеть каждый шаг API. Если вы используете GitHub CLI версию 2.105.0 или более поздней версии, gh event команды обрабатывают подписку, потоковую передачу и повторное подключение. См. статью "Использование GitHub CLI команд".
1. Создание подписки
Замените OWNER, REPOа NUMBER также владельцем запроса на вытягивание, именем репозитория и номером.
EVENTS_URL=$(gh api -X POST /event-subscriptions \
-f resource_url=https://github.com/OWNER/REPO/pull/NUMBER \
-f 'event_types[]=com.github.pull_request.review.submitted.v1' \
-f 'event_types[]=com.github.pull_request.state.changed.v1' \
--jq .events_url)
Ответ включает в себя подписку idи expires_at``events_url. Параметр --jq .events_url печатает только events_urlнужный вариант на следующем шаге. Возвращается новая подписка 201 Created. Если у вас уже есть подписка с одинаковым запросом на вытягивание и типами событий, вы получите эту подписку обратно 200 OK.
2. Открытие потока событий
Откройте поток в events_url.
gh api Ожидает всего ответа перед печатью, поэтому используйте клиент потоковой передачи, например curl -N:
curl -sS -N -H 'Accept: text/event-stream' \
-H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
"$EVENTS_URL"
Откройте поток перед активацией действия, которое вы хотите увидеть. Поток предоставляет только события, которые происходят во время его открытия.
3. Получение последнего состояния
Каждое событие указывает, что произошло изменение и предоставляется api_url.
api_url Получите маркер, чтобы прочитать текущее состояние запроса на проверку или вытягивание.
4. Удаление подписки
По завершении закройте поток. Удаление подписки не закрывает открытые потоки, поэтому сначала закройте поток. Перечислите активные подписки, gh api /event-subscriptions чтобы найти подписку id. Затем удалите подписку, заменив ID это значение:
gh api -X DELETE /event-subscriptions/ID
Использование GitHub CLI команд
GitHub CLI 2.105.0 и более поздних версий включают gh event команды для потоков событий. Эти команды также находятся и Публичный предварительный просмотр подвергаются изменению.
Чтобы дождаться события в запросе на вытягивание, выполните команду gh event listen с URL-адресом запроса на вытягивание и одним или несколькими типами событий:
gh event listen --resource https://github.com/OWNER/REPO/pull/NUMBER \
--event com.github.pull_request.review.submitted.v1,com.github.pull_request.state.changed.v1
gh event listen создает подписку или повторно использует существующую для одного и того же запроса на вытягивание и типов событий. Затем он открывает поток и выводит каждое событие в виде одной строки JSON. Он повторно подключается при удалении потока и создает подписку снова, если срок действия истекает.
- По умолчанию команда завершает работу после первого события. Это подходит для агентов, которые обычно ожидают завершения команды, прежде чем они продолжаются.
--count Nзавершает работу после событий N и--followпродолжает прослушивать, пока не остановите его.--timeoutостанавливается в ожидании после длительности, например30m, и завершается с состоянием8.--jqи--templateотформатируйте каждое событие, как и вgh apiслучае . Например,--jq .data.conclusionпечатает только вывод набора.
Команда выводит Listening for events. на stderr после открытия потока. Изменения, внесенные до этого, не сообщаются, поэтому прочтите текущее состояние запроса на вытягивание после просмотра этой строки.
Чтобы управлять подписками напрямую, использовать gh event subscription list, view``createи deleteт. е.
gh event listen не удаляет свою подписку при выходе. Срок действия подписок истекает через 24 часа.
При gh обнаружении того, что агент вызывает его, команды, такие как gh pr create, gh run view``gh pr view, gh run watchи gh api предлагают gh event listen вместо опроса.
Для всех параметров выполните команду gh event listen --help.
Справочник по API
Все маршруты включены https://api.github.com.
| Метод | Маршрут | Description |
|---|---|---|
POST | / | Создайте подписку. |
GET | / | Сначала выведите список активных подписок. |
GET | / | Получение подписки. |
DELETE | / | Удаление подписки. |
GET | / | Потоковая передача событий подписки по протоколу SSE. |
Создание подписки
Текст запроса содержит два поля:
resource_url: URL-адрес веб-запроса на вытягивание в форме или URL-адрес REST API в формеhttps://github.com/OWNER/REPO/pull/NUMBER``https://api.github.com/repos/OWNER/REPO/pulls/NUMBERбез дополнительного пути, запроса или фрагмента. Оба формы называют одну и ту же подписку, а ответ всегда возвращает URL-адрес веб-адреса. URL-адреса для части запроса на вытягивание, например проверки, не принимаются.event_types: один или несколько типов событий. Неизвестные типы событий возвращаются422 Unprocessable Contentи имена сообщений об ошибке.
Ответы на подписку включают id, , resource_url, event_types``created_at, expires_at, urlи events_url.
Limits
- Подписка охватывает один запрос на вытягивание.
- Срок действия подписок истекает через 24 часа после их создания. Чтобы сохранить получение событий, создайте новую подписку.
- У каждого пользователя, приложения и маркера установки может быть до 100 активных подписок. Создание дополнительных возвращаемых данных
422с сообщением "Превышено ограничение подписки". Удаление подписок, которые больше не нужны.
Типы событий
| Тип события | Отправлен, когда |
api_url указывает на |
| --- | --- | --- |
| com.github.pull_request.check_suite.status.changed.v1 | Контрольный набор по фиксации головы запроса на вытягивание завершается независимо от его вывода. | Контрольный набор |
| com.github.pull_request.head.changed.v1 | Изменение фиксации головного запроса на вытягивание, например после отправки. | Запрос на вытягивание |
| com.github.pull_request.merge_conflict.v1 |
GitHub находит, что запрос на вытягивание имеет конфликт слияния. | Запрос на вытягивание |
| com.github.pull_request.review.submitted.v1 | Кто-то отправляет отзыв, утверждающий, запрашивает изменения или комментарии. | Обзор |
| com.github.pull_request.state.changed.v1 | Запрос на вытягивание объединяется, закрывается, повторно открывается, помечается готовым к просмотру или преобразуется в черновик. | Запрос на вытягивание |
Запрос на вытягивание обычно содержит несколько наборов проверок, один на приложение, поэтому один push-запрос может создавать несколько событий контрольного набора, а повторное выполнение создает другой после завершения.
Каждый комментарий проверки и каждый ответ на комментарий проверки также считается рецензированием.
В настоящее время события говорят, что что-то изменилось, а не то, что изменилось. Например, событие проверки не включает состояние проверки, а событие изменения состояния не говорит, был ли запрос на вытягивание объединенным или закрытым.
api_url Получите, чтобы узнать.
События набора контрольных наборов являются исключением: их data.conclusion поле всегда присутствует, поэтому вы можете сообщить о сбое без получения. Это один из success, failure, action_required``cancelled``neutral``stale``skipped``timed_out``startup_failureили unknown (заключение за пределами этого списка).
GitHub Проверяет наличие конфликтов слиянием только после того, как кто-то просматривает запрос на вытягивание, поэтому события конфликтов слияния могут занять больше времени, чем другие события.
Формат события
Каждое событие в потоке имеет три поля:
id: идентификатор событияevent: тип мероприятияdata: полное событие в виде однострочного JSON CloudEvent
Обработка потока
Потоки событий являются длительными подключениями, поэтому клиенту необходимо обрабатывать пробелы, повторяющиеся или устаревшие события и потоки, которые заканчиваются. Следуйте этим рекомендациям, чтобы избежать отсутствия или неправильного использования событий.
-
Пропущенные события: потоки доставляют события только во время их открытия без воспроизведения. События, которые происходят, не будут отображаться:
- Перед открытием потока
- Во время короткого окна сразу после создания подписки
- При отключении
После подписки вы получите запрос на вытягивание один раз, чтобы поймать все, что вы пропустили.
-
Дубликаты и упорядочивание: вы можете получать одно и то же событие более одного раза, а события для одного запроса на вытягивание могут поступать из порядка. Извлеките текущее состояние вместо
api_urlтого, чтобы полагаться на порядок событий. Для событий проверки и проверки наборов идентифицируетapi_urlнабор проверки или проверки, поэтому его можно использовать для дедупликации. -
Пульс: пока поток неактивен, сервер отправляет строку комментариев, начиная с
:15 секунд после последнего события или комментария. Игнорировать эти строки. -
Завершение потока: когда сервер заканчивает поток, его последнее событие —
github.stream.endс вoutcomedata.outcomeДействовать не в необязательномreasonполе, так как могут быть добавлены новыеreasonзначения.subscription_ended: срок действия подписки истек или вы потеряли доступ к запросу на вытягивание. Остановите и создайте новую подписку при необходимости.reconnect: повторно откройте поток в той же подписке. Отключайте с помощью jitter и сначала обновите маркер, если срок его действия истек.
-
Непредвиденные отключения: если поток заканчивается без
github.stream.endсобытия, повторно подключитесь. -
Маркеры установки: срок действия маркеров установки истекает через час, и потоки, открытые с одним концом после следующей проверки доступа после истечения срока действия. Создайте новый маркер перед повторной подключением. Невозможно
GITHUB_TOKENпродлить подписку, поэтому удалите созданные подписки до завершения задания.
Errors
Ответы на ошибки включают message, documentation_urlи status.
| Status | Что делать |
|---|---|
400 | Текст запроса не является объектом JSON. Исправление запроса. |
401 | Ваш маркер недопустим или истек. Обновите его и повторите попытку один раз. |
403 | Потоки событий не включены для этой учетной записи или вы выполняете проверку подлинности в качестве приложения, а не как пользователя или установки. Не пытайтесь снова. |
404 | Подписка не существует, истекла или принадлежит другому пользователю или не может получить доступ к запросу на вытягивание. Не пытайтесь снова. |
422 | Значение resource_url или недопустимо, или event_types вы достигли ограничения подписки. Исправьте запрос или удалите подписки, которые больше не нужны. |
503 | Временный. Повторите попытку после количества секунд в заголовке Retry-After . |
500, 504 | Повторите попытку с обратным выходом. |
Известные ограничения
- Нет события "все проверки завершены": вы получаете одно событие для каждого набора проверок. Чтобы узнать, выполняются ли все проверки, получите наборы проверок запроса на вытягивание после каждого события.
- Комментарии к беседе запроса на вытягивание: комментарии на вкладке беседы запроса на вытягивание пока не создают события. Просмотрите комментарии, как события проверки.
- Открытые потоки после удаления: удаление подписки еще не закрывает открытые потоки. Закройте поток перед удалением подписки.
- Состояния фиксации: события набора check suite не охватывают состояния фиксации, созданные с помощью REST API. Если необходимые проверки запроса на вытягивание включают состояния фиксации, извлекайте их отдельно.
- Нет воспроизведения: см. раздел "Обработка потока".
Обратная связь
Мы хотели бы услышать, что работает и что не так. Поделитесь отзывами в обсуждении GitHub сообщества.