Введение
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щелкните фото профиля.
- Перейдите к настройкам учетной записи.
- Для приложения, принадлежащих личная учетная запись, нажмите кнопку "Параметры".
- Для приложения, принадлежащих организации:
- Щелкните Your organizations (Ваши организации).
- Справа от организации нажмите кнопку "Параметры".
- На левой боковой панели щелкните Параметры разработчика.
- На левой боковой панели щелкните 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щелкните фото профиля.
- Перейдите к настройкам учетной записи.
- Для приложения, принадлежащих личная учетная запись, нажмите кнопку "Параметры".
- Для приложения, принадлежащих организации:
- Щелкните Your organizations (Ваши организации).
- Справа от организации нажмите кнопку "Параметры".
- На левой боковой панели щелкните Параметры разработчика.
- На левой боковой панели щелкните 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.