まくまくGitノート
GitHub REST API を使用する
2019-01-30

GitHub の REST API でできること

GitHub は Web API (REST API) を提供しており、コマンドラインや任意のアプリケーションから利用することで、GitHub の操作を自動化することができます。 Linux の curl コマンドや、スクリプト(Python や Ruby など)から簡単に利用できるので、Organization やリポジトリを管理する立場にある人はぜひ使ってみてください。

例えば、下記のようなことを REST API によって自動化することができます。

  • Users
    • 指定したユーザの詳細情報を取得する
    • 二要素認証が設定できていないユーザのリストを取得する
  • Projects
    • プロジェクトのリストを取得する
    • プロジェクトの詳細情報を取得する
    • プロジェクトを作成・変更・削除する
  • Organizations/Members
    • Organization 内のユーザリストを取得する
  • Pull Requests
    • Open 状態の Pull リクエストのリストを取得する

API トークンを発行する

REST API を呼び出すには、API トークン (HTTPS Access Token) が必要です。 プライベートリポジトリに関する情報を取得するには、そのリポジトリへのアクセス権限を持つユーザが作成した API トークンを使用して REST API を呼び出す必要があります。

GitHub の API トークンは下記のページで生成することができます。

Generate new token のボタンを押せば、新しいトークンを発行できます。 Select scope の項目で、そのトークンを使って使用できる機能 (API) の範囲を制御できるようになっているので、必要な機能のみにチェックを入れるようにしてください。

API トークンは次のようなハッシュ値です。 REST API を呼び出す際に必要になるので保存しておいてください。

c647c084ed5f60ee7fd53a22537fd6602ace4ced

REST API を呼び出す

REST API は単純な HTTP リクエストをベースに動作するため、Linux の curl コマンドなどを使って簡単に実行できます。

例: オープンな Pull Request の一覧を取得する (github-api.sh)

#!/bin/bash
GITHUB_TOKEN=9b671cc01a1d966f3a3d1dc3366867836aa19c5d
GITHUB_BASEURL=https://api.github.com
GITHUB_API=/repos/YourOrganization/YourProject/pulls?state=open

curl -k -s -u :$GITHUB_TOKEN $GITHUB_BASEURL$GITHUB_API

GITHUB_TOKEN 変数は自分で作成した API トークンに、GITHUB_API 変数は実行した API にそれぞれ置き換えて実行してください。

  • GITHUB_TOKEN: API トークン
  • GITHUB_API: 実行したい REST API

上記のサンプルコードでは、指定した Organization あるいはユーザ(ここでは YourOrganization) の、指定したリポジトリ (ここでは YourProject) のうち、オープン状態 (state=open) になっている Pull リクエストの一覧を取得しています。 結果は JSON 形式で出力されますが、長いのでここでは省略します。

GITHUB_API 変数は、他にも下記のような感じで置き換えて実行できます。 詳細は GitHub REST API のサイトを参照してください。

  • /users/MyName: 指定したユーザ (MyName) の詳細情報
  • /orgs/MyOrg/members: 指定した Organization (MyOrg) 内のメンバーリスト

ちなみに、上記の curl コマンド実行時に指定しているオプションの意味は下記の通りです。

  • -u USER:PASSWORD: Server user, password and login options
  • -k: Allow connections to SSL sites without certs
  • -s: Silent mode. Don’t output anything

プロキシ環境から curl 実行する場合

プロキシ環境内から実行する場合は、https_proxy 環境変数でプロキシサーバのアドレスとポート番号を設定してから実行してください。

$ export https_proxy=https://proxy.example.com:10080
$ ./github-api.sh

すべての結果が得られない場合

REST API の結果は、デフォルトではページネーションによって 30件ずつ しか返されません。 一度にたくさんの結果を取得するには、URL の末尾に per_page オプションを指定することで最大 100 件ずつ取得することができます。 それ以上の件数を取得するときは、page オプションを使用して取得位置を切り替える必要があります。

GITHUB_API=/user/repos?per_page=100&page=1  # 1~100件目のリポジトリ情報
GITHUB_API=/user/repos?per_page=100&page=2  # 101~200件目のリポジトリ情報
GITHUB_API=/user/repos?per_page=100&page=3  # 201~300件目のリポジトリ情報

ページの切り替え処理を自動化するのは若干面倒ですが、件数が多くても 500 件以下であることが分かっているのであれば、下記のように単純にループで取得してしまえば事足りるかもしれません。

GITHUB_API=/user/repos?per_page=100

# 100件の取得を5ページ分繰り返す
for i in `seq 1 5`; do
  curl -k -s -u :$GITHUB_TOKEN $GITHUB_BASEURL$GITHUB_API\&page=$i
done
2019-01-30