Сведения о проверке подлинности в виде установки GitHub App
После установки данных GitHub App в учетной записи вы можете выполнить проверку подлинности в качестве установки приложения для запросов API. Это позволяет приложению получать доступ к ресурсам, принадлежащим этой установке, если приложению предоставлен необходимый доступ к репозиторию и разрешения. Запросы API, сделанные установкой приложения, относятся к приложению. Дополнительные сведения об установке приложений GitHub см. в разделе "Установка приложений GitHub".
Например, если вы хотите, чтобы приложение изменило Status
поле проблемы в проекте, принадлежащей организации с именем "octo-org", вы будете проходить проверку подлинности в качестве установки окто-организации приложения. В временная шкала проблемы будет указано, что ваше приложение обновило состояние.
Чтобы выполнить запрос API в качестве установки, необходимо сначала создать маркер доступа к установке. Затем вы отправите маркер доступа к установке в заголовке Authorization
последующих запросов API. Вы также можете использовать , которые могут создать маркер доступа к установке.
Некоторые конечные точки REST API не принимают маркеры доступа к установке, и большинство конечных точек REST API требуют от приложения определенных разрешений на использование конечной точки. Чтобы узнать, принимает ли конечная точка REST API маркеры доступа к установке и чтобы узнать, какие разрешения необходимы, см. в документации по конечной точке.
Установка приложений также может использовать 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 или API GraphQL. Срок действия маркера доступа к установке истекает через 1 час.
Создание маркера доступа к установке
-
Создайте веб-токен JSON (JWT) для приложения. Дополнительные сведения см. в разделе "Создание веб-маркера JSON (JWT) для приложения GitHub".
-
Получите идентификатор установки, которую требуется пройти проверку подлинности как.
Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.
Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с
GET /users/{username}/installation
помощью конечных точек илиGET /app/installations
конечныхGET /repos/{owner}/{repo}/installation``GET /orgs/{org}/installation
точек. Дополнительные сведения см. в разделе "Конечные точки REST API для GitHub Apps".Вы также можете найти идентификатор приложения на странице параметров приложения. Идентификатор приложения отличается от идентификатора клиента. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе "Изменение регистрации приложения GitHub".
-
Отправьте запрос REST API
POST
в/app/installations/INSTALLATION_ID/access_tokens
. Добавьте веб-токен JSON вAuthorization
заголовок запроса. ЗаменитеINSTALLATION_ID
идентификатором установки, которую требуется пройти проверку подлинности.Например, отправьте этот запрос curl. Замените
INSTALLATION_ID
идентификатором установки иJWT
веб-маркером JSON:curl --request POST \ --url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT" \ --header "X-GitHub-Api-Version: 2022-11-28"
При необходимости можно использовать
repositories
параметры илиrepository_ids
параметры тела для указания отдельных репозиториев, к которым может получить доступ маркер доступа к установке. Если вы не используетеrepositories
илиrepository_ids
не предоставляете доступ к определенным репозиториям, маркер доступа к установке будет иметь доступ ко всем репозиториям, к которым была предоставлена установка. Маркер доступа к установке не может быть предоставлен доступ к репозиториям, к которым установка не была предоставлена. Вы можете перечислить до 500 репозиториев.При необходимости используйте
permissions
параметр body, чтобы указать разрешения, которые должен иметь маркер доступа установки. Еслиpermissions
это не указано, маркер доступа к установке будет иметь все разрешения, предоставленные приложению. Маркер доступа к установке не может быть предоставлен разрешениям, которым приложение не было предоставлено.При использовании
permissions
параметров для уменьшения доступа к маркеру сложность маркера увеличивается из-за количества разрешений в запросе и количества репозиториев, к к которых будет иметь доступ маркер. Если сложность слишком велика, появится сообщение об ошибке, указывающее максимальное количество репозиториев, которые можно поддерживать. В этом случае необходимо запросить меньше разрешений с параметромpermissions
, использоватьrepositories
илиrepository_ids
параметр для запроса меньше репозиториев или установить приложение наall
репозитории в организации.Ответ будет включать маркер доступа к установке, время истечения срока действия маркера, разрешения, имеющиеся маркером, и репозитории, к которым может получить доступ маркер. Срок действия маркера доступа к установке истекает через 1 час.
Дополнительные сведения об этой конечной точке см. в разделе "Конечные точки REST API для GitHub Apps".
Примечание. В большинстве случаев передать маркер с помощью
Authorization: Bearer
илиAuthorization: token
. Однако при передаче веб-токена JSON (JWT) необходимо использоватьAuthorization: Bearer
.
Проверка подлинности с помощью маркера доступа к установке
Чтобы пройти проверку подлинности с помощью маркера доступа к установке, добавьте его в Authorization
заголовок запроса API. Маркер доступа будет работать как с API GraphQL, так и с REST API.
Приложение должно иметь необходимые разрешения для использования конечной точки. Дополнительные сведения см. в разделе Выбор разрешений для приложения GitHub.
В следующем примере замените INSTALLATION_ACCESS_TOKEN
маркер доступа на установку:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
Использование пакета SDK Octokit.js для проверки подлинности в качестве установки приложения
Для проверки подлинности в качестве установки приложения можно использовать пакет SDK Octokit.js GitHub. Одним из преимуществ использования пакета SDK для проверки подлинности является то, что вам не нужно создавать веб-токен JSON (JWT) самостоятельно. Кроме того, пакет SDK будет заботиться о повторном создании маркера доступа к установке, поэтому вам не нужно беспокоиться о истечении одного часа.
Чтобы использовать библиотеку Octokit.js, необходимо установить и импортировать octokit
ее. В следующем примере используются инструкции импорта в соответствии с ES6. Дополнительные сведения о различных методах установки и импорта см . в разделе об использовании Octokit.js README.
Использование Octokit.js для проверки подлинности с помощью идентификатора установки
-
Получите идентификатор данных GitHub App. Идентификатор приложения можно найти на странице параметров для GitHub App. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе "Изменение регистрации приложения GitHub".
-
Создайте закрытый ключ. Дополнительные сведения см. в разделе "Управление закрытыми ключами для приложений GitHub".
-
Получите идентификатор установки, которую требуется пройти проверку подлинности как.
Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.
Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с
GET /users/{username}/installation
помощью конечных точек илиGET /app/installations
конечныхGET /repos/{owner}/{repo}/installation``GET /orgs/{org}/installation
точек. Дополнительные сведения см. в разделе "Конечные точки REST API для GitHub Apps". -
Импорт
App
изoctokit
. Создайте новый экземпляр классаApp
. В следующем примере заменитеAPP_ID
ссылку на идентификатор приложения. ЗаменитеPRIVATE_KEY
ссылкой на закрытый ключ приложения.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
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);
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
octokit
Используйте метод для выполнения запроса к API.Приложение должно иметь необходимые разрешения для использования конечной точки. Дополнительные сведения см. в разделе Выбор разрешений для приложения GitHub.
Например, чтобы запросить API GraphQL:
JavaScript await octokit.graphql(` query { viewer { login } } `)
await octokit.graphql(` query { viewer { login } } `)
Например, чтобы выполнить запрос к REST API:
JavaScript await octokit.request("GET /meta")
await octokit.request("GET /meta")
Использование Octokit.js для проверки подлинности в ответ на событие веб-перехватчика
Пакет SDK Octokit.js также передает предварительно прошедший проверку подлинности octokit
экземпляр обработчикам событий веб-перехватчика.
-
Получите идентификатор данных GitHub App. Идентификатор приложения можно найти на странице параметров для GitHub App. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе "Изменение регистрации приложения GitHub".
-
Создайте закрытый ключ. Дополнительные сведения см. в разделе "Управление закрытыми ключами для приложений 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 }, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
app.webhooks.*
Используйте метод для обработки событий веб-перехватчика. Дополнительные сведения см . в разделе веб-перехватчиков README Octokit.js. Например, чтобы создать комментарий о проблеме при открытии проблемы: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.`, headers: { "x-github-api-version": "2022-11-28", }, } ) });