はじめに
GitHubと連携して何かをする場合、以下の4つの方法があるかと思います。
どういう時にどの連携方法を選ぶと良いのかをいまいち把握していなかったのでざっくりと整理しました。
GitHubとの連携方法
どの方法も基本的には次のような関係がベースにあります。
Webhookとは、例えば「PRが作成された」「イシューにコメントがされた」というようなイベント情報を指定されたアドレスにHTTPで知らせる仕組みです。GitHub Actionsではもっと抽象化されているかと思います。
プログラムからはWebhookに連動して、もしくは任意のタイミングでGitHub APIを叩いて何かしらの操作を行ったり、Web UIを用意してユーザとコミュニケーションしたりします。
GitHub Apps
GitHub Appsは個人もしくは組織のアカウントにインストールして使います。インストールというのはいわゆるソフトウェアのインストールではなくて、裏でWebhookのアドレスが設定されたり、GitHub APIで操作することを許可するというような設定がされるだけです。開発者が作ったGitHub Appsとの連携の設定がされるというイメージです。どのようなアプリがあるかはマーケットプレイスを見るとわかるかと思います。
作ったGitHub Appsはマーケットプレイスに公開する必要はありません。インターネットには公開されているのでインストールページのリンクを知っていればインストールできます。非公開設定にすると個人もしくは組織が作成したGitHub Appsはその個人もしくは組織でしかインストールできないようになります。ただし非公開設定のGitHub Appsは複数の個人や組織では使えないようです。
GitHub Actions
内部的にはGitHub Appsの仕組みを使っているようです。こちらもマーケットプレイスでどのようなものがあるかわかります。
GitHub Appsではアプリが動くインフラから用意する必要がありました。一方でGitHub ActionsはGitHubが用意しているマシンもしくはコンテナで動くので、開発者が用意するのはプログラムだけです*1。GitHub APIを叩くためのトークンの発行まで済ませてくれますし、CI/CDの機能もあり、UIもGitHubに統合されているので一番連携がしやすいです。
OAuth Apps
Twitterログイン、GitHubでログインなどソーシャルログインで使われる仕組みで作るアプリです。ユーザのログインを通してアクセストークンを発行し、そのトークンでGitHub APIを叩きます。例えばCircleCIやGitHub CLIはOAuth Appsです。
Personal access tokens
個人アカウントのアクセストークンを発行して、そのトークンでGitHub APIを叩いて作るアプリです。企業ではBotアカウントを作ってそのアカウントのアクセストークン(Personal access tokens)を発行してGitHub APIを叩くツールを作ったりするかと思います。他の方法で発行するトークンには有効期限がありますが、Personal access tokensには期限がありません。
カヤックさんではBotアカウント(Personal access tokens)を使う方法からGitHub Appsを使う方法へ変えたようです。
どの連携方法で作るか
GitHub Actions と その他
まずはGitHub Actionsを検討すると良いかと思います。GitHub Actionsは主に一時的な処理に向いています。コチラにはGitHub AppsとGitHub Actionsの違いが簡単に述べられています。
GitHub Apps と OAuth Apps と Personal access tokens
永続的に動作するアプリを作りたいなどGitHub Actionsではできないことする場合どれを使えばよいでしょうか。ドキュメントには一応次のような図が載っています。
この図は個人的にいまいちしっくり来ませんでした。Differences between GitHub Apps and OAuth Appsに違いが述べられているので、これを見ながらどれを使うか選ぶと良いかと思います。例えばGitHubログインとして使うだけならばOAuth Appsを使うと良いようです。またGitHub Appsでは組織に属するメンバーやリポジトリの数によってAPIを叩く時間あたり回数制限が増えたりします。
主体と利用するトークンによる整理
次のような関係を理解しておくとすっきりするかと思います。
ユーザアカウント
例えばgithubユーザアカウントはGitHub CLIOAuth Appsを管理しています。そしてGitHub CLIを使う時に私達にログインさせて作成したアクセストークンを使ってGitHub APIを叩きPRの一覧を取得したりしています。
また、企業においてはユーザアカウントを作ってBotアカウントとして運用し、Personal access tokensを発行してGitHub APIを叩いて何かしら自動化したりします。
GitHub Apps
GitHub Appsはユーザアカウントと同じレベルの存在です。Installation TokensというのはGitHub Appsをインストールした個人や組織に対してGitHub APIを叩いて操作する時に使うアクセストークンです。GitHub ActionsもInstallation Tokensを使っているかと思われます。
GitHub Appsの方にもUser-Based Tokensがあります。これはGitHub AppsでもGitHubログインでユーザにログインさせてユーザのトークンを使えるということです。
おわりに
どういう風に説明するとわかりやすいのかが難しかったです。個人的には主体と利用するトークンによる整理がしっくりきています。
GitHub Appsは非公開で複数の組織で共有できるようになるといいのになと思います。GitHub Appsがインストールされた時にはinstallationイベントが発生するのですが、その情報を見てバリデーションをして自分達の管理する組織でしかインストールできないようにしている人もいるみたいです。
同じ組織だとInstallation Tokenも同じになってしまうのかが気になります。そうだとすれば同じ組織アカウントで複数プロジェクトがある場合、GitHub AppsではAPIの制限に引っかかりやすくなりそうです。
