Миграция OAuth приложений на GitHub Apps

Узнайте о преимуществах миграции на OAuth app ваш GitHub Appобъект и узнайте, как выполнить миграцию OAuth app.

В этой статье

Преимущества миграции из OAuth appsGitHub Apps

GitHub Apps рекомендуется интегрировать с GitHub. GitHub Apps предлагают множество преимуществ, OAuth appsв том числе:

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

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

Преобразование объекта в OAuth app a GitHub App

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

1. Просмотр OAuth app

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

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

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официальную библиотеку Octokit.js, можно использовать встроенный App объект для проверки подлинности. Примеры см. в разделе [AUTOTITLE и Скриптирование с помощью REST API и JavaScript](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events).

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

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

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

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

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

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

Если вы хотите, чтобы другие учетные записи могли использовать новые GitHub Appучетные записи, убедитесь, что ваше приложение является общедоступным. Если вы хотите сделать приложение GitHub App более обнаруживаемым, введите список приложений GitHub Marketplace. Дополнительные сведения см. в разделе О GitHub Marketplace для приложений и Как сделать приложение 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-адреса установки .https://github.com/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 для конечных точек, прошедших проверку подлинности пользователей и репозиториев организации.

Например: https://github.com/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см. в разделе Установка приложения GitHub из GitHub Marketplace для личная учетная запись, Установка приложения GitHub из GitHub Marketplace для организаций,Установка приложения GitHub из стороннего производителя и Установка собственного приложения GitHub.

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

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

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

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

Рекомендуем пользователям отменять OAuth app доступ

Вы также должны поощрять пользователей отменять доступ для старых OAuth app. Это поможет вам полностью перейти от ваших OAuth app данных и поможет защитить данные пользователей. Дополнительные сведения см. в разделе Просмотр авторизованных приложений OAuth.

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

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

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

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

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

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

7. Удаление старого OAuth app

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