Skip to main content

Краткое руководство по GitHub REST API

Узнайте, как начать работу с REST API GitHub.

В этой статье описывается, как быстро приступить к работе с REST API GitHub с помощью GitHub CLI, JavaScript или curl. Дополнительные сведения см. в статье Начало работы с REST API.

Начало работы с GitHub CLI

Использование GitHub CLI в командной строке

GitHub CLI — это самый простой способ использовать REST API GitHub из командной строки.

  1. Установите GitHub CLI, если еще не установили. Инструкции по установке см. в репозитории GitHub CLI.

  2. Используйте подкоманду auth login для проверки подлинности в GitHub CLI: Дополнительные сведения см. в документации по auth loginGitHub CLI.

    gh auth login
  3. Используйте подкоманду api для выполнения запроса к API. Дополнительные сведения см. в документации по apiGitHub CLI.

    gh api repos/octocat/Spoon-Knife/issues

Использование GitHub CLI в GitHub Actions

Вы можете использовать GitHub CLI в рабочих процессах GitHub Actions. Дополнительные сведения см. в разделе Использование GitHub CLI в рабочих процессах.

Вместо того, чтобы использовать команду gh auth login, передайте маркер доступа в качестве переменной среды GH_TOKEN. GitHub рекомендует использовать встроенный GITHUB_TOKEN вместо создания маркера. Если это невозможно, сохраните маркер в качестве секрета и замените GITHUB_TOKEN в приведенном ниже примере именем секрета. Дополнительные сведения о GITHUB_TOKEN см. в разделе Автоматическая проверка подлинности маркера. Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

При проверке подлинности с помощью GitHub App можно создать маркер доступа к установке в рабочем процессе:

  1. Храните идентификатор GitHub App как секрет. В следующем примере замените APP_ID именем секрета. Идентификатор приложения можно найти на странице параметров приложения или через API. Дополнительные сведения см. в разделе "Приложения" в документации по REST API. Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

  2. Создайте закрытый ключ для приложения. Храните содержимое получившегося файла как секрет. (Сохраните все содержимое файла, включая -----BEGIN RSA PRIVATE KEY----- и -----END RSA PRIVATE KEY-----.) В следующем примере замените APP_PEM именем секрета. Дополнительные сведения см. в разделе Проверка подлинности с помощью GitHub Apps.

  3. Добавьте шаг для создания маркера и используйте его вместо GITHUB_TOKEN. Обратите внимание, что срок действия этого маркера истекает через 60 минут. Пример:

    # <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
    # <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>Они предоставляются сторонним поставщиком, и на них распространяются
    # <a name="separate-terms-of-service-privacy-policy-and-support"></a>отдельные условия обслуживания, политика конфиденциальности и поддержка
    # <a name="documentation"></a>документации.
    
    on:
      workflow_dispatch:
    jobs:
      track_pr:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
    
          - name: Use API
            env:
              GH_TOKEN: ${{ steps.generate_token.outputs.token }}
            run: |
              gh api repos/octocat/Spoon-Knife/issues
    

Начало работы с JavaScript

Вы можете использовать Octokit.js для взаимодействия с REST API GitHub в скриптах JavaScript. Дополнительные сведения см. в разделе Создание скриптов с помощью REST API и JavaScript.

Использование Octokit.js

  1. Создание маркера доступа Например, создайте маркер доступа пользователя к серверу personal access token или GitHub App. Дополнительные сведения см. в разделах Создание personal access tokenили Идентификация и авторизация пользователей для приложений GitHub.

    Предупреждение. Считайте маркер доступа своим паролем.

    Чтобы обеспечить безопасность маркера, вы можете хранить маркер в виде секрета и запустить скрипт с помощью GitHub Actions. Дополнительные сведения см. в разделе Использование Octokit.js в GitHub Actions.

    Вы также можете сохранить маркер в виде секрета Codespaces и запустить скрипт в Codespaces. Дополнительные сведения см. в разделе Управление зашифрованными секретами для ваших кодовых пространств.

    Если эти варианты недоступны, рассмотрите возможность безопасного хранения маркера с помощью другой службы, например 1Password CLI.

  2. Установить службы octokit. Например, npm install octokit. Другие способы установки или загрузки octokit см. в Octokit.js README.

  3. Импортируйте octokit в скрипт. Например, import { Octokit } from "octokit";. Другие способы импорта octokit см. в Octokit.js README.

  4. Создайте экземпляр Octokit с помощью маркера. Замените YOUR-TOKEN собственным маркером.

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. Используйте octokit.request для выполнения запроса. Отправьте метод HTTP и путь в качестве первого аргумента. Укажите любой путь, запрос и параметры текста в объекте в качестве второго аргумента. Например, в следующем запросе используется метод HTTP GET, путь — /repos/{owner}/{repo}/issuesи параметры owner: "octocat" и repo: "Spoon-Knife".

    await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });
    

Использование Octokit.js в GitHub Actions

Вы также можете выполнять скрипты JavaScript в рабочих процессах GitHub Actions. Дополнительные сведения см. в статье "Синтаксис рабочего процесса для GitHub Actions".

GitHub рекомендует использовать встроенный GITHUB_TOKEN вместо создания маркера. Если это невозможно, сохраните маркер в качестве секрета и замените GITHUB_TOKEN в приведенном ниже примере именем секрета. Дополнительные сведения о GITHUB_TOKEN см. в разделе Автоматическая проверка подлинности маркера. Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

См. следующий пример рабочего процесса:

  1. Извлекает содержимое репозитория.
  2. Настраивает Node.js.
  3. Устанавливает octokit.
  4. Сохраняет значение GITHUB_TOKEN как переменную среды TOKEN и выполняет .github/actions-scripts/use-the-api.mjs, которые могут получить доступ к этой переменной среды в качестве process.env.TOKEN

Пример рабочего процесса:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        run: |
          node .github/actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}

Пример скрипта JavaScript с путем к файлу .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit"

const octokit = new Octokit({
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

При проверке подлинности с помощью GitHub App можно создать маркер доступа к установке в рабочем процессе:

  1. Храните идентификатор GitHub App как секрет. В следующем примере замените APP_ID именем секрета. Идентификатор приложения можно найти на странице параметров приложения или через API приложений. Дополнительные сведения см. в разделе Приложения . Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

  2. Создайте закрытый ключ для приложения. Храните содержимое получившегося файла как секрет. (Сохраните все содержимое файла, включая -----BEGIN RSA PRIVATE KEY----- и -----END RSA PRIVATE KEY-----.) В следующем примере замените APP_PEM именем секрета. Дополнительные сведения см. в разделе Проверка подлинности с помощью GitHub Apps.

  3. Добавьте шаг для создания маркера и используйте его вместо GITHUB_TOKEN. Обратите внимание, что срок действия этого маркера истекает через 60 минут. Например:

    # <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
    # <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>Они предоставляются сторонним поставщиком, и на них распространяются
    # <a name="separate-terms-of-service-privacy-policy-and-support"></a>отдельные условия обслуживания, политика конфиденциальности и поддержка
    # <a name="documentation"></a>документации.
    
    on:
      workflow_dispatch:
    jobs:
      use_api_via_script:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repo content
            uses: actions/checkout@v3
    
          - name: Setup Node
            uses: actions/setup-node@v3
            with:
              node-version: '16.17.0'
              cache: npm
    
          - name: Install dependencies
            run: npm install octokit
    
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
    
          - name: Run script
            run: |
              node .github/actions-scripts/use-the-api.mjs
            env:
              TOKEN: ${{ steps.generate_token.outputs.token }}
    

Начало работы с использованием curl

Использование curl в командной строке

Примечания.

  • Следующий пример предназначен для GitHub.com. Если вы предпочитаете попробовать пример с помощью GitHub Enterprise Cloud, замените https://api.github.com https://api.github.comна , а замените HOSTNAME именем узла для . Также необходимо заменить octocat/Spoon-Knife репозиторием в GitHub Enterprise Cloud.
  • Если вы хотите выполнять запросы API из командной строки, GitHub рекомендует использовать GitHub CLI, что упрощает проверку подлинности и запросы. Дополнительные сведения о начале работы с REST API с помощью GitHub CLI см. в версии этой статьи для GitHub CLI.
  1. Установите curl , если он еще не установлен на компьютере. Чтобы проверить, установлен ли curl компонент, выполните команду curl --version в командной строке. Если выходные данные содержат сведения о версии curl, она устанавливается. Если появится сообщение, похожее на command not found: curl, необходимо скачать и установить curl. Дополнительные сведения см. на странице скачивания проекта curl.

  2. Создание маркера доступа Например, создайте маркер доступа пользователя к серверу personal access token или GitHub App. Дополнительные сведения см. в разделах Создание personal access tokenили Идентификация и авторизация пользователей для приложений GitHub.

    Предупреждение. Считайте маркер доступа своим паролем.

    В целях безопасности вы можете хранить маркер в виде секрета Codespaces и использовать командую строку в Codespaces. Дополнительные сведения см. в разделе Управление зашифрованными секретами для ваших кодовых пространств.

    Вместо можно также использовать GitHub CLI .curl GitHub CLI выполнит задачи по проверке подлинности. Дополнительные сведения см. в версии этой страницы для GitHub CLI.

    Если эти варианты недоступны, рассмотрите возможность безопасного хранения маркера с помощью другой службы, например 1Password CLI.

  3. Используйте команду curl для выполнения запроса. Передайте маркер в заголовок Authorization. Замените YOUR-TOKEN собственным маркером.

    curl --request GET \
    --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer YOUR-TOKEN"

    Примечание. В большинстве случаев передать маркер с помощью Authorization: Bearer или Authorization: token. Однако при передаче веб-токена JSON (JWT) необходимо использовать Authorization: Bearer.

Использование curl команд в GitHub Actions

Команды также можно использовать curl в рабочих процессах GitHub Actions.

GitHub рекомендует использовать встроенный GITHUB_TOKEN вместо создания маркера. Если это невозможно, сохраните маркер в качестве секрета и замените GITHUB_TOKEN в приведенном ниже примере именем секрета. Дополнительные сведения о GITHUB_TOKEN см. в разделе Автоматическая проверка подлинности маркера. Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

При проверке подлинности с помощью GitHub App можно создать маркер доступа к установке в рабочем процессе:

  1. Храните идентификатор GitHub App как секрет. В следующем примере замените APP_ID именем секрета. Идентификатор приложения можно найти на странице параметров приложения или через API приложений. Дополнительные сведения см. в разделе Приложения . Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

  2. Создайте закрытый ключ для приложения. Храните содержимое получившегося файла как секрет. (Сохраните все содержимое файла, включая -----BEGIN RSA PRIVATE KEY----- и -----END RSA PRIVATE KEY-----.) В следующем примере замените APP_PEM именем секрета. Дополнительные сведения см. в разделе Проверка подлинности с помощью GitHub Apps.

  3. Добавьте шаг для создания маркера и используйте его вместо GITHUB_TOKEN. Обратите внимание, что срок действия этого маркера истекает через 60 минут. Например:

    # <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
    # <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>Они предоставляются сторонним поставщиком, и на них распространяются
    # <a name="separate-terms-of-service-privacy-policy-and-support"></a>отдельные условия обслуживания, политика конфиденциальности и поддержка
    # <a name="documentation"></a>документации.
    
    on:
      workflow_dispatch:
    jobs:
      use_api:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
    
          - name: Use API
            env:
              GH_TOKEN: ${{ steps.generate_token.outputs.token }}
            run: |
              curl --request GET \
              --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
              --header "Accept: application/vnd.github+json" \
              --header "Authorization: Bearer $GH_TOKEN"
    

Дальнейшие действия

Дополнительные сведения см. в статье Начало работы с REST API.