この記事では、GitHub CLI、JavaScript、または cURL を使用して、GitHub REST API の使用をすばやく開始する方法について説明します。 詳しいガイドについては、「REST API を使用した作業の開始 」をご覧く� さい。
GitHub CLI を使用した作業の開始
コマンド ラインでの GitHub CLI の使用
GitHub CLI は、コマンド ラインから GitHub REST API を使用する方法として最も簡単です。
GitHub CLI をま� インストールしていない� �合は、インストールしてく� さい。 インストールの手� �については、GitHub CLI リポジトリ を参照してく� さい。
auth login
サブコマンドを使用して、GitHub CLI に対する認証を行います。 詳しくは、GitHub CLIauth login
のドキュメント を参照してく� さい。
gh auth login
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 を使用して認証する� �合は、ワークフロー内にインストール アクセス トークンを作成します。
GitHub App の ID をシークレットとして保存します。 以下の例では、APP_ID
をシークレットの名前に置き換えます。 アプリ ID は、アプリの設定ページで、あるいは API を通じて確認できます。 詳しくは、REST API のドキュメントの「アプリ 」をご覧く� さい。 シークレットについて詳しくは、「暗号化されたシークレット 」を参照してく� さい。
アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY-----
および -----END RSA PRIVATE KEY-----
を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM
をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証 」を参照してく� さい。
トークンを生成するステップを追� し、GITHUB_TOKEN
ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
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 の使用
アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザーからサーバーへのアクセス トークンを作成します。 詳しい情� �については、「personal access token の作成 」か「GitHub App のユーザーの特定と認可 」を参照してく� さい。
警告 : アクセス トークンはパスワードと同様に扱ってく� さい。
トークンを安全な状態に保つには、ご利用のトークンをシークレットとして� �納し、GitHub Actions を介してスクリプトを実行します。 詳しくは、「GitHub Actions での Octokit.js の使用 」セクションを参照してく� さい。
これらのオプションが使用できない� �合は、1Password CLI などの別のサービスを使用してトークンを安全に� �納することを検討してく� さい。
octokit
をインストールする。 たとえば、「 npm install octokit
」のように入力します。 octokit
をインストールまたは読み込むための他の方法については、Octokit.js の README を参照してく� さい。
スクリプトで octokit
をインポートします。 たとえば、「 import { Octokit } from "octokit";
」のように入力します。 その他の octokit
のインポート方法については、Octokit.js の README を参照してく� さい。
実際のトークンを指定して Octokit
のインスタンスを作成します。 YOUR-TOKEN
を実際のトークンに置き換えます。
const octokit = new Octokit ({
auth : 'YOUR-TOKEN'
});
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
について詳しくは、「自動トークン認証 」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット 」を参照してく� さい。
次のワークフロー例を参照してく� さい。
リポジトリのコンテンツをチェックアウトする
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@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 を使用して認証する� �合は、ワークフロー内にインストール アクセス トークンを作成します。
GitHub App の ID をシークレットとして保存します。 以下の例では、APP_ID
をシークレットの名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳細については、「アプリ 」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット 」を参照してく� さい。
アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY-----
および -----END RSA PRIVATE KEY-----
を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM
をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証 」を参照してく� さい。
トークンを生成するステップを追� し、GITHUB_TOKEN
ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
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 バージョンを参照してく� さい。
cURL がま� コンピューターにインストールされていない� �合は、cURL をインストールします。 cURL がインストールされているかどうかを確認するには、コマンド ラインで curl --version
を実行します。 出力が cURL バージョンに関する情� �である� �合は、cURL がインストールされています。 command not found: curl
のようなメッセージが表示された� �合は、cURL をダウンロードしてインストールする必要があります。 詳しくは、cURL プロジェクトのダウンロードに関するページ を参照してく� さい。
アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザーからサーバーへのアクセス トークンを作成します。 詳しい情� �については、「personal access token の作成 」か「GitHub App のユーザーの特定と認可 」を参照してく� さい。
警告 : アクセス トークンは、パスワードと同様の扱いとしてく� さい。
cURL ではなく GitHub CLI を使用することもできます。 認証は GitHub CLI によって自動的に処理されます。 詳しくは、このページの GitHub CLI バージョンを参照してく� さい。
これらのオプションが使用できない� �合は、1Password CLI などの別のサービスを使用してトークンを安全に� �納することを検討してく� さい。
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 を使用して認証する� �合は、ワークフロー内にインストール アクセス トークンを作成します。
GitHub App の ID をシークレットとして保存します。 以下の例では、APP_ID
をシークレットの名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳細については、「アプリ 」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット 」を参照してく� さい。
アプリケーションの秘密鍵を生成してく� さい。 作成されたファイルの内容をシークレットとして保存します。 (-----BEGIN RSA PRIVATE KEY-----
および -----END RSA PRIVATE KEY-----
を含め、ファイルの内容全体を保存します)。以下の例では、APP_PEM
をシークレットの名前に置き換えます。 詳細については、「GitHub Apps による認証 」を参照してく� さい。
トークンを生成するステップを追� し、GITHUB_TOKEN
ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してく� さい。 次に例を示します。
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 を使用した作業の開始 」をご覧く� さい。