Перейти к основному содержимому

Настройка плагина GitHub

О плагине GitHub​

Плагин GitHub использует вебхук для подключения вашей учетной записи GitHub к Loop для прослушивания входящих событий GitHub. Уведомления о событиях отправляются через личные сообщения в Loop. События не требуют отдельной настройки.

После того, как системный администратор настроил плагин GitHub, запустите /github connect в канале Loop, чтобы объединить учетные записи Loop и GitHub.

После подключения вы получите доступ к следующим функциям:

  • Ежедневные напоминания. Каждый раз, когда вы впервые входите в Loop, вы получаете сообщение, в котором сообщается, на какие события в GitHub следует обратить внимание.
  • Уведомления. Вы будете получать сообщения в Loop, когда кто-то упоминает вас, оставляет комментарии, отправляет pull request и о других изменениях на GitHub.
  • Действия с публикациями. Создайте новую проблему (issue) на GitHub к публикации проекта или прикрепите сообщение к проблеме. Наведите указатель мыши на публикацию, чтобы открыть меню действий и нажмите «Дополнительные действия...».
  • Кнопки на боковой панели. Будьте в курсе того, сколько у вас просмотров, непрочитанных сообщений, открытых проблем и pull request’ов от других пользователей, с помощью кнопок на боковой панели Loop.
  • Slash-команды. Взаимодействуйте с плагином GitHub с помощью slash-команды /github

Настройка плагина​

У вас должна быть учетная запись GitHub. Настройка плагина GitHub начинается с регистрации приложения OAuth в GitHub остальные действия производятся в Loop.

Примечание. Если вы используете GitHub Enterprise, замените все ссылки GitHub ниже URL-адресом GitHub Enterprise.

Вы можете использовать эту /github setup slash-команду для оптимизации процесса настройки.

Шаг 1. Зарегистрируйте приложение OAuth на GitHub.​

Сначала вы должны зарегистрировать плагин Loop GitHub в качестве авторизованного приложения OAuth независимо от того, настраиваете ли вы плагин GitHub, как системный администратор или пользователь Loop.

  1. Перейдите на https://github.com/settings/applications/new , чтобы зарегистрировать приложение OAuth.
  2. Установите следующие значения:
  • Application name: Loop GitHub Plugin - <наименование вашей компании>
  • Homepage URL: https://github.com/ваш-Github-account/ваш-репозиторий
  • Authorization callback URL: https://ваш-сервер-loop/plugins/github/oauth/completehttps://ваш-сервер-loop Это значение должно соответствовать URL-адресу сервера Loop, на который вы или ваши пользователи входят.
  1. Нажмите Register Application
  2. Нажмите «Generate a new client secret» и укажите свой пароль от GitHub, чтобы продолжить.
  3. Скопируйте Client ID и Client Secret.
  4. После того как вы зарегистрировали плагин Loop GitHub в качестве авторизованного приложения OAuth, запустите Loop и в канале с помощью slash-команды /github connect настройте соединение с плагином GitHub. Вы должны получить личное сообщение от плагина GitHub о доступных вам функциях. В списке контактов появится бот GitHub, а в верхней части отобразится панель управления плагина.
  5. Перейдите в «Системная консоль» > «Плагины» > GitHub и введите GitHub OAuth Client ID и GitHub OAuth Client Secret, которые вы скопировали ранее.
  6. Нажмите «Сохранить»

Шаг 2. Создайте вебхуки в GitHub​

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

  1. В Системной консоли > Плагины > GitHub > Webhook Secret и нажмите кнопку Создать новую. Скопируйте значение поля, так как вы будете использовать его на следующем этапе.
  2. Нажмите «Сохранить»
  3. Перейдите меню Settings вашего аккаунта GitHub, затем выберите «Webhooks» на боковой панели.
  4. Нажмите «Add webhook».
  5. Установите следующие значения:
  • Payload URL: https://ваш-сервер-loop/plugins/github/webhook
  • Content type:application/json
  • Secret: Webhook Secret, который вы создали и скопировали на 1 шаге.
  1. Выберите «Let me select individual events» для параметра «Which events would you like to trigger this webhook?».
  2. Выберите следующие события: Branch or Tag creation, Branch or Tag deletion, Issue comments, Issues, Pull requests, Pull request review, Pull request review comments, Pushes, Stars
  3. Нажмите «Add webhook», чтобы сохранить его.

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

Шаг 3. Настройка плагина в Loop​

Если у вас есть существующая учетная запись пользователя Loop с именем github, плагин будет публиковать сообщения с использованием этой учетной записи, но без БОТ тега.

Чтобы предотвратить это, либо:

  • Преобразуйте github пользователя в учетную запись бота или
  • Если пользователь представляет собой существующую учетную запись, которую вы хотите сохранить, измените его имя пользователя и сообщите нам, мы перезапустим сервер Loop. После перезапуска плагин создаст учетную запись бота с именем github

Сгенерируйте ключ шифрования​

Откройте Системную консоль > Плагины > GitHub и выполните следующие действия:

  1. Создайте новое значение для At Rest Encryption Key
  2. GitHub Organization (Необязательно): прикрепите плагин к организации, как на GitHub, указав в этом поле соответствующее имя.
  3. Enable Private Repositories (Необязательно): разрешите плагину получать уведомления из частных репозиториев, установив для этого значения значение true
  4. Enterprise Base URL и Enterprise Upload URL(Только для Enterprise): установите эти значения для URL-адресов GitHub Enterprise, например https://github.example.comEnterprise Base URL и Enterprise Upload URL часто совпадают. Если эта функция включена, существующие пользователи должны повторно подключить свои учетные записи, чтобы получить доступ к частным репозиториям. Плагин уведомит пользователей о включении частных репозиториев.
  5. Нажмите «Сохранить»
  6. Перейдите по пути «Системная консоль» > «Плагины» > «Управление плагинами» и нажмите «Включить», чтобы включить плагин GitHub.

После завершения настройки запустите slash-команду /github connect на любом канале Loop, чтобы подключить свою учетную запись Loop к GitHub. Когда вы протестировали плагин и убедились в его работе, сообщите об этом своей команде, чтобы они могли подключить свою учетную запись GitHub к Loop и начать работу. Расскажите о действиях, который нужно выполнить пользователям.

Например: *Мы настроили плагин GitHub, чтобы вы могли получать уведомления с GitHub в Loop. Чтобы начать, отправьте slash-команду /github connect в любом канале Loop, чтобы подключить свою учетную запись Loop к GitHub.

Slash-команды плагина GitHub​

  • Введя символ / в поле ввода текста, с помощью дополнительной функции автодополнение, вы получите перечень доступных команд, которые выделены черным цветом и краткое описание функции серым текстом.

  • Подписка на репозиторий . Используйте команду /github subscriptions add, чтобы подписаться и получать уведомления о новых pull request’ах, вопросах, создании веток и многих других событиях в репозитории GitHub.

  • Например, чтобы публиковать уведомления о проблемах, комментарии к вопросам и pull request’ы, метки “Help Wanted” из mattermost/mattermost-server, используйте команду: /github subscriptions add mattermost/mattermost-server --features issues,pulls,issue_comments,label:"Help Wanted"

  • Поддерживаются следующие флаги:

    • --features: разделенный запятыми список из одного или нескольких из: Issues, Pulls, Pulls_merged, Pushs, Creates, Deletes, Issue_creations, Issue_comments, Pull_reviews, label:"labelname". По умолчанию извлекает, выдает, создает, удаляет.

    • --exclude-org-member: события, которые инициируют участники организации, не будут доставлены. Они будут привязаны к организации, указанной в конфигурации плагина, и будут работать только для пользователей, чье участие является общедоступным. Обратите внимание, что члены организации и сотрудники — это не одно и то же.

    • --render-style: уведомления будут доставлены в указанном стиле (например, тело запроса pull requst’а не будет отображаться). Поддерживаемые значения collapsed , skip-body или default(то же самое, что и отсутствие флага).

  • Получить информацию о новых событиях — используйте /github todo для получения сообщения с заданиями на GitHub, включая список непрочитанных сообщений и pull request’ов, ожидающих вашего рассмотрения.

  • Обновить настройки — используйте /github settings для обновления настроек уведомлений и ежедневных напоминаний.

  • Настройка интеграции GitHub — используйте /github setup для настройки интеграции между GitHub и Loop. Эта команда имеет следующие подкоманды:

    • /github setup oauth настраивает приложение OAuth2 в GitHub, устанавливая необходимое соединение для авторизации между GitHub и Loop.
    • /github setup webhook Создает вебхук от GitHub к Loop, позволяющий отправлять уведомления и обновления из GitHub в режиме реального времени на каналы Loop.
    • /github setup announce отправляет сообщение по назначенным каналам в Loop, уведомляя о доступности интеграции GitHub для использования участниками команды.

  • Получить информацию о доступных командах - используя команду /github help вы получите список доступных slash-команд, узнайте о других возможностях.

Часто задаваемые вопросы​

Как подключить репозиторий вместо организации?​

Настройте вебхук GitHub из репозитория, а не из организации. Уведомления и подписки будут отправляться только для репозиториев, для которых вы создаете вебхуки. Напоминание и /github todo по-прежнему будут выполняться по всей организации, но будут перечислены только выбранные элементы.

Как отправлять уведомления при применении определенного ярлыка?​

Предположим, вы хотите отправлять уведомления на канал Loop, когда Severity/Critical метка применяется к любой проблеме в mattermost/mattermost-plugin-github репозитории. Используйте нижеуказанную команду, чтобы подписаться на эти уведомления: /github subscriptions add mattermost/mattermost-plugin-github issues,label:"Severity/Critical"

Как плагин использует пользовательские данные для каждого подключенного пользователя GitHub?​

Токены пользователей GitHub зашифрованы по алгоритму AES с помощью ключа шифрования, настроенного на странице настроек плагина. После шифрования токены сохраняются в PluginKeyValueStore таблице вашей базы данных Loop.