Проверка подлинности в качестве установки Приложение GitHub

Сведения об установке 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.`,
      
    }
  )
});
```