Сведения об установке GitHub App
После установки GitHub App в учетной записи вы можете выполнить проверку подлинности в качестве установки приложения для запросов API. Это позволяет приложению получать доступ к ресурсам, принадлежащим этой установке, при условии, что приложению был предоставлен необходимый доступ к репозиторию и разрешения. Запросы API, выполняемые установкой приложения, относятся к приложению. Дополнительные сведения об установке приложений GitHub см. в разделе Установка приложений GitHub.
Например, если вы хотите, чтобы приложение изменяло Status
поле проблемы в проекте, принадлежавом организации с именем "octo-org", необходимо пройти проверку подлинности как установка приложения octo-org. В временная шкала проблемы будет указано, что ваше приложение обновило состояние.
Чтобы выполнить запрос API в качестве установки, необходимо сначала создать маркер доступа к установке. Затем вы отправите маркер доступа к установке в заголовке Authorization
последующих запросов API. Вы также можете использовать пакеты SDK Octokit для GitHub, которые могут создать маркер доступа для установки.
Если конечная точка REST API работает с маркером доступа установки GitHub App, в справочной документации по REST для этой конечной точки будет указано "Работает с GitHub Apps". Кроме того, приложение должно иметь необходимые разрешения для использования конечной точки. Дополнительные сведения см. в разделе Выбор разрешений для Приложение GitHub.
Установки приложений также могут использовать API GraphQL. Как и REST API, приложение должно иметь определенные разрешения на доступ к объектам в API GraphQL. Для GraphQL запросов следует протестировать приложение, чтобы убедиться, что приложение имеет необходимые разрешения для GraphQL запросов и изменений, которые вы хотите выполнить.
Вы также можете использовать маркер доступа к установке для проверки подлинности для доступа Git по протоколу HTTP. У приложения должно быть разрешение репозитория "Содержимое". Затем можно использовать маркер доступа для установки в качестве пароля HTTP. Замените TOKEN
маркером доступа установки: git clone https://x-access-token:TOKEN@github.com/owner/repo.git"
.
Запросы, выполненные с помощью маркера доступа установки, иногда называются запросами "сервер-сервер".
Дополнительные сведения о проверке подлинности в качестве приложения от имени пользователя, а не в качестве установки приложения, см. в разделе Проверка подлинности с помощью Приложение GitHub от имени пользователя.
Использование маркера доступа к установке для проверки подлинности в качестве установки приложения
Чтобы пройти проверку подлинности в качестве установки с помощью маркера доступа к установке, сначала используйте REST API для создания маркера доступа к установке. Затем используйте этот маркер доступа установки в заголовке Authorization
REST API или GraphQL запроса API. Срок действия маркера доступа для установки истекает через 1 час.
Создание маркера доступа установки
-
Создайте веб-токен JSON (JWT) для приложения. Дополнительные сведения см. в разделе Создание веб-токена JSON (JWT) для Приложение GitHub.
-
Получите идентификатор установки, для которой требуется пройти проверку подлинности.
Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.
Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с конечными точками
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
илиGET /app/installations
. Дополнительные сведения см. в разделе Приложения GitHub. -
Отправьте запрос REST API
POST
по адресу/app/installations/INSTALLATION_ID/access_tokens
. Включите веб-токен JSON вAuthorization
заголовок запроса. ЗаменитеINSTALLATION_ID
идентификатором установки, для которой требуется пройти проверку подлинности.Например, отправьте этот запрос curl. Замените
INSTALLATION_ID
идентификатором установки, аJWT
— своим веб-токеном JSON:curl --request POST \ --url "https://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT"
При необходимости можно использовать
repositories
параметры илиrepository_ids
body, чтобы указать отдельные репозитории, к которым может получить доступ маркер доступа установки. Если вы не используетеrepositories
илиrepository_ids
для предоставления доступа к определенным репозиториям, маркер доступа к установке будет иметь доступ ко всем репозиториям, к которым была предоставлена установка. Маркер доступа установки не может быть предоставлен доступ к репозиториям, к которым установка не была предоставлена.При необходимости используйте
permissions
параметр body, чтобы указать разрешения, которые должен иметь маркер доступа установки. Еслиpermissions
параметр не указан, маркер доступа к установке будет иметь все разрешения, предоставленные приложению. Маркеру доступа установки не могут быть предоставлены разрешения, которые не были предоставлены приложению.Ответ будет включать маркер доступа к установке, время истечения срока действия маркера, разрешения, имеющиеся у маркера, и репозитории, к которым маркер может получить доступ. Срок действия маркера доступа для установки истекает через 1 час.
Дополнительные сведения об этой конечной точке см. в разделе Приложения GitHub.
Примечание. В большинстве случаев передать маркер с помощью
Authorization: Bearer
илиAuthorization: token
. Однако при передаче веб-токена JSON (JWT) необходимо использоватьAuthorization: Bearer
.
Проверка подлинности с помощью маркера доступа установки
Для проверки подлинности с помощью маркера доступа установки включите его в Authorization
заголовок запроса API. Маркер доступа будет работать как с API GraphQL, так и с REST API.
Приложение должно иметь необходимые разрешения для использования конечной точки. Дополнительные сведения см. в разделе Выбор разрешений для Приложение GitHub.
В следующем примере замените INSTALLATION_ACCESS_TOKEN
маркером доступа установки:
curl --request GET \
--url "https://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN"
Использование пакета SDK для Octokit.js для проверки подлинности в качестве установки приложения
Вы можете использовать пакет SDK для Octokit.js GitHub для проверки подлинности в качестве установки приложения. Одним из преимуществ использования пакета SDK для проверки подлинности является то, что вам не нужно создавать веб-маркер JSON (JWT) самостоятельно. Кроме того, пакет SDK позаботится о повторном создании маркера доступа к установке, поэтому вам не нужно беспокоиться об истечении одного часа.
Чтобы использовать библиотеку Octokit.js, необходимо установить и импортировать octokit
ее. В следующем примере используются операторы импорта в соответствии с ES6. Дополнительные сведения о различных методах установки и импорта см . в разделе использование файла сведений Octokit.js.
Использование Octokit.js для проверки подлинности с помощью идентификатора установки
-
Получите идентификатор приложения. Идентификатор приложения можно найти на странице параметров приложения. Для приложений, принадлежащих пользователю, страница параметров имеет значение
https://github.com/settings/apps/APP-SLUG
. Для приложений, принадлежащих организации, страница параметров имеет значениеhttps://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
. ЗаменитеAPP-SLUG
на slugified имя приложения. ЗаменитеORGANIZATION
на slugified имя вашей организации. Например,https://github.com/organizations/octo-org/settings/apps/octo-app
. -
Создайте закрытый ключ. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.
-
Получите идентификатор установки, для которой требуется пройти проверку подлинности.
Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.
Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с конечными точками
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
илиGET /app/installations
. Дополнительные сведения см. в разделе Приложения GitHub. -
Импорт
App
изoctokit
. Создайте новый экземпляр классаApp
. В следующем примере заменитеAPP_ID
ссылкой на идентификатор приложения. ЗаменитеPRIVATE_KEY
ссылкой на закрытый ключ приложения.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
-
Используйте метод для
getInstallationOctokit
создания экземпляра, прошедшего проверку подлинностиoctokit
. В следующем примере заменитеINSTALLATION_ID
идентификатором установки приложения, от имени которого требуется пройти проверку подлинности.JavaScript const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
octokit
Используйте метод для выполнения запроса к API.Приложение должно иметь необходимые разрешения для использования конечной точки. Дополнительные сведения см. в разделе Выбор разрешений для Приложение GitHub.
Например, чтобы выполнить запрос к API GraphQL:
JavaScript await octokit.graphql(` query { viewer { login } } `)
Например, чтобы выполнить запрос к REST API, выполните следующие действия:
JavaScript await octokit.request("GET /meta")
Использование Octokit.js для проверки подлинности в ответ на событие веб-перехватчика
Пакет SDK для Octokit.js также передает предварительно прошедший проверку подлинности octokit
экземпляр в обработчики событий веб-перехватчика.
-
Получите идентификатор приложения. Идентификатор приложения можно найти на странице параметров приложения. Для приложений, принадлежащих пользователю, страница параметров имеет значение
https://github.com/settings/apps/APP-SLUG
. Для приложений, принадлежащих организации, страница параметров имеет значениеhttps://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
. ЗаменитеAPP-SLUG
на slugified имя приложения. ЗаменитеORGANIZATION
на slugified имя вашей организации. Например,https://github.com/organizations/octo-org/settings/apps/octo-app
. -
Создайте закрытый ключ. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.
-
Получите секрет веб-перехватчика, указанный в параметрах приложения. Дополнительные сведения о секретах веб-перехватчика см. в разделе Использование веб-перехватчиков с приложениями GitHub.
-
Импорт
App
изoctokit
. Создайте новый экземпляр классаApp
. В следующем примере заменитеAPP_ID
ссылкой на идентификатор приложения. ЗаменитеPRIVATE_KEY
ссылкой на закрытый ключ приложения. ЗаменитеWEBHOOK_SECRET
секретом веб-перехватчика приложения.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
app.webhooks.*
Используйте метод для обработки событий веб-перехватчика. Дополнительные сведения см. в разделе Веб-перехватчики Octokit.js readme. Например, чтобы создать комментарий к проблеме при ее открытии, выполните следующие действия.app.webhooks.on("issues.opened", ({ octokit, payload }) => { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.issue.number, body: `This is a bot post in response to this issue being opened.`, } ) });