Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.
All products
Приложения

Переход с OAuth Apps на GitHub Apps

В этой статье

Узнайте о преимуществах миграции OAuth App в GitHub App, а также о том, как перенести OAuth App.

Преимущества миграции с OAuth Apps на GitHub Apps

GitHub Apps — это рекомендуемый способ интеграции с GitHub. GitHub Apps имеют множество преимуществ по сравнению с OAuth Apps, в том числе:

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

Дополнительные сведения см. в разделе Сведения о создании приложений GitHub.

Преобразование OAuth App в GitHub App

Ниже приведен обзор миграции с OAuth App на GitHub App. Конкретные шаги зависят от приложения.

1. Проверьте OAuth App

Повторно ознакомьтесь с кодом для OAuth App. Запросы API, выполняемые OAuth App, помогут вам решить, какие разрешения следует выбрать для GitHub App.

Кроме того, существует несколько конечных точек REST API, которые недоступны для OAuth Apps. Убедитесь, что все используемые конечные точки REST доступны для GitHub App, проверив "Конечные точки, доступные для приложений GitHub".

2. Регистрация GitHub App

Зарегистрируйте новый GitHub App. Дополнительные сведения см. в разделе Registering a GitHub App.

По сравнению с OAuth App вы можете управлять параметрами GitHub App. Ниже приведены некоторые ключевые дополнения.

  • В отличие от OAuth App, который всегда действует от имени пользователя, вы можете заставить GitHub App выполнять действия от имени пользователя или от имени пользователя. Если вы не хотите, чтобы новый GitHub App делал действия от имени пользователя, можно пропустить параметры "Идентификация и авторизация пользователей". Дополнительные сведения см. в разделе Сведения о проверке подлинности с помощью Приложение GitHub.

  • Вы можете использовать веб-перехватчики для уведомления GitHub App о возникновении определенных событий. В отличие от веб-перехватчиков для OAuth Apps, которые необходимо настроить с помощью API для каждого репозитория или организации, веб-перехватчики встроены в GitHub Apps. При регистрации GitHub App можно выбрать события веб-перехватчика, которые вы хотите получить. Кроме того, если OAuth App в настоящее время использует опрос, чтобы определить, произошло ли событие, рассмотрите возможность подписки на веб-перехватчики, чтобы помочь GitHub App оставаться в пределах ограничения скорости. Дополнительные сведения см. в разделе Использование веб-перехватчиков с приложениями GitHub.

  • При использовании OAuth App вы запрашиваете области, когда пользователь авторизует приложение. При использовании GitHub App вы указываете разрешения в параметрах приложения. Эти разрешения являются более детализированными, чем области, и позволяют выбирать только те разрешения, которые нужны приложению. Кроме того, эти разрешения сопоставляются с конечными точками REST API и событиями веб-перехватчика, поэтому вы можете легко определить, какие разрешения необходимы GitHub App для доступа к определенной конечной точке REST API или подписки на определенный веб-перехватчик. Разрешения в настоящее время не документируются для GraphQL запросов. Дополнительные сведения см. в разделе Выбор разрешений для Приложение GitHub.

3. Изменение кода приложения

После регистрации GitHub App адаптируйте код из старого OAuth App для работы с новым GitHub App.

Обновление проверки подлинности

Вам потребуется обновить код приложения для обработки проверки подлинности API для GitHub App. GitHub App может проходить проверку подлинности тремя способами:

Если вы используете официальную библиотеку Octokit.js GitHub, для проверки подлинности можно использовать встроенный App объект . Примеры см. в разделах Создание скриптов с помощью REST API и JavaScript и Создание Приложение GitHub, реагирующей на события веб-перехватчика.

Ограничения скорости проверки

Просмотрите различия в ограничениях скорости между OAuth Apps и GitHub Apps. GitHub Apps используют скользящие правила для ограничения скорости, которые могут увеличиваться в зависимости от количества репозиториев и пользователей в организации. Дополнительные сведения см. в разделе Ограничения скорости для приложений GitHub.

По возможности рекомендуется использовать условные запросы и подписку на веб-перехватчики вместо опроса, чтобы помочь вам оставаться в пределах скорости. Дополнительные сведения об условных запросах см. в разделе Ресурсы в REST API. Дополнительные сведения об использовании веб-перехватчиков с GitHub App см. в разделах Использование веб-перехватчиков с приложениями GitHub и Создание Приложение GitHub, реагирующей на события веб-перехватчика.

Тестирование кода

Протестируйте новый GitHub App, чтобы убедиться, что код работает должным образом.

4. Публикуйте новые GitHub App

Если вы хотите, чтобы другие учетные записи могли использовать ваш новый GitHub App, убедитесь, что ваше приложение является общедоступным. Дополнительные сведения см. в разделах "Преобразование приложения GitHub в общедоступное или частное".

5. Указание пользователям выполнить миграцию

Когда новый GitHub App будет готов, попросите пользователей старого OAuth App перейти на новый GitHub App. Нет способа автоматической миграции пользователей. Каждый пользователь должен установить и (или) авторизовать GitHub App самостоятельно.

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

Запрос на установку GitHub App

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

Чтобы помочь пользователям установить GitHub App, можно добавить ссылку на веб-страницу приложения, которую пользователи могут щелкнуть для установки GitHub App. Формат URL-адреса установки — http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new. Замените YOUR_APP_NAME на вспущенное имя GitHub App, которое можно найти в поле "Общедоступная ссылка" на странице параметров GitHub App.

Чтобы предварительно выбрать репозитории, к которые имел доступ OAuth App, можно добавить /permissions параметры и запросить к URL-адресу установки. Это помогает пользователям предоставлять GitHub App доступ к репозиториям, к которым у OAuth App уже есть доступ. Параметры запроса:

Например: http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Запрос пользователей на авторизацию приложения

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

Чтобы предложить пользователям авторизовать приложение, вы будете вести их через поток веб-приложения или поток устройства. Дополнительные сведения см. в разделе Создание маркера доступа пользователя для Приложение GitHub.

Дополнительные сведения об авторизации GitHub Apps см. в разделе Авторизация приложений GitHub.

Предложите пользователям отменить доступ к OAuth App

Кроме того, следует призвать пользователей отозвать доступ к старым OAuth App. Это поможет полностью перейти от OAuth App и защитить данные пользователей. Дополнительные сведения см. в разделе Reviewing your authorized OAuth applications.

Обновление интерфейсов или документации

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

6. Удалите веб-перехватчики для старых OAuth App

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

Чтобы удалить веб-перехватчики репозитория, можно прослушивать installation_repositories веб-перехватчик с added помощью действия . Когда GitHub App получает это событие, можно использовать REST API для удаления веб-перехватчика в этих репозиториях для OAuth App. Дополнительные сведения см. в разделах События и полезные данные веб-перехватчика и Веб-перехватчики репозитория.

Аналогичным образом, чтобы удалить веб-перехватчики организации, вы можете прослушивать installation веб-перехватчик с created помощью действия . Когда GitHub App получает это событие для организации, можно использовать REST API для удаления веб-перехватчика в этой организации и соответствующих репозиториев для OAuth App. Дополнительные сведения см. в разделах "События и полезные данные веб-перехватчика", "Веб-перехватчики организации" и "Веб-перехватчики репозитория".

7. Удалите старый OAuth App

После миграции пользователей на новый GitHub App следует удалить старый OAuth App. Это поможет избежать злоупотребления учетными данными OAuth App. Это действие также отменит все оставшиеся разрешения OAuth App. Дополнительные сведения см. в разделе Удаление приложения OAuth. Если OAuth App указан в GitHub Marketplace, может потребоваться сначала связаться с Поддержка GitHub, чтобы удалить приложение из Marketplace.