Краткое руководство по созданию приложений 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 . Замените YOUR_HOSTNAME именем ваш экземпляр GitHub Enterprise Server. Вы обновите другие значения на следующем шаге.
Text
```
APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"
```
```
APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"
```

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

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

В правом верхнем углу любой страницы на 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

В этой статье