エピソード紹介
- Ep.1 – クリーンアーキテクチャとは
- Ep.2 – 認証方式の実践的な紹介 ← 今回はこちら
- Ep.3 – ER設計と監査ログ
- Ep.4 – RepoScanner の実装とテスト
- Ep.5 – Copilot プロンプトを効率化
こんな方へ特におすすめ
- 外部 API と連携するアプリケーションで安全な認証・権限設計を行いたい方
- GitHubを使っているが、「トークン」や「認証」の仕組みがよく分からない方
- PAT （Personal Access Token）を使っているが、セキュリティに不安がある方
概要
こんにちは。サイオステクノロジーのはらちゃんです！
「GitHubを使った開発をよくするけど、認証方式って結局どうなっているの…」
と分からなくなったことありませんか？
—
本シリーズでは、Copilotを活用しつつ、クリーンアーキテクチャに沿って小規模なプロダクト「RepoScanner」を設計・実装した経緯をまとめます。
このエピソードでは、GitHub など外部 API と連携する際に実務でよく使われる認証方式（PAT、OAuth2、JWT）の比較と、GitHub APIとGitHub Actionsで使われる認証の違いを考えていきます。
外部と連携する認証方式
方式の比較
| 認証の主体 | 有効期限 | 管理の単位 | |
|---|---|---|---|
| PAT (Personal Access Token) | ユーザー個人 | 任意 (設定可能) | アカウントごと |
| OAuth2 (OAuth App) | ユーザーの代理 | 基本的に無期限 | アプリ全体 |
| JWT + Installation Token (GitHub App) | アプリケーション自体 (Bot) | 1時間以内 | リポジトリ単位 |
それぞれの仕組み
PAT
一言で言うと自分の分身として、他のツールやサービスにあなたの代わりに操作を許可する仕組みです。
- イメージ
自分の「分身」 - メリット
簡易で導入が早い。
- デメリット
「個人のアカウント」に紐づくため、本人が退職すると動かなくなる。
権限が広くなりがちなため、長期的な運用・委譲には向かない。
OAuth2
ユーザーが外部サービスへのログインや連携を許可すると、OAuth2 はアクセストークンを生成します。このアクセストークンは、ユーザーの代わりに外部サービスで操作を実行するための許可証のようなものです。
- イメージ
標準プロトコル - メリット
ユーザー代理での操作やサービス間連携に適する。 - デメリット
「リポジトリ全部の読み取り」など、付与できる権限のスコープが大雑把。
最小権限の原則を適用しにくいため、セキュリティ要件が厳しい組織では敬遠される。
JWT + Installation Token (GitHub App)
JWT の署名と検証、そして短期トークンの発行という 2 段階の認証フローが、PAT や OAuth2 のシンプルな鍵と比較して、より強固なセキュリティであることを示しています。
- イメージ
最もセキュア - メリット
リポジトリ単位で細かく権限（Issueの読み取りだけ、など）を絞れる。
トークンの期限が1時間以内と短く、万が一漏洩しても被害が最小限。 - デメリット
JWTの生成や署名検証、短期トークンの都度発行など、実装と運用設計の手間が大きい。
共通の注意点: シークレット管理の鉄則
個人開発の場合は問題ない場合もありますが、常に意識しておくと習慣になるためおすすめです。
- ソースコードに直書きしない
- 必要な権限だけを持たせたトークンを発行する
- 長期トークンはローテーション（再発行）を設計し、失効を検知できる仕組みを入れる
GitHub APIとGitHub Actions
どちらも最終的には「トークン」を使いますが、「誰として動作するか」「どこで発行されるか」に大きな違いがあります。
GitHub API
スクリプトが個人のアカウント権限を模した合鍵（トークン）を使って、GitHubからデータを自動的に集約します。
- イメージ
外から自由に指示を出してデータを収集 - メリット
簡易で導入が早い。 - デメリット
大量のリポジトリを扱う場合、APIのレート制限に引っかかりやすい。
漏洩時のリスクが集中する。
GitHub Actions
PATのようにずっと使える「マスターキー」を持たせるのではなく、「その時、そのジョブだけで使える使い捨ての鍵」にすることで、万が一の漏洩リスクを最小限に抑えています。
- イメージ
リポジトリ内に住み込み、出来事に反応して自動で労働 - メリット
トークンを管理する手間がない。
有効期限が最大24時間と短く、自動消滅する。
イベントに合わせてリアルタイム処理。 - デメリット
スコープがワークフローが動いているリポジトリの中のみ。
行った操作をトリガーにして、別のワークフローを起動できない。
各リポジトリで独立して動くため、集める仕組みが必要。
本シリーズの認証方針
今回「RepoScanner」では、最終的にGitHub Actions による認証と実行をメインに据える決断をしました。
その理由は、運用の手軽さとセキュリティのバランスにあります。
データ取得自動化の恩恵
私がこの構成で最も大きなメリットだと感じたのは、「Actionsが勝手にデータを運んできてくれる」という点です。
- プッシュや定時実行（Cron）をトリガーに実行
コードが更新された瞬間や毎日決まった時間に、ActionsがリポジトリのスナップショットやPR詳細をスキャンし、DBへ自動保存する。 - ユーザーの手間が軽減
アプリ実行時にはデータが揃っているので、取得を走らせて待つ時間がない。
実行環境の分離
クリーンアーキテクチャの観点で見ると、GitHub Actions は非常に扱いやすいです。
- 実行基盤の最適化
GitHub Actionsが提供する一時的な環境変数GITHUB_TOKENを利用することで、アプリ本体は「合鍵（トークン）を使ってAPIを叩く」というシンプルな責務になる。 - 環境を移し替えても最小限の変更で再利用
「誰が実行するか」をActionsに委ねることで、ビジネスロジックはアクセストークンに依存しない。
セキュリティと運用コスト
前述の比較表の通り、PATは管理が漏洩リスクを伴い、JWTは実装コストが高いです。
GitHub Actions を使えば、ワークフロー実行中だけ有効なトークンが自動発行されます。
- 管理不要
自分でトークンの有効期限を気にしなくてよい。 - 安全
万が一ログから漏洩しても、数時間後にはその鍵は無効化している。
結論
「RepoScanner」が目指す形として、リポジトリのデータを自動で集約し、DBに溜め、それをアプリで閲覧することです。
このサイクルを最も低コストかつセキュアに実現できるのが、GitHub Actions という方法でした。
—
リポジトリごとの権限管理の手間は「方式そのもの」だけで決まるのではなく、どの手法を採り、どのレベルで一括管理するかに依存します。
- ローカルや外部サーバーから叩く場合
- 個人でのちょっとした検証・ツール → PAT（Personal Access Token）
- チームでの本格的な運用・自動化 → GitHub App（JWTベース）
- GitHub Actions 内で完結する場合
- GITHUB_TOKEN を使用
- Actionsの中で動かしたいけど、他のリポジトリも触りたい場合
- 組織用のGitHub Appを作成
まとめ
今回は、GitHubを使った開発での認証方式についてご紹介しました。
認証方式の選択は、システムのセキュリティと運用コストに直結します。要件に合わせた適切な認証・実行基盤を選択していきましょう。
- PATは、個人の分身である
- OAuth2は、ユーザー代理での操作やサービス間連携に適する
- JWTは、最小権限の原則に即している
これらの認証方式は、クリーンアーキテクチャにおいては「Frameworks & Drivers層」の関心事です。
エピソード4で、Domain層やUse Case層が特定の認証方式に依存しないよう抽象化して実装を行うのでお楽しみに！
参考
