Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.

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

Вы можете выполнить проверку подлинности GitHub App как установку, чтобы выполнять запросы API, влияющие на ресурсы, принадлежащие учетной записи, в которой установлено приложение.

Сведения об установке 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 час.

Создание маркера доступа установки

  1. Создайте веб-токен JSON (JWT) для приложения. Дополнительные сведения см. в разделе Создание веб-токена JSON (JWT) для Приложение GitHub.

  2. Получите идентификатор установки, для которой требуется пройти проверку подлинности.

    Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.

    Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с конечными точками GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installationили GET /app/installations . Дополнительные сведения см. в разделе Приложения GitHub.

  3. Отправьте запрос 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"

    При необходимости можно использовать 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 "http(s)://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 для проверки подлинности с помощью идентификатора установки

  1. Получите идентификатор приложения. Идентификатор приложения можно найти на странице параметров приложения. Для приложений, принадлежащих пользователю, страница параметров имеет значение 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.

  2. Создайте закрытый ключ. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.

  3. Получите идентификатор установки, для которой требуется пройти проверку подлинности.

    Если вы отвечаете на событие веб-перехватчика, полезные данные веб-перехватчика будут содержать идентификатор установки.

    Вы также можете использовать REST API для поиска идентификатора для установки приложения. Например, можно получить идентификатор установки с конечными точками GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installationили GET /app/installations . Дополнительные сведения см. в разделе Приложения GitHub.

  4. Импорт App из octokit. Создайте новый экземпляр класса App. В следующем примере замените APP_ID ссылкой на идентификатор приложения. Замените PRIVATE_KEY ссылкой на закрытый ключ приложения.

    JavaScript
    import { App } from "octokit";
    
    const app = new App({
      appId: APP_ID,
      privateKey: PRIVATE_KEY,
    });
  5. Используйте метод для getInstallationOctokit создания экземпляра, прошедшего проверку подлинности octokit . В следующем примере замените INSTALLATION_ID идентификатором установки приложения, от имени которого требуется пройти проверку подлинности.

    JavaScript
    const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
  6. 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 экземпляр в обработчики событий веб-перехватчика.

  1. Получите идентификатор приложения. Идентификатор приложения можно найти на странице параметров приложения. Для приложений, принадлежащих пользователю, страница параметров имеет значение 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.

  2. Создайте закрытый ключ. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.

  3. Получите секрет веб-перехватчика, указанный в параметрах приложения. Дополнительные сведения о секретах веб-перехватчика см. в разделе Использование веб-перехватчиков с приложениями GitHub.

  4. Импорт 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 },
    });
  5. 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.`,
          
        }
      )
    });