はじめに
この記事では、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
をリポジトリ所有者の名前に置き換えます。
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 アプリのユーザーの特定と認可」を参照してください。
警告: アクセス トークンは、パスワードと同様の扱いとしてください。
トークンを安全な状態に保つには、ご利用のトークンをシークレットとして格納し、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
を使用する
注: コマンド ラインから 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 に対する認証」を参照してください。
警告: アクセス トークンは、パスワードと同様の扱いとしてください。
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"
注: ほとんどの場合は、
Authorization: Bearer
またはAuthorization: token
を使用してトークンを渡すことができます。 ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer
を使用する必要があります。
GitHub Actions での curl
コマンドの使用
GitHub Actions ワークフローでも curl
コマンドを使用できます。
アクセス トークンを使用した認証
GitHub では、トークンを作成するのでなく組み込みの GITHUB_TOKEN
を使用することをお勧めしています。 これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で GITHUB_TOKEN
を実際のシークレットの名前に置き換えます。 GITHUB_TOKEN
について詳しくは、「自動トークン認証」をご覧ください。 シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。
次の例では、HOSTNAME
は お使いの GitHub Enterprise Server インスタンス の名前に置き換えます。 REPO-OWNER
をリポジトリを所有するアカウントの名前に置き換えます。 REPO-NAME
をリポジトリ所有者の名前に置き換えます。
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 でのシークレットの使用」を参照してください。 -
トークンを生成するステップを追加し、
GITHUB_TOKEN
ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してください。 例: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 を使用した作業の開始」をご覧ください。