GitHub REST API のクイックスタート

はじめに

この記事では、GitHub CLI、curl、または JavaScript を使用して、GitHub REST API の使用をすばやく開始する方法について説明します。さらに詳しいガイドについては、「REST API を使用した作業の開始」をご覧ください。

コマンドラインでの GitHub CLI の使用

GitHub CLI は、コマンドラインから GitHub REST API を使用する方法として最も簡単です。

macOS、Windows、または Linux に GitHub CLI をインストールします。詳細については、GitHub CLI リポジトリ内でのインストールを参照してください。
ターミナルからこのコマンドを実行して、GitHub で認証します。HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。たとえば、octo-inc.ghe.com です。
```
gh auth login --hostname HOSTNAME
```
画面の指示に従います。

GitHub CLI は、Git 操作の優先プロトコルとして HTTPS を選択すると自動的に Git 資格情報を格納し、GitHub 資格情報で Git に対して認証するかどうかを尋ねるプロンプトに対して "はい" と答えます。これは、別の資格情報マネージャーを設定したり、SSH を使用したりすることなく、git push、git pull などの Git コマンドを使用できるので便利です。
GitHub CLI api サブコマンドにパスを続けて使用して要求を行います。メソッドを指定するには、--method または -X フラグを使用します。詳しくは、GitHub CLIapi のドキュメントを参照してください。

この例では、メソッド GET とパス /octocat を使用する "Get Octocat" エンドポイントに要求を行います。このエンドポイントの完全なリファレンスドキュメントについては、「メタデータ用 REST API エンドポイント」をご覧ください。
Shell
```
gh api /octocat --method GET
```
```
gh api /octocat --method GET
```

GitHub Actions での GitHub CLI の使用

GitHub Actions ワークフローでは、GitHub CLI を使用することもできます。詳しくは、「ワークフローで GitHub CLI を使用する」を参照してください。

gh auth login コマンドを使用するのでなく、アクセストークンを GH_TOKEN という環境変数として渡します。 GitHub では、トークンを作成するのでなく組み込みの GITHUB_TOKEN を使用することをお勧めしています。これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で GITHUB_TOKEN を実際のシークレットの名前に置き換えます。 GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

次のワークフロー例では、"リポジトリの issue の一覧表示" エンドポイントを使用し、指定したリポジトリ内の issue の一覧を要求します。HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 REPO-OWNER をリポジトリを所有するアカウントの名前に置き換えます。 REPO-NAME をリポジトリ所有者の名前に置き換えます。

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

GitHub App による認証

GitHub App を使用して認証する場合は、ワークフロー内にインストールアクセストークンを作成します。

GitHub App の ID を構成変数として保存します。以下の例で、APP_ID を構成変数の名前に置き換えます。アプリ ID は、アプリの設定ページで、あるいは API を通じて確認できます。詳しくは、「GitHub Apps用 REST API エンドポイント」を参照してください。構成オプションの詳細については「変数に情報を格納する」を参照してください。
アプリケーションの秘密鍵を生成してください。作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。詳しくは、「GitHub Apps の秘密キーの管理」を参照してください。シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

トークンを生成するステップを追加し、GITHUB_TOKEN ではなくそのトークンを使用します。このトークンは 60 分後に期限切れになるので注意してください。例:

YAML

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues


on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

Octokit.js の使用

Octokit.js を使用すれば、JavaScript スクリプト内で GitHub REST API とやりとりすることができます。詳しくは、「REST API と JavaScript を使用したスクリプト」をご覧ください。

アクセストークンを作成します。たとえば、personal access token または GitHub App のユーザーアクセストークンを作成します。このトークンを使用して要求を認証するため、そのエンドポイントへのアクセスに必要なスコープまたはアクセス許可を付与する必要があります。詳しくは、「REST API に対する認証」または「GitHub アプリのユーザーの特定と認可」を参照してください。

Warning

アクセストークンは、パスワードと同様に扱います。

トークンを安全な状態に保つには、ご利用のトークンをシークレットとして格納し、GitHub Actions を介してスクリプトを実行します。詳しくは、「GitHub Actions での Octokit.js の使用」セクションを参照してください。

これらのオプションを使用できない場合は、別の CLI サービスを使用してトークンを安全に格納することを検討してください。
octokitをインストールする。たとえば、「 npm install octokit 」のように入力します。 octokit をインストールまたは読み込むための他の方法については、Octokit.js の README を参照してください。
スクリプトで octokit をインポートします。たとえば、「 import { Octokit } from "octokit"; 」のように入力します。その他の octokit のインポート方法については、Octokit.js の README を参照してください。
トークンで Octokit のインスタンスを作成します。HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。YOUR-TOKEN はトークンに置き換えます。
JavaScript
```
const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN'
});
```
```
const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN'
});
```
octokit.request を使用して、要求を実行します。 HTTP メソッドとパスを最初の引数として送信します。オブジェクト内のパス、クエリ、および本文のパラメーターを 2 番目の引数として指定します。パラメーターの詳細については、「REST API を使用した作業の開始」を参照してください。

たとえば、次の要求では、HTTP メソッドは GET、パスは /repos/{owner}/{repo}/issues、パラメーターは owner: "REPO-OWNER" と repo: "REPO-NAME" です。REPO-OWNER はリポジトリを所有するアカウントの名前に、REPO-NAME はリポジトリの名前に置き換えます。
JavaScript
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```

GitHub Actions での Octokit.js の使用

また、GitHub Actions ワークフローで JavaScript スクリプトを実行することもできます。詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

アクセストークンを使用した認証

GitHub では、トークンを作成するのでなく組み込みの GITHUB_TOKEN を使用することをお勧めしています。これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で GITHUB_TOKEN を実際のシークレットの名前に置き換えます。 GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

次のワークフロー例を参照してください。

リポジトリのコンテンツをチェックアウトする
Node.js を設定する
octokit をインストールする
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@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        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 }}

ファイルパス .github/actions-scripts/use-the-api.mjs を含む JavaScript スクリプトの例を次に示します。HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 REPO-OWNER をリポジトリを所有するアカウントの名前に置き換えます。 REPO-NAME をリポジトリ所有者の名前に置き換えます。

import { Octokit } from "octokit"

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "REPO-OWNER",
      repo: "REPO-NAME",
    });

  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 による認証

GitHub App を使用して認証する場合は、ワークフロー内にインストールアクセストークンを作成します。

GitHub App の ID を構成変数として保存します。以下の例で、APP_ID を構成変数の名前に置き換えます。アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。詳しくは、「GitHub Apps用 REST API エンドポイント」を参照してください。構成オプションの詳細については「変数に情報を格納する」を参照してください。
アプリケーションの秘密鍵を生成してください。作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。詳しくは、「GitHub Apps の秘密キーの管理」を参照してください。シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

トークンを生成するステップを追加し、GITHUB_TOKEN ではなくそのトークンを使用します。このトークンは 60 分後に期限切れになるので注意してください。次に例を示します。


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

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

      - name: Install dependencies
        run: npm install octokit

      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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` を使用する

Note

コマンドラインから API 要求を行う場合、GitHub では、GitHub CLI を使用することをお勧めします。これにより、認証と要求が簡略化されます。 GitHub CLI を使用して REST API の使用を開始する方法について詳しくは、この記事の GitHub CLI バージョンを参照してください。

curl がまだコンピューターにインストールされていない場合は、インストールします。 curl がインストールされているかどうかを確認するには、コマンドラインで curl --version を実行します。出力が curl のバージョンに関する情報であれば、curl がインストールされているということです。 command not found: curl のようなメッセージが表示された場合は、curl をダウンロードしてインストールする必要があります。詳しくは、curl プロジェクトのダウンロードに関するページを参照してください。
アクセストークンを作成します。たとえば、personal access token または GitHub App のユーザーアクセストークンを作成します。このトークンを使用して要求を認証するため、エンドポイントへのアクセスに必要なスコープまたはアクセス許可を付与する必要があります。詳しくは、「REST API に対する認証」を参照してください。

Warning

アクセストークンは、パスワードと同様に扱います。

curl ではなく GitHub CLI を使用することもできます。認証は GitHub CLI によって自動的に処理されます。詳しくは、このページの GitHub CLI バージョンを参照してください。

これらのオプションを使用できない場合は、別の CLI サービスを使用してトークンを安全に格納することを検討してください。
curl コマンドを使用して要求を行います。 Authorization ヘッダーのトークンを渡します。HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 REPO-OWNER をリポジトリを所有するアカウントの名前に置き換えます。 REPO-NAME をリポジトリの名前に置き換えます。 YOUR-TOKEN をトークンに置き換えます。
Shell
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
Note

ほとんどの場合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができます。ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer を使用する必要があります。

GitHub Actions での `curl` コマンドの使用

GitHub Actions ワークフローでも curl コマンドを使用できます。

アクセストークンを使用した認証

次の例では、HOSTNAME はお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 REPO-OWNER をリポジトリを所有するアカウントの名前に置き換えます。 REPO-NAME をリポジトリ所有者の名前に置き換えます。

YAML

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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

GitHub App による認証

GitHub App を使用して認証する場合は、ワークフロー内にインストールアクセストークンを作成します。

GitHub App の ID を構成変数として保存します。以下の例で、APP_ID を構成変数の名前に置き換えます。アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。詳しくは、「GitHub Apps用 REST API エンドポイント」を参照してください。構成オプションの詳細については「変数に情報を格納する」を参照してください。
アプリケーションの秘密鍵を生成してください。作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。詳しくは、「GitHub Apps の秘密キーの管理」を参照してください。シークレットの保管の詳細については、「GitHub Actions でのシークレットの使用」を参照してください。

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"


on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

次の手順

詳しいガイドについては、「REST API を使用した作業の開始」をご覧ください。

Tool navigation

この記事の内容

はじめに

コマンドラインでの GitHub CLI の使用

GitHub Actions での GitHub CLI の使用

アクセストークンを使用した認証

GitHub App による認証

Octokit.js の使用

GitHub Actions での Octokit.js の使用

アクセストークンを使用した認証

GitHub App による認証

コマンドラインで `curl` を使用する

GitHub Actions での `curl` コマンドの使用

アクセストークンを使用した認証

GitHub App による認証

次の手順