Fine-grained PATとclassic PATの違い|スマホアプリに渡すならどちらか

この記事は「Pocket Actions」の開発者が書いています。Pocket ActionsもGitHubのトークン(PAT)を貼って使うアプリです。だからこそ、どのアプリに渡すにしても(自分のアプリを含めて)、トークンが何をできるのかを知っておいてほしいと思って書きました。内容は確認日時点のGitHub公式ドキュメント(リンク先)にもとづいています。

なぜスマホで気にするべきか

スマホのGitHub関連アプリの中には、「GitHubでサインイン」ではなくPAT(パーソナルアクセストークン)を貼る方式のものがあります。iPhoneのショートカットでGitHubのAPIを呼ぶ場合も同じです。トークンは、毎日持ち歩く端末に入ります。もし漏れれば、そのトークンの範囲内で、あなたとして操作されてしまいます。

なので考えるべきなのは「一般にどちらが優れているか」ではなく、**「やりたいことができる、いちばん小さなトークンはどれか」**です。

2種類のトークン(GitHubの説明)

GitHubのPATのドキュメントでは、次のように説明されています。

Fine-grained PAT(GitHubは、使える場面ではこちらを推奨)

  • 1つのユーザーか1つの組織のリソースだけに限られる
  • さらに、特定のリポジトリだけに絞れる
  • 広いスコープではなく、細かい権限(Actionsの読み取り/書き込み、Contentsの読み取り/書き込みなど)を選ぶ
  • 組織のオーナーが承認制にできる
  • 作れるのは50個まで
  • 注意点:GitHub上のすべての公開リポジトリへの読み取りは常に含まれる

classic PAT(GitHubいわく「安全性が低い」)

  • あなたがアクセスできるすべてのリポジトリにアクセスできる(個人のリポジトリも、所属する組織のリポジトリも)
  • repo や workflow といった広いスコープで指定する
  • 一部、classicでしかできないことがある(後述)

どちらも作ったユーザーにひもづきます。GitHubは、1年間使われていないPATを自動で削除し、有効期限を付けることを強く勧めています。

Fine-grained PATでまだできないこと

GitHubが挙げている、Fine-grained PATの主な制限です。

  • メンバーではない公開リポジトリへの貢献
  • 外部コラボレーターとして参加しているリポジトリ
  • 複数の組織にまたがるアクセス
  • Packages
  • Checks API
  • ユーザー所有のProjects

また、一部のREST APIはclassicでしか使えません。組織によってはclassicを禁止していたり(その場合403エラーになります)、逆にFine-grainedを禁止していたりします。

比較表(アプリに貼る場面)

比較表(アプリに貼る場面)
項目Fine-grained PATclassic PAT
届くリポジトリ選んだものだけ(+公開リポジトリの読み取り)アクセスできる全部
権限の細かさ権限ごとに読み取り/書き込み広いスコープ(repoは非公開リポジトリのフル操作)
複数の組織を1本でできないできる
組織による承認できるできない(許可か禁止のみ)
有効期限作成時に設定。組織が上限を決められる任意(付けることを推奨)
漏れたときの被害絞っていれば小さい大きい
すべてのAPIで使えるかまだ一部使えないほぼ使える

GitHub Actionsを動かすのに必要な権限

RESTのドキュメントとFine-grained PATの権限表によると、次のとおりです。

GitHub Actionsを動かすのに必要な権限
やりたいことFine-grainedclassic
workflow_dispatch のワークフローを実行Actions:書き込みrepo
repository_dispatch を送るContents:書き込みrepo
非公開リポジトリのワークフロー一覧を見るActions:読み取りrepo
ワークフローのファイルを書き換えるWorkflows:書き込みworkflow

つまり「ワークフローを動かすボタン」用のトークンなら、対象のリポジトリだけ、Actions:書き込み、有効期限つきで作れます(Metadataの読み取りは自動で付きます)。ただし、実際のアプリは実行以外のこともします。ワークフローの一覧を見るにはActionsの読み取り(「読み取りと書き込み」に含まれます)、ワークフローのファイルを読んで入力フォームを作るにはContentsの読み取りが必要です。各アプリが何を求めているか確認しましょう。

Pocket Actionsの現状(正直に)

必要以上の権限を求めるアプリには、私のアプリも含めて慎重になってください。

Pocket Actionsで必要なのは、classic PATなら repo だけです。アプリ内ガイドは以前、workflow も選んだ状態でトークン作成画面を開いていました。しかしGitHubのドキュメント上、ワークフローの実行に必要なのは repo で、workflow はワークフローのファイルを書き換えるためのスコープです。Pocket Actionsはファイルを書き換えないので不要でした。そのため、ガイドを repo だけを選ぶ形に改めています。すでに workflow 付きのトークンを使っている場合は、repo だけのトークンに作り直せます。

Fine-grained PATで使う場合は、使うリポジトリに対して Actions:読み取りと書き込み(ワークフローの一覧と実行)と Contents:読み取り(ワークフローのファイルを読んで入力フォームを作る)が必要です。アプリのコードはFine-grained PATを受け付け、トークンの種類やスコープで弾く処理もないので、コード上は対応しています。ただし実機ではまだ確かめておらず、未確認です。組織のリポジトリでは、組織側でFine-grained PATが許可されている必要があることもあります。トークンは端末内の安全な領域にだけ保存され、開発者のサーバーには送られません(そもそもサーバーがありません)。

実践のルール

  1. Fine-grainedを優先し、アプリやショートカットが使うリポジトリだけに絞る
  2. 最小の権限にする(実行だけならActions:書き込み。Contentsの読み取りなどは、ツールが必要とする分だけ)
  3. 有効期限を付け、更新日をカレンダーに入れておく
  4. アプリや端末ごとに1本、名前を分かりやすく付ける。漏れたときにその1本だけ無効にできる
  5. classicは、ドキュメントにある制限に当たったときだけ使う(複数の組織など)
  6. 端末をなくしたらすぐ無効化:Settings → Developer settings → Personal access tokens
  7. トークンをメモ・チャット・ドキュメントに貼らない。保存はアプリの中だけにする

トークンの作り方と動作確認

画面の名前はGitHubの手順に沿っています。名前が変わっていたら、近いものを探してください。

Fine-grained PAT(ワークフローを動かす用)

  1. Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
  2. Token nameは、取り消すときに見分けられる名前にします(例:iphone-actions)
  3. Expirationは、スマホ用なら30〜90日くらいが目安です。組織が上限を決めていることもあります
  4. Resource ownerには、リポジトリの持ち主(自分か組織)を選びます。1つのトークンで扱える持ち主は1つです
  5. Repository accessは「Only select repositories」にして、使うリポジトリだけを選びます
  6. 権限は、Actionsを「Read and write」、ワークフローのファイルを読むアプリならContentsを「Read-only」にします。Metadataは自動で付きます
  7. 生成されたトークンはその場で一度しか表示されないので、そのままアプリに貼ります

組織が承認を求める設定にしている場合、承認されるまでトークンは使えません。

Classic PAT(repoだけ)

Tokens (classic) → Generate new token (classic) で、スコープはrepoだけにチェックを入れます。workflowは、.github/workflowsのファイルを作ったり変えたりするときだけ必要です(スコープの説明)。有効期限は「No expiration」も選べますが、GitHubは期限の設定を勧めています。

貼る前にパソコンで確かめる

トークンは環境変数に入れ、チャットや文書には貼らないでください。

read -s GITHUB_TOKEN && export GITHUB_TOKEN
# リポジトリが見えるか(200が返ればOK)
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO
# ワークフローを実行できるか(実際に動くので、無害なワークフローで試す)
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/hello.yml/dispatches \
  -d '{"ref":"main"}'

2つ目は2xxが返れば成功です。-iを付けると、Classic PATではX-OAuth-Scopesヘッダーでスコープが確認できます。Fine-grained PATで失敗したときは、X-Accepted-GitHub-Permissionsヘッダーに必要な権限が出ることがあります(トラブルシューティング)。

エラーの読み方

エラーの読み方
応答よくある原因対処
401 Bad credentials打ち間違い、期限切れ、取り消し済み作り直す
404 Not Foundトークンの対象にリポジトリが入っていない、または持ち主の選択違い。非公開リポジトリには404が返ります対象リポジトリを編集する
403 Resource not accessible権限不足(Actionsの書き込みなど)権限を追加する
403(組織のポリシー)組織がその種類を禁止している、または承認待ち許可された種類を使う

エラーメッセージの文言は公式に記載がないため、表の文言は目安です(未確認)。

入れ替えと紛失時

入れ替えるときは、同じ設定の新しいトークンを作り、アプリに貼って動作を確かめてから、古いほうを削除します。スマホをなくしたら、まずトークンを取り消してください。数秒で済み、誰が端末を持っていても使えなくなります。そのあと、Actionsタブに心当たりのない実行がないかを確認します。

タイプ別のおすすめ

  • アプリ1つ、個人のリポジトリ1〜2個:Fine-grained。対象のリポジトリだけ、Actions:書き込み(+アプリが必要とする読み取り)、30〜90日の有効期限。
  • 複数の組織のリポジトリ:Fine-grainedは組織をまたげないので、組織ごとに1本作るか、慎重にclassicを使う。
  • 組織がどちらかを禁止している:許可されている方を使う。
  • GitHub公式アプリ:PATは不要(アカウントでサインイン)。

使い方の一例(開発者の場合)

開発者自身は、気になった銘柄をAIに評価させる自動化を、必要なときにスマホから実行しています。どのアプリやショートカットを使う場合でも、その裏にあるトークンはパスワードと同じように扱う価値があります。

Pocket Actionsを試す

スマホからworkflow_dispatchのワークフローを動かしたいなら、1日5回まで無料で試せます。制限:実行はmainブランチ固定、アプリ内でログは見られない、iOSのみ。

App StoreでPocket Actionsを見る

よくある質問

Fine-grainedとclassic、どちらを使うべきですか? GitHubは、使える場面ではFine-grainedを推奨しています。複数の組織を1本で扱いたいなど、ドキュメントにある制限に当たったときだけclassicを使いましょう。

workflow_dispatchを動かすのに必要なFine-grainedの権限は? 対象リポジトリの「Actions:書き込み」です。

classicのrepoスコープは全部のリポジトリに届きますか? 届きます。classic PATは、あなたがアクセスできるすべてのリポジトリ(組織のものを含む)にアクセスできます。

Fine-grained PATに有効期限はありますか? 作成時に設定します。組織が上限を決めることもできます。1年間使われていないPATはGitHubが自動で削除します。

Pocket ActionsはFine-grained PATに対応していますか? アプリのコードは対応していますが、実機ではまだ確かめていません。試す場合は、対象リポジトリに「Actions:読み取りと書き込み」と「Contents:読み取り」を付けてください。classic PATなら repo だけで足ります。

関連記事

最終確認日:2026-11-01(GitHub Docs:PATの管理、REST API、Fine-grained PATの権限表)。