(わからないことが多すぎるので全体公開はまだまだ先だなー)
どういうもの？
GitHub の機能を拡張するツール。
GitHub App を経由することで、以下のようなことができる。
- issue を開く
- PR にコメント
- GitHub で issue が発行されたときに slack で通知
GitHub App は、GitHub Marketplace でオープンに公開されているものを見繕って使うこともできるし、独自に作成することもできる。
GitHub App を作成する
以下、個人の GitHub App を作成する手順
GitHub の Web コンソールへログイン > ユーザーのアバター > Settings > Developer Settings > New GitHub App
→Register new GitHub App ページが開く
Register new GitHub App で以下の項目を入力する
| 項目1 | 項目2 | 説明 |
|---|---|---|
| Register new GitHub App | GitHub App name | GitHub App の名前。GitHub 全体でユニークでなければならない。 |
| 〃 | Description(表示上は名無し) | アプリの説明 |
| 〃 | Homepage URL | GitHub App の Web サイトのURL (ダミーでも何でもいいらしい) |
| Indentifying and authorizing users | Callback URL | GitHub App のインストールをユーザーが承認した際のリダイレクト先 URL (TODO) |
| 〃 | Expire user authorization tokens | チェックを入れるとアクセストークンに有効期限が設定される |
| 〃 | Request user authorization (OAuth) during installation | GitHub App のインストール中にユーザーが GitHub App を認可した際、ユーザーのアクセストークンを生成できる？ |
| 〃 | Enable Device Flow | デバイスフローを使用してユーザーのアクセストークンを生成する場合に。 |
| Post installation | Setup URL | GitHub App へ追加設定した際のリダイレクト先 URL。Redirect on update が無効である場合機能しない (TODO) |
| 〃 | Redirect on update | GitHub App へ追加設定した際に Setup URL へリダイレクトするか |
| Webhook | Active | GitHub |
| 〃 | Webhook URL | GitHub が Web Hook イベントを送信する URL |
| 〃 | Secret | Web Hook のためのシークレット？ |
| Permissions | Repository permissions | リポジトリおよび関連リソースへのアクセス権限 |
| 〃 | Organization permissions | 組織関連リソースへのアクセス権限 |
| 〃 | Account permissions | ユーザー承認フローの一部として各ユーザーごとに付与されるアクセス権限 |
| Subscribe to events | Installation target | GitHub App がインストールされているユーザーや組織のアカウントに関連するアクティビティがあったときにトリガー？ |
| 〃 | Meta | Web Hook が削除されたとき？ |
| 〃 | Security advisory | GitHub によるセキュリティ勧告の発行・更新・撤回？ |
| 〃 | where can this GitHUb App be installed | 以下の二択。 -Only on this account: - Any account: |
GitHub App を使用する
組織またはアカウント単位で GitHub App をインストールできる。
このとき、GitHub App を紐づけるリポジトリも指定する形になる。
参考
https://docs.github.com/ja/apps/using-github-apps/about-using-github-apps
GitHub App 認証とトークン
GitHub App には以下の認証および、発行されるトークンの種類がある。
- GitHub App として認証 : JWT
- GitHub App インストールとして認証: インストールアクセストークン(IAT)
- ユーザーに代わって認証: ユーザーアクセストークン(UAT)
各トークンの種類ごとに、利用できる GitHub API のエンドポイントが異なる。
GitHub App の JWT
GitHub App の JWT は、GitHub App の ID と秘密鍵を使って生成できる。
JWT の生成には、各プログラミング言語で用意されているパッケージを利用できる。
参考
インストールアクセストークン(IAT)
処理の自動化で使うアクセストークンである。
GitHub App は、ユーザー or 組織 の裁量でリポジトリにインストールすることができるが、GitHub App をインストールすると、インストール ID が発行される。
インストール ID 単位のアクセストークンが IAT である。
例えば、GitHub Actions において GitHub 側で自動的に取得される GITHUB_TOKEN は、IAT に該当する。
IAT は、GitHub App の JWT を Bearer トークンとして /app/installations/<インストールID>/access_tokens API を叩くことで取得できる。
このとき、リクエストボディ の repository_ids パラメータで操作可能なリポジトリを限定したり、permissions パラメータで、使用するパーミッションを限定したりできる。これらを指定しない場合は、その GitHub App に紐づけられている全てのリポジトリおよび、GitHub App に付与されているすべてのパーミッションが IAT に付与されることになる。
GitHub Actions で IAT を取得する
を参照。
この action を使うことで、GitHub アプリのインストール アクセス トークンの生成に記述されている、JWT の生成 〜 IAT の取得までを一貫して行ってくれる。
アクセストークンを使った GitHub API の利用
GitHub App のアクセストークンを使って、GitHub API を利用できる。
アクセストークンに付与されるパーミッションごとに利用できるエンドポイントが定められており、ものによっては UAT でしか利用できないものもある。
これらの情報は、Permissions required for GitHub Appsで確認できる。
参考
GitHub App のスラッグ名
GitHub App nameを「小文字化＋特殊文字をハイフンへ変換」した値 とのこと
参考:
https://zenn.dev/tmknom/articles/github-apps-token
GitHub App インストールに伴う暗黙的なユーザー作成
GitHub App は、 <GitHub App のスラッグ名>[bot] というユーザーっぽいものとして扱われるらしい。
※これは、actions/create-github-app-token のサンプルに、
user_id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)
があったことから。
ちなみに、/users/<ユーザー名> の GitHub API 仕様は コレ
ダミーのメールアドレス
以下のダミーメールアドレスが使えるっぽい。
<GitHub App の ID>+<GitHub App のスラッグ名>[bot]@users.noreply.github.com