APIでGitHubを操作する方法を考える

実現したいこと

既存システムでAPI経由でGitHub操作する方法を検討しています。

GitHubで使用できるAPI

GitHubのAPIはGraphQLを用いて操作する最新バージョンのv4とREST APIで操作ができるv3がリリースされています。

各特長としては次の通りで、従来通りのREST APIと柔軟性の高いGraphQLで使い分けします。

• GitHub API v4(GraphQL)
  • personal access token、GitHub App、または OAuth appで認証します。
  • クエリに指定したフィールドでレスポンスができ、一度のクエリで複数のデータを取得できます。
  • 単一のエンドポイントを使用します。
• GitHub API v3(REST API)
  • v4と同様に認証でき、Github CLIコマンドで認証も使用できます。
  • HTTPメソッドを使用した実行が可能です。
  • エンドポイントには階層パスを使用します。

GitHub CLIを用いた単純なコマンド実行であればv3、クエリ結果から処理を実行するようなアプリを開発するのであればv4の仕様が必要になると思われます。

認証方法

1. インストール アクセス トークンを使って、HTTP ベースの Git アクセスをする
   REST APIのAuthorizationヘッダーにトークンを使用して認証します。
2. アプリをインストールすることによるアプリ帰属の認証
   GitHub AppsのラッパーであるOctokit SDKを使用します。
   ユーザーではなくアプリとして認証されます。
3. GitHub CLIで認証
   こちらはユーザのクリデンシャルに依存する方法です。

外部コラボレーターの REST API エンドポイント - GitHub Docs

Oktokit

OktokitはGitHub APIのラッパーです。

Oktokitの公式ライブラリはjs, .NET, Ruby, Terraformがサポートされています。

サードパーティ製ではphpやJava, JavaScriptなどのライブラリが公開されているようです。

REST API のライブラリ - GitHub Enterprise Cloud Docs

GitHub Apps

GitHub Appsはリポジトリとアプリケーションを紐づけ可能な認証の仕組みを提供する拡張ツールです。

GitHub App の使用について - GitHub Docs

OAuth Appsと異なる点は、アプリがリポジトリにアクセスする権限をきめ細かく制御できることです。

仕様

• GitHubの機能を拡張するツールで、Node.jsを用いてイベントに基づいた処理やプロジェクト管理機能を開発することができます。

  • マーケットプレイスでアプリ購入して開発なしでアプリを実行することも可能です。

• 個人アカウントおよびOrganizationにインストール可能です。

  • Organizationの場合オーナーのみがGitHub Appsの設定を管理できます。
    • 開発者にはアクセス権限を付与できます。
    • Organizationsのロールについて

• アプリにアクセス許可を持たせることで、承認するユーザーの権限に基づいた処理を実行できます。

  GitHub アプリのアクセス許可を選択する - GitHub Docs

  • トークンまたはOAuthを使用した認証が必要です。
    • 認証の仕組みとして現時点ではGitHub AppsとOAuth Appsの選択肢があります。
      • GitHub AppssとOAuth Appsの違い
      • GitHub Appsはトークンの有効期限やアクセス許可をきめ細かく設定可能なため、こちらが推奨されます。

言語

GitHub Appsとしての認証はJson Web Token(JWT)を使用しますが、任意のプログラミング言語を使用することができます。

Probotとは

• ProbotとはGithub Appsを構築するためのフレームワークです。
• Webhookを用いてイベント駆動の処理ができます。
• クリデンシャル情報が自動で設定されるためインストールが容易です。

まとめ

今回はGitHubをAPIで操作する方法を考えました。
この記事を読んでGitHubのAPI開発に興味を持っていただければ幸いです。