Сведения о GitHub Apps
GitHub App — это тип интеграции, который можно создать для взаимодействия и расширения функциональности GitHub. Вы можете создать GitHub App для обеспечения гибкости и снижения сложности процессов без необходимости входа пользователя или создания учетной записи службы.
Ниже перечислены распространенные варианты использования GitHub Apps:
- Автоматизация задач или фоновых процессов
- Поддержка функции "Вход с помощью GitHub", которая позволяет пользователям выполнять вход с помощью учетной записи GitHub для предоставления удостоверений в вашей экосистеме.
- Как средство разработчика, позволяющее пользователям работать с GitHub путем входа в GitHub App, который затем может действовать от их имени
- Интеграция средства или внешней службы с GitHub
GitHub Apps являются независимыми субъектами в GitHub. GitHub App действует от своего имени, что означает, что вам не нужно поддерживать учетную запись бота или службы в качестве отдельного пользователя. Они также могут проходить проверку подлинности как пользователь и действовать от имени пользователя, используя предоставленные ему разрешения.
Пользователь или организация могут владеть до 100 GitHub Apps, но нет ограничений на количество, которые можно установить в учетной записи.
Если вы хотите, чтобы приложение отвечало на события в GitHub, оно должно подписаться на веб-перехватчики. Например, может потребоваться, чтобы приложение оставило комментарий при открытии запроса на вытягивание. Дополнительные сведения см. в разделе Использование веб-перехватчиков с приложениями GitHub.
Во время разработки вы можете запустить приложение локально для разработки. Когда приложение будет готово к использованию в рабочей среде, его следует развернуть на выделенном сервере. Например, можно использовать Служба приложений Azure.
Разрешения и видимость для GitHub Apps
GitHub Apps могут устанавливаться непосредственно в организациях и личных учетных записях и получать доступ к определенным репозиториям. Они поставляются со встроенными веб-перехватчиками и конкретными разрешениями. При настройке GitHub App можно выбрать определенные разрешения для приложения. Эти разрешения определяют, что приложение может делать с помощью API GitHub, что оно может делать от имени вошедшего пользователя и какие веб-перехватчики может получить приложение. Когда приложение устанавливается в учетной записи пользователя или организации, пользователь, который устанавливает приложение, решает, к каким репозиториям приложение может получить доступ под этой учетной записью. Дополнительные сведения см. в разделе Выбор разрешений для Приложение GitHub.
По умолчанию управлять настройками приложений GitHub в организации могут только владельцы организации. Чтобы разрешить дополнительным пользователям изменять параметры разработчика приложений GitHub, принадлежащих организации, владелец может предоставить им разрешения диспетчера приложений GitHub. Диспетчеры приложений GitHub не могут управлять сторонними приложениями. Дополнительные сведения о добавлении и удалении диспетчеров приложений GitHub в организации см. в разделе Роли в организации .
Вы можете настроить видимость приложения, чтобы управлять его установкой. Вы можете сделать его общедоступным, чтобы другие пользователи или организации GitHub могли устанавливать приложение, или частные, чтобы установить его только в учетной записи, которая владеет приложением. Дополнительные сведения см. в разделе Преобразование приложения GitHub в общедоступное или частное.
Когда следует использовать GitHub Apps
При создании интеграции следует использовать GitHub App в следующих сценариях вместо OAuth App, personal access token или GitHub Actions.
Использование GitHub App вместо OAuth App
Как правило, GitHub Apps предпочтительнее, чем OAuth Apps.
Дополнительные сведения см. в разделе Различия между приложениями GitHub и приложениями OAuth.
Сведения о переносе существующего OAuth App в GitHub App см. в разделе Переход с OAuth Apps на GitHub Apps.
GitHub Apps обеспечивают повышенную безопасность
GitHub Apps обеспечивают больший контроль над тем, что может делать приложение. Вместо широких областей, которые используют OAuth App, GitHub Apps используют детализированные разрешения. Например, если приложению необходимо прочитать содержимое репозитория, OAuth App потребуется repo область, что также позволит приложению изменять содержимое и параметры репозитория. GitHub App может запрашивать доступ только для чтения к содержимому репозитория, что не позволит приложению выполнять более привилегированные действия, такие как изменение содержимого репозитория или параметров.
GitHub Apps также обеспечивают больший контроль над доступом к репозиторию. С помощью GitHub App пользователь или владелец организации, установивший приложение, может решить, к каким репозиториям приложение может получить доступ. И наоборот, OAuth App может получить доступ к каждому репозиторию, к которому может получить доступ пользователь, авторизовать приложение.
GitHub Appиспользуют кратковременные маркеры. В случае утечки маркера маркер будет действителен в течение более короткого периода времени, что сокращает ущерб, который можно нанести. И наоборот, срок действия маркеров OAuth App не истекает, пока пользователь, авторизовавший OAuth App, не отзовет маркер.
Эти функции безопасности помогают защитить GitHub App, ограничивая ущерб, который может быть нанесен в случае утечки учетных данных приложения. Кроме того, это позволяет организациям с более строгими политиками безопасности использовать ваше приложение.
GitHub Apps могут действовать независимо от пользователя или от его имени
GitHub Apps могут действовать независимо от пользователя. Это полезно для автоматизации, для которых не требуется ввод данных пользователем.
Как и в случае с OAuth Apps, GitHub Apps по-прежнему может выполнять действия от имени пользователя. В отличие от OAuth App, которые не указывают на то, что действие было выполнено приложением, GitHub App указывает, что действие было выполнено приложением от имени пользователя.
GitHub Apps не привязаны к учетной записи пользователя и не занимают место в GitHub Enterprise Cloud. GitHub Apps остаются установленными, даже если пользователь, который изначально установил приложение, покидает организацию. Это позволяет интеграции продолжать работать, даже если люди покидают вашу команду.
GitHub Apps имеют ограничения масштабируемой скорости
Ограничение скорости для GitHub App, использующих маркер доступа для установки, масштабируется с помощью количества репозиториев и пользователей организации. И наоборот, OAuth Apps имеет более низкие ограничения скорости и не масштабируется. Дополнительные сведения см. в разделе Ограничения скорости для приложений GitHub.
GitHub Apps имеют встроенные веб-перехватчики
GitHub Apps имеют встроенные централизованные веб-перехватчики. GitHub Apps может получать события веб-перехватчика для всех репозиториев и организаций, к которые может получить доступ приложение. И наоборот, OAuth Apps должны настраивать веб-перехватчики по отдельности для каждого репозитория и организации.
Доступ к API немного отличается
Как правило, GitHub Apps и OAuth Apps могут выполнять одни и те же запросы API. Но между ними существуют некоторые отличия.
- REST API для управления проверка запусков и проверка наборов доступен только для GitHub Apps.
- Корпоративные ресурсы доступны только для OAuth Apps.
- Некоторые запросы могут возвращать неполные данные в зависимости от разрешений и доступа к репозиторию, предоставленных GitHub App. Например, если приложение отправляет запрос на получение всех репозиториев, к которым пользователь может получить доступ, ответ будет включать только те репозитории, к которым приложению также был предоставлен доступ.
Дополнительные сведения о конечных точках REST API, доступных для GitHub App, см. в разделе Конечные точки, доступные для приложений GitHub.
Выбор между GitHub App или personal access token
Если вы хотите получить доступ к ресурсам GitHub от имени пользователя или в организации или планируете долговременную интеграцию, рекомендуется создать GitHub App.
personal access tokens можно использовать для тестирования API или кратковременных скриптов. Так как personal access token связан с пользователем, автоматизация может нарушиться, если у пользователя больше нет доступа к нужным ресурсам. GitHub App, установленный в организации, не зависит от пользователя. Кроме того, в отличие от пользователя, GitHub App не использует место GitHub.
GitHub поддерживает два типа personal access tokens, но рекомендует по возможности использовать fine-grained personal access tokens вместо personal access tokens (classic). Дополнительные сведения о personal access tokens см. в разделе Создание личного маркера доступа.
Выбор между GitHub App или GitHub Actions
GitHub Apps и GitHub Actions предоставляют способы создания средств автоматизации и рабочих процессов.
GitHub Actions обеспечивает автоматизацию, которая может выполнять такие задания, как непрерывная интеграция, задачи развертывания и управление проектами в репозитории. Они выполняются непосредственно на компьютерах, размещенных в GitHub, или на локальных средствах выполнения, настроенных администратором. GitHub Actions не выполняются постоянно. Они выполняются в ответ на события, происходящие в их репозитории, и имеют доступ только к ресурсам репозитория, для которых они настроены. Однако их можно совместно использовать в репозиториях и организациях, что позволяет разработчикам повторно использовать и изменять существующие действия в соответствии с их потребностями. GitHub Actions также поставляются со встроенным управлением секретами, которое можно использовать для безопасного взаимодействия со сторонними службами и безопасного управления ключами развертывания.
GitHub Apps постоянно выполняются на предоставленном сервере или вычислительной инфраструктуре и реагируют на события веб-перехватчика, а также события из-за пределов экосистемы GitHub. Они являются хорошим вариантом для операций, охватывающих несколько репозиториев или организаций, или для предоставления размещенных служб другим организациям. GitHub App — лучший выбор при создании средства с функциями, которые выполняются в основном за пределами GitHub или требуют больше времени, чем отведено для выполнения действия.
Дополнительные сведения о сравнении GitHub Actions с GitHub Apps см. в разделе Сведения о настраиваемых действиях.
Вы можете использовать GitHub App для проверки подлинности в рабочем процессе GitHub Actions, если встроенный GITHUB_TOKEN не имеет достаточных разрешений. Дополнительные сведения см. в разделе Выполнение запросов API с проверкой подлинности с помощью Приложение GitHub в рабочем процессе GitHub Actions.
Общие сведения о типе GitHub App для сборки
Существует несколько способов проектирования GitHub App, которые вы хотите рассмотреть, в зависимости от функциональных возможностей приложения.
GitHub Apps, которые действуют от имени пользователя
Если вы хотите, чтобы приложение следовало выполнять действия от имени пользователя, следует использовать маркер доступа пользователя для проверки подлинности. Этот тип запроса иногда называют "от пользователя к серверу", и это означает, что приложение будет ограничено разрешениями, предоставленными приложению, а также разрешениями пользователя. В этом шаблоне пользователь должен авторизовать приложение, прежде чем оно сможет выполнить действие. Дополнительные сведения см. в разделе Проверка подлинности с помощью Приложение GitHub от имени пользователя.
Ниже приведены некоторые примеры автоматизации, которые можно создать с помощью GitHub App, где приложение действует от имени пользователя.
- GitHub App, использующий GitHub в качестве поставщика удостоверений для вашей экосистемы
- GitHub App, который добавляет службу поверх GitHub.com, которая может быть полезна для пользователя GitHub. Вы можете поделиться приложением с другими разработчиками с помощью GitHub Marketplace или сделав приложение общедоступным.
GitHub Apps, которые действуют от своего имени
Если вы хотите, чтобы приложение должно выполнять действия от своего имени, а не от имени пользователя, следует использовать маркер доступа установки для проверки подлинности. Этот тип запроса иногда называют "сервер-сервер", и это означает, что приложение будет ограничено разрешениями, предоставленными приложению. Дополнительные сведения см. в разделе Проверка подлинности в качестве установки Приложение GitHub.
Ниже приведены некоторые примеры автоматизации, которые можно создать с помощью GitHub App, где приложение действует от своего имени:
- GitHub App, который использует веб-перехватчики для реагирования на событие с учетом определенного набора критериев. Например, можно создать автоматизацию для конечных точек REST API для проверки запросов для fine-grained personal access token , утверждающих запрос с учетом определенной политики
- GitHub App, который помогает участникам репозитория. Например, приложение может публиковать полезные ресурсы после того, как участник создает запрос на вытягивание или делает комментарий
- GitHub App, который создает кратковременные маркеры для передачи другим средствам CI/CD или извлечения сведений из репозитория.