Краткое руководство по созданию приложений GitHub

Введение

GitHub Apps позволяет автоматизировать процессы или интегрировать другие платформы с GitHub. Дополнительные сведения см. в разделе "Создание приложений GitHub".

В этом кратком руководстве описывается, как быстро создать GitHub App. Когда запрос на вытягивание открывается в репозитории, к которому был предоставлен доступ, приложение добавит комментарий к запросу на вытягивание.

В этом кратком руководстве используется предварительно написанный код, помогающий быстро приступить к работе. Более подробное руководство по написанию кода см. в разделе "Создание приложения GitHub, реагирующего на события веб-перехватчика".

Необходимые компоненты

Компьютер или пространство кода должно использовать Node.js версии 12 или более поздней. Дополнительные сведения см. в Node.js.

Шаг 1. Клонирование кода приложения

Чтобы быстро приступить к работе, мы написали код, который можно использовать. Если вы хотите узнать, как самостоятельно писать код, см. раздел AUTOTITLE.

Клонируйте репозиторий github/github-app-js-sample . Дополнительные сведения см. в разделе Клонирование репозитория. Вы можете использовать локальный клон или GitHub Codespaces.
В окне терминала перейдите в каталог, в котором хранится клон.
Запустите npm install, чтобы установить зависимости.

Шаг 2. Получение URL-адреса прокси-сервера веб-перехватчика

Для локальной разработки приложения можно использовать URL-адрес прокси-сервера веб-перехватчика для пересылки веб-перехватчиков из GitHub на компьютер или пространство кода. В этом кратком руководстве используется Smee.io для предоставления URL-адреса прокси-сервера веб-перехватчика и перенаправления веб-перехватчиков.

В браузере перейдите по адресу https://smee.io/.
Нажмите кнопку " Пуск нового канала".
Скопируйте полный URL-адрес в разделе "URL-адрес прокси-сервера веб-перехватчика". Этот URL-адрес будет использоваться на следующем шаге.

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

Ниже приведены инструкции по настройке параметров приложения, необходимых для работы с этим кратким руководством. Дополнительные сведения о параметрах см. в разделе "Регистрация приложения GitHub".

В правом верхнем углу любой страницы на GitHubщелкните фото профиля.
Перейдите к настройкам учетной записи.
- Для приложения, принадлежащих личная учетная запись, щелкните Параметры.
- Для приложения, принадлежащих организации:
  1. Щелкните Your organizations (Ваши организации).
  2. Справа от организации щелкните Параметры.
На левой боковой панели щелкните Параметры разработчика.
На левой боковой панели щелкните GitHub Apps.
Нажмите кнопку Создать приложение GitHub.
В разделе "Имя приложения GitHub" введите имя приложения. Например, USERNAME-quickstart-app где USERNAME находится имя пользователя GitHub.
В разделе "URL-адрес домашней страницы" введите https://github.com/github/github-app-js-sample#readme.
Пропустите разделы "Идентификация и авторизация пользователей" и "После установки" для этого краткого руководства. Дополнительные сведения об этих параметрах см. в разделе "Регистрация приложения GitHub".
Убедитесь, что параметр "Активный " выбран в разделе "Веб-перехватчики".
В разделе "URL-адрес веб-перехватчика" введите URL-адрес прокси-сервера веб-перехватчика ранее. Дополнительные сведения см. в разделе "Шаг 2. Получение URL-адреса прокси-сервера веб-перехватчика".
В разделе "Секрет веб-перехватчика" введите случайную строку. Эта строка будет использоваться позже.
В разделе "Разрешения репозитория" рядом с пунктом "Запросы на вытягивание" выберите "Чтение и запись".
В разделе "Подписка на события" выберите запрос на вытягивание.
В разделе "Где можно установить приложение GitHub?", выберите только в этой учетной записи.
Нажмите кнопку Создать приложение GitHub.

Шаг 4. Хранение сведений и учетных данных

В этом кратком руководстве вы сохраните учетные данные приложения и определите сведения в качестве переменных среды в .env файле. При развертывании приложения необходимо изменить способ хранения учетных данных. Дополнительные сведения см. в разделе "Развертывание приложения".

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

Создайте файл `.env` .

Клонированные репозитории включаются .env в .gitignore файл. Это позволит предотвратить случайное фиксацию учетных данных приложения. Дополнительные сведения о файлах см. в .gitignore разделе "Пропуск файлов".

Перейдите в каталог, в котором хранится клон github/github-app-js-sample .
Создайте файл, вызывающийся .env на верхнем уровне этого каталога.

Добавьте в файл следующее содержимое .env . Вы обновите значения на следующем шаге.

Text

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"

Перейдите к параметрам приложения

Если вы перейдете из параметров приложения после создания приложения, перейдите на страницу параметров приложения:

В правом верхнем углу любой страницы на GitHubщелкните фото профиля.
Перейдите к настройкам учетной записи.
- Для приложения, принадлежащих личная учетная запись, щелкните Параметры.
- Для приложения, принадлежащих организации:
  1. Щелкните Your organizations (Ваши организации).
  2. Справа от организации щелкните Параметры.
На левой боковой панели щелкните Параметры разработчика.
На левой боковой панели щелкните GitHub Apps.
Рядом с именем приложения нажмите кнопку "Изменить".

Получение учетных данных приложения и идентификация сведений

На странице параметров приложения рядом с идентификатором приложения найдите идентификатор приложения.
.env В файле замените YOUR_APP_ID идентификатор приложения.
На странице параметров приложения в разделе "Закрытые ключи" нажмите кнопку "Создать закрытый ключ". Вы увидите скачанный на компьютер закрытый ключ в формате PEM. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.
Если вы используете пространство кода, переместите скачанный PEM-файл в пространство кода, чтобы пространство кода могли получить доступ к файлу.
.env В файле замените YOUR_PRIVATE_KEY_PATH полный путь к закрытому ключу, включая .pem расширение.
.env В файле замените YOUR_WEBHOOK_SECRET секрет веб-перехватчика для приложения. Если вы забыли секрет веб-перехватчика, в разделе "Секрет веб-перехватчика (необязательно)" нажмите кнопку "Изменить секрет". Введите новый секрет и нажмите кнопку "Сохранить изменения".

Шаг 5. Установка приложения

Чтобы приложение оставило комментарий по запросам на вытягивание в репозитории, оно должно быть установлено в учетной записи, которая владеет репозиторием и предоставляет доступ к нему. Так как ваше приложение является частным, оно может быть установлено только в учетной записи, которая владеет приложением.

В учетной записи, владеющей созданным приложением, создайте новый репозиторий для установки приложения. Дополнительные сведения см. в разделе Создание репозитория.
Если вы перейдете из параметров приложения после создания приложения, перейдите на страницу параметров приложения. Дополнительные сведения см. в разделе "Переход к параметрам приложения".
Щелкните общедоступную страницу.
Щелкните Установить.
Выберите только репозитории выбора.
Выберите раскрывающееся меню "Выбор репозиториев" и выберите репозиторий, выбранный в начале этого раздела.
Щелкните Установить.

Шаг 6. Запуск сервера

Для тестирования вы будете использовать компьютер или пространство кода в качестве сервера. Ваше приложение будет активно только при запуске сервера.

В окне терминала перейдите в каталог, в котором хранится клон github/github-app-js-sample .
Чтобы получить перенаправленные веб-перехватчики из Smee.io, выполните команду npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook. Замените WEBHOOK_PROXY_URL URL-адрес прокси-сервера веб-перехватчика. Если вы забыли URL-адрес, его можно найти в поле "URL-адрес веб-перехватчика" на странице параметров приложения.

Вы увидите выходные данные, которые выглядят следующим образом, где WEBHOOK_PROXY_URL находится URL-адрес прокси-сервера веб-перехватчика:
```
Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
Connected WEBHOOK_PROXY_URL
```
Во втором окне терминала перейдите в каталог, где хранится клон github/github-app-js-sample .
Запустите npm run server. Ваш терминал должен сказать: Server is listening for events at: http://localhost:3000/api/webhook

Шаг 7. Тестирование приложения

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

Откройте запрос на вытягивание в репозитории, созданном на шаге 5. Установите приложение. Дополнительные сведения см. в разделе Создание запроса на включение изменений.
Перейдите по URL-адресу прокси-сервера веб-перехватчика на smee.io. Должно появиться pull_request событие. Это означает, что GitHub успешно отправил событие запроса на вытягивание при создании запроса на вытягивание.
В терминале, на котором вы выполнили, npm run serverвы увидите примерно следующее: "Получено событие запроса на вытягивание для #1", где целое число после # того, как указано число открываемого запроса на вытягивание.
В временная шкала запроса на вытягивание вы увидите комментарий из приложения. Комментарий использует содержимое message.md файла в клонированного репозитория.
В обоих окнах терминала введите CTRL+C, чтобы остановить сервер и прекратить прослушивание перенаправленных веб-перехватчиков.

Следующие шаги

Теперь, когда у вас есть приложение, может потребоваться развернуть код приложения, развернуть приложение и сделать приложение общедоступным.

Изменение кода приложения

Вилку репозитория github/github-app-js-sample и измените код для реагирования на различные события веб-перехватчика или для выполнения различных запросов API. Дополнительные сведения о коде см. в разделе "Создание приложения GitHub, реагирующего на события веб-перехватчика".

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

Развертывание приложения

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

После создания сервера обновите URL-адрес веб-перехватчика в параметрах приложения. Не следует использовать Smee.io для пересылки веб-перехватчиков в рабочей среде.

Вам также потребуется обновить port и host константы в коде. Дополнительные сведения см. в разделе Создание приложения GitHub, реагирующего на события веб-перехватчика.

Вы никогда не должны публиковать закрытый ключ приложения или секрет веб-перехватчика. В этом руководстве хранятся учетные данные приложения в gitignored-файле .env . При развертывании приложения следует выбрать безопасный способ хранения учетных данных и обновления кода, чтобы получить соответствующее значение. Например, учетные данные можно хранить в переменной среды на сервере, на котором развернуто приложение. Вы также можете использовать службу управления секретами, например Azure Key Vault.

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

Применение рекомендаций

Вам следует следовать рекомендациям по использованию данных GitHub App. Дополнительные сведения см. в разделе Рекомендации по созданию приложения GitHub.

Краткое руководство по созданию приложений GitHub

В этой статье