Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2023-01-18. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい

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

GitHub REST API の使用を開始する方法について説明します。

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

GitHub CLI を使用した作業の開始

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

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

  1. GitHub CLI をま� インストールしていない� �合は、インストールしてく� さい。 インストールの手� �については、GitHub CLI リポジトリを参照してく� さい。

  2. auth login サブコマンドを使用して、GitHub CLI に対する認証を行います。 詳しくは、GitHub CLIauth login のドキュメントを参照してく� さい。

    gh auth login
  3. api サブコマンドを使用して API 要求を行います。 詳しくは、GitHub CLIapi のドキュメントを参照してく� さい。

    gh api repos/octocat/Spoon-Knife/issues

GitHub Actions での GitHub CLI の使用

GitHub Actions ワークフローでは、GitHub CLI を使用することもできます。 詳しくは、「ワークフローでの 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 の ID をシークレットとして保存します。 以下の例では、APP_ID をシークレットの名前に置き換えます。 アプリ ID は、アプリの設定ページで、あるいは API を通じて確認できます。 詳しくは、REST API のドキュメントの「アプリ」をご覧く� さい。 シークレットについて詳しくは、「暗号化されたシークレット」を参照してく� さい。
  2. アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証」を参照してく� さい。
  3. トークンを生成するステップを追� し、GITHUB_TOKEN ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してく� さい。

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 を使用すれば、JavaScript スクリプト内で GitHub REST API とやりとりすることができます。 詳しくは、Octokit.js の README を参照してく� さい。

Octokit.js の使用

  1. アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザーからサーバーへのアクセス トークンを作成します。 詳しい情� �については、「personal access token の作成」か「GitHub App のユーザーの特定と認可」を参照してく� さい。

    警告: アクセス トークンはパスワードと同様に扱ってく� さい。

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

    これらのオプションが使用できない� �合は、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 メソッドとパスを最初の引数として送信します。 オブジェクト内のパス、クエリ、および本文のパラメーターを 2 番目の引数として指定します。 たとえば、次の要求では、HTTP メソッドは GET、パスは /repos/{owner}/{repo}/issues、パラメーターは owner: "octocat" および repo: "Spoon-Knife" となっています。

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

GitHub Actions での Octokit.js の使用

また、GitHub Actions ワークフローで JavaScript スクリプトを実行することもできます。 詳細については、「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@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        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 スクリプトの例:

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 の ID をシークレットとして保存します。 以下の例では、APP_ID をシークレットの名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳細については、「アプリ」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット」を参照してく� さい。
  2. アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証」を参照してく� さい。
  3. トークンを生成するステップを追� し、GITHUB_TOKEN ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してく� さい。

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

      - name: Setup Node
        uses: actions/setup-node@v2
        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 の使用

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

  1. cURL がま� コンピューターにインストールされていない� �合は、cURL をインストールします。 cURL がインストールされているかどうかを確認するには、コマンド ラインで curl --version を実行します。 出力が cURL バージョンに関する情� �である� �合は、cURL がインストールされています。 command not found: curl のようなメッセージが表示された� �合は、cURL をダウンロードしてインストールする必要があります。 詳しくは、cURL プロジェクトのダウンロードに関するページを参照してく� さい。

  2. アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザーからサーバーへのアクセス トークンを作成します。 詳しい情� �については、「personal access token の作成」か「GitHub App のユーザーの特定と認可」を参照してく� さい。

    警告: アクセス トークンは、パスワードと同様の扱いとしてく� さい。

    cURL ではなく GitHub CLI を使用することもできます。 認証は 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 Web トークン (JWT) を渡す� �合は、Authorization: Bearer を使用する必要があります。

GitHub Actions での cURL の使用

GitHub Actions ワークフローでも cURL を使用できます。

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 の ID をシークレットとして保存します。 以下の例では、APP_ID をシークレットの名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳細については、「アプリ」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット」を参照してく� さい。
  2. アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY----- および -----END RSA PRIVATE KEY----- を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証」を参照してく� さい。
  3. トークンを生成するステップを追� し、GITHUB_TOKEN ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してく� さい。

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 を使用した作業の開始」をご覧く� さい。