GitHub Appsでリポジトリにファイル追加・更新 / magicien　

GitHub Appsでリポジトリにファイル追加・更新する手順メモ。ゲームエディタの編集データをGitHubに保存したいと思ったので。手元のMacBook Airの空き容量は500MBくらいで虫の息。シンクライアント的な使い方しかできない状態なのです。

はじめに。GitHub Appsで新規リポジトリを作ろうとしたけどだめだった。ユーザ側でAppを使うリポジトリを決める必要があるので、App側で勝手にリポジトリを追加することはできないのかも。OAuth Appsなら作成できるはずなので、やるとすれば、一旦OAuthで作成してから、GitHub Appでそのリポジトリをアクセス対象に追加する感じかな（Appが2つ必要だとするとユーザ側の操作もかなり面倒なことに...）よくよく見たら、APIの説明に「Currently, only the organization endpoint is enabled for GitHub Apps.」って書いてあったぁぁぁ。Organizationで試してみたら問題なくリポジトリ作れたぁぁぁ。ゲームエディタ用Organization作ってそこでリポジトリ管理することにしよう。その方が安全だし。

GitHub Apps作成

ここら辺はずいぶん前の話で忘れてしまったため適当。

Developer Memberに登録

事前にメンバー登録が必要だったと思う。登録に手間取った記憶がないので、要求されたものを入力しただけだったはず。

App作成

ここの手順通りに実施したはず。
登録手順の前に、GitHub AppsとOAuth Appsの二種類があって、こんな違いがありますよーみたいな話が延々と書いてあって手順を見つけるのに苦労した。

App情報を確認

「Setting > GitHub Apps > アプリ名」を選ぶと、アプリ情報の一覧が表示される。最下部にある「OAuth credentials」の「Client ID」「Client secret」を認証に使うので覚えておく。
「Private key」も必要なので、「Generate private key」ボタンを押して生成、覚えておく。

認証用トークン生成準備

認証には JSON Web Token（JWT）なるものを使うので、それを生成する何らかの仕組みを用意する必要がある。
JWTのページにライブラリがたくさんあるので、良さげなものを選ぶ。
自分はサーバでPHPを使っているので、lcobucci/jwtにした。
JWT生成コードはこんな感じ。 Private Keyはボタンを押して生成したものを貼り付け。setIssuerに指定するIDは「Settings > GitHub Apps」で見られる。
有効期限は最大10分なので、手動でのんびり実行していると時間切れになってしまう。

作ったAppのインストール

もしかしたらアプリ生成の時にインストール先を選択済みかも。インストールしていない場合は、
「https://github.com/apps/アプリ名」にアクセスすると、インストールできる。

操作対象のリポジトリを決める

ユーザを判別する

まずは誰がAppを使おうとしているのか判別する。公式の説明はここ。
ユーザに下記URLにGETでアクセスしてもらう。（child_idはApp登録時にメモしたもの）

stateはリクエストフォージェリ対策で付けておくと良さげ。何か情報を受けわたす為に使っても良い、とのこと。
https://github.com/login/oauth/authorize?child_id=ChildID&redirect_uri=自分のサイトのどこか&state=ランダムな文字列

すると、アプリが認証を要求してるけど？というページが表示される。ユーザが「良いよ！」ということであれば、redirect_uriで指定したURLに戻ってくる。が、この時、codeパラメータが追加されている。stateが先ほど付けたものと同じかどうかをチェックすると良さげ。
https://自分のサイト/どこかのページ.html?code=1234567890abcdef&state=先ほどのstate

アクセストークン生成

ここから先はサーバ・GitHub間でゴリゴリする。
先ほど返ってきたcodeを使ってアクセストークンを生成する。（JWTを使った認証とは別なので要注意）

curl -X POST -d "code=先ほどのcode" -d "client_id=ClientID" -d "client_secret=ClientSecret" https://github.com/login/oauth/access_token

一応、redirect_urlで次のリダイレクト先を指定できるけど、クライアント側からclient_secretを送ることは無いと思うので使い道なさげ。stateも指定できるけど同じ理由で使い道無さげ（GitHub側でcodeとstateの組をチェックしている様子は無かった）。応答はこんな感じで返ってくる。
access_token=アクセストークン&scope=&token_type=bearer

ユーザが使っているApp（Installation）のIDを取得する

Github AppのIDとは別に、ユーザ・App毎にIDが割り当てられているので、それを取得する。
現状、Acceptヘッダを付けないと怒られるけど、そのうち要らなくなるはず。
curl -H "Authorization: token アクセストークン" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/user/installations
応答はJSONで返ってくる。

{
  "total_count": 1,
  "installations": [
    {
      "id": 56789,
      中略
      "integration_id": 1234,
      "app_id": 1234,
    }
  ],
  "integration_installations": [
    {
      "id": 56789,
      中略
      "integration_id": 1234,
      "app_id": 1234,
    }
  ]
}

installations[i].app_id が一致するものを見つけて、installations[i].id を取得する。integration_installationsに全く同じ情報が入ってるんだけど、どっちを見るべきかよくわからん。

アクセスできるリポジトリ一覧を取得する

先ほど取得したinstallationのidを使って、リポジトリ一覧を取得する。
アプリとしては、ユーザに一覧を表示して選んでもらう感じになると思う。
curl -H "Authorization: token アクセストークン" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/user/installations/さっき取得したinstallationのid/repositories
応答はJSONで返ってくる。今回は repositories[].full_name が分かれば良い。

{
  "total_count": 1,
  "repositories": [
    {
      "id": リポジトリID,
      "name": "リポジトリ名",
      "full_name": "ユーザ名/リポジトリ名",
      中略
    }
  ]
}

Installationとしての認証

これ要る？公式の説明はここ。
先ほど取得したアクセストークンだとリポジトリ操作ができないようなので、Installation用のアクセストークンを別途取得する。
最初の方で準備しておいたJWTのトークンを生成して、次のコマンドを実行する。
curl -X POST -H "Authorization: Bearer JWTのトークン" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/installations/先ほど取得したinstallationのid/access_tokens
応答はJSONで返ってくる。

{
  "token": "アクセストークンその２",
  "expires_at": "2017-01-01T00:00:00Z"
}

ファイルを追加する

ようやくファイルを追加する。公式の説明はここ。
curl -X PUT -H "Authorization: token アクセストークンその２" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/repos/ユーザ名/リポジトリ名/contents/ファイルパス -d '{"path":"ファイルパス","message":"commitメッセージ","content":"ファイルの内容"}'
オプションでcomitterの情報も付けられる。デフォルトだと、Appのbotがcomitterになる。branchでブランチの指定も可。
contentはbase64にエンコードしないといけないので、base64コマンドを使うなりして変換しておく。

ファイルを更新する

ファイルを追加する場合とほぼ同じ。唯一の違いは、元のファイルのshaを指定すること。

元ファイルのshaを取得する

認証トークンは特に要らない。
curl https://api.github.com/repos/ユーザ名/リポジトリ名/contents/ファイルパス
応答はJSON形式。

{
    中略
    "sha": "ハッシュ値",
    中略
}

ファイル更新

curl -X PUT -H "Authorization: token アクセストークンその２" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/repos/ユーザ名/リポジトリ名/contents/ファイルパス-d '{"path":"ファイルパス","message":"commitメッセージ","content":"ファイルの内容", "sha":"ハッシュ値"}'