Перенос приложений OAuth в приложения GitHub

Преимущества миграции с 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 Apps путем проверки AUTOTITLE.

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

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

По сравнению с параметрами 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 может пройти проверку подлинности тремя способами:

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

Если вы используете официальную библиотеку Octokit.js данных GitHub, можно использовать встроенный App объект для проверки подлинности. Примеры см. в разделе [AUTOTITLE и Скриптирование с помощью REST API и JavaScript](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events).

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

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

По возможности рекомендуется использовать условные запросы и подписку на веб-перехватчики вместо опроса, чтобы помочь вам оставаться в пределах скорости. Дополнительные сведения об условных запросах см. в разделе Рекомендации по использованию REST API. Дополнительные сведения об использовании веб-перехватчиков с данными GitHub Appсм. в разделе [AUTOTITLE и Использование веб-перехватчиков с приложениями GitHub](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events).

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

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

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

Если вы хотите, чтобы другие учетные записи могли использовать новые данные GitHub App, убедитесь, что ваше приложение открыто. Дополнительные сведения см. в разделе Преобразование приложения GitHub в общедоступное или частное](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace).

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 . Параметры запроса:

suggested_target_id: идентификатор пользователя или организации, устанавливающей данные GitHub App. Этот параметр является обязательным.
repository_ids[]: идентификаторы репозитория, которые нужно выбрать для установки. Если опущено, выбраны все репозитории. Максимальное число репозиториев, которые можно предварительно выбрать, — 100. Чтобы получить список репозиториев, к которым имеет доступ OAuth app, используйте репозитории List для конечных точек, прошедших проверку подлинности пользователей и репозиториев организации.

Например: 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 Appsсм. в разделе [AUTOTITLE и Установка собственного приложения GitHub.](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account)

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

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

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

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

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

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

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

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

Чтобы удалить веб-перехватчики репозитория, можно прослушивать installation_repositories веб-перехватчик с added помощью действия. Когда данные GitHub App получают это событие, можно использовать REST API для удаления веб-перехватчика в этих репозиториях для OAuth app. Дополнительные сведения см. в разделе [AUTOTITLE и События и полезные данные веб-перехватчика](/rest/webhooks#delete-a-repository-webhook).

Аналогичным образом, чтобы удалить веб-перехватчики организации, вы можете прослушивать installation веб-перехватчик с created помощью действия. Когда данные GitHub App получают это событие для организации, вы можете использовать REST API для удаления веб-перехватчика в этой организации и соответствующих репозиториев для OAuth app. Дополнительные сведения см. в разделе AUTOTITLE, [AUTOTITLE[ и Конечные точки REST API для веб-перехватчиков репозитория](/rest/orgs/webhooks#delete-an-organization-webhook).](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=created#installation)

7. Удаление старых данных OAuth app

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