Сведения о GitHub Apps
GitHub App — это тип интеграции, который можно создать для взаимодействия и расширения функциональности GitHub. Вы можете создать GitHub App для обеспечения гибкости и снижения сложности процессов без необходимости входа пользователя или создания учетной записи службы.
Распространенные варианты использования GitHub Apps включают:
- Автоматизация задач или фоновых процессов
- Поддержка функции "Вход с помощью GitHub", которая позволяет пользователям выполнять вход с помощью учетной записи GitHub для предоставления удостоверения в вашей экосистеме.
- Как средство разработчика, позволяющее пользователям работать с GitHub путем входа в GitHub App, который затем может действовать от их имени.
- Интеграция средства или внешней службы с GitHub
GitHub Apps являются независимыми субъектами в GitHub. GitHub App действует от своего имени, что означает, что вам не нужно поддерживать бот или учетную запись службы в качестве отдельного пользователя. Они также могут проходить проверку подлинности от имени пользователя и действовать от его имени, используя предоставленные ему разрешения.
Если вы хотите, чтобы приложение реагировал на события в 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.
Как OAuth Apps, так и GitHub Apps используют OAuth 2.0.
OAuth Apps может действовать только от имени пользователя, в то время как GitHub 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 Apps используют короткоживущие токены. В случае утечки маркера маркер будет действителен в течение более короткого периода времени, что сокращает ущерб, который можно нанести. И наоборот, срок действия маркеров OAuth App не истекает до тех пор, пока пользователь, авторизовавший OAuth App, не отменит маркер.
Эти функции безопасности помогают защитить GitHub App, ограничивая ущерб, который может быть нанесен при утечке учетных данных приложения. Кроме того, это позволяет организациям с более строгими политиками безопасности использовать ваше приложение.
GitHub Apps может действовать независимо или от имени пользователя
GitHub Apps может действовать независимо от пользователя. Это полезно для автоматизации, для которых не требуется ввод данных пользователем.
Как и в случае с OAuth Apps, GitHub Apps по-прежнему может выполнять действия от имени пользователя. В отличие от OAuth Apps, которые не указывают на то, что действие было выполнено приложением, GitHub Apps указывает, что действие было выполнено приложением от имени пользователя.
GitHub Apps не привязаны к учетной записи пользователя и не занимают место в GitHub Enterprise Server. 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 Apps, см. в разделе Конечные точки, доступные для приложений 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. Дополнительные сведения о personal access tokens см. в разделе Managing your 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 для меток для добавления меток к каждой новой проблеме, созданной в репозитории, с учетом определенного набора критериев
- GitHub App, который помогает участникам репозитория. Например, приложение может публиковать полезные ресурсы после того, как участник создает запрос на вытягивание или делает комментарий.
- GitHub App, который создает кратковременные маркеры для предоставления другим средствам CI/CD или извлечения сведений из репозитория.