GitHub認証トークン完全ガイド：PAT取得からGITHUB_TOKEN・GH_TOKENの使い分けまで

はじめに

GitHubで自動化やCLIツールを使おうとしたとき、トークンまわりで詰まることがあります。

PATを作ったのにghコマンドで使えない
GITHUB_TOKENとGH_TOKENどちらを設定すればいいかわからない
GitHub Actionsで認証エラーが出る

この記事ではPATの取得からGITHUB_TOKEN・GH_TOKENの違いと設定方法、それぞれの認証確認方法までをまとめて解説します。

PATとは

PAT（Personal Access Token）はGitHubのAPIやCLIツールを使うための認証トークンです。パスワードの代わりとして使用します。

PATには2種類あります。

種類	特徴
Classic PAT	昔からある形式。スコープで権限を設定
Fine-grained PAT	新しい形式。リポジトリ単位で細かく権限を設定できる

新規で作成する場合はFine-grained PATが推奨ですが、一部のツールやサービスでまだClassicしか対応していないケースもあります。

PATを作成する

1. GitHubの設定画面を開く

右上のアバター → Settings → 左メニュー下部の Developer settings → Personal access tokens

Classic PATは → Tokens (classic)
Fine-grained PATは → Fine-grained tokens

2. Generate new tokenをクリック

Classic PATの設定項目

Note：トークンの用途がわかる名前（例：local-dev、ci-deploy）
Expiration：有効期限（無期限も設定可能だが90日推奨）
Scopes：必要な権限にチェックを入れる

よく使うスコープ：

スコープ	用途
`repo`	リポジトリの読み書き
`workflow`	GitHub Actionsの操作
`read:org`	Organization情報の読み取り
`write:packages`	GitHub Packagesへの公開

3. Generate tokenをクリック

トークンはこの画面を閉じると二度と表示されません。必ずコピーしてパスワードマネージャー等に保存してください。

GITHUB_TOKENとは

GITHUB_TOKENはGitHub Actionsが自動で発行する一時トークンです。自分で作成する必要はありません。

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

特徴

ワークフローの実行ごとに自動生成・自動失効
そのリポジトリ内でのみ有効
権限はリポジトリの設定で制御できる

できないこと

別リポジトリへのアクセス
Organization全体の操作

GH_TOKENとは

GH_TOKENはGitHub CLI（ghコマンド）が認証に使う環境変数です。

export GH_TOKEN=ghp_xxxxxxxxxxxx
gh auth status  # 認証確認

gh CLIはGH_TOKENとGITHUB_TOKENの両方を認識します。GH_TOKENが優先されますが、GitHub Actions内ではGITHUB_TOKENが自動で存在するため、多くのケースでGH_TOKENに明示的にセットしなくてもghコマンドが動きます。

明示的にGH_TOKENを設定する場面は、権限を上書きしたい場合や別途作成したPATを使いたい場合です。

steps:
  - name: gh コマンドでPRを作成
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      gh pr create --title "自動PR" --body "本文"

GITHUB_TOKENとGH_TOKENの違い

	GITHUB_TOKEN	GH_TOKEN
何者か	Actionsが自動発行するシークレット	gh CLIの認証用環境変数
誰が設定するか	GitHub（自動）	自分で設定
使える場所	GitHub Actionsのみ	ローカル・Actions両方
gh コマンドで使える？	使える（GH_TOKENより優先度低）	使える（優先）
有効期限	ジョブ終了まで	PATの有効期限に依存

ローカル環境でのPAT設定

# ~/.zshrc または ~/.bashrc に追記
export GH_TOKEN=ghp_xxxxxxxxxxxx

設定後はターミナルを再起動するかsource ~/.zshrcを実行します。

認証確認

gh auth status

github.com
  ✓ Logged in to github.com account yourname (keyring)
  - Active account: true
  - Token: ghp_****
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

GitHub ActionsでPATを使う

別リポジトリへのアクセスなどGITHUB_TOKENでは権限が足りない場合はPATをSecretsに登録して使います。

SecretsへのPAT登録手順

リポジトリの Settings → Secrets and variables → Actions
New repository secret をクリック
Nameに変数名（例：MY_PAT）、Secretにトークンを貼り付けて保存

steps:
  - uses: actions/checkout@v4
    with:
      repository: yourname/other-repo
      token: ${{ secrets.MY_PAT }}

ユーザー名が必要になるケース

トークンだけでなくGitHubのユーザー名も環境変数で管理する場面があります。

GitHub Container Registry（ghcr.io）へのログイン

echo $GH_TOKEN | docker login ghcr.io -u $GH_USERNAME --password-stdin

docker loginはトークンに加えてユーザー名が必要なため、セットで環境変数に持っておきます。

GitHub Packages（Maven/Gradle/旧npm形式）

//npm.pkg.github.com/:username=${GH_USERNAME}
//npm.pkg.github.com/:_password=${GH_TOKEN}

この場合の変数名はGH_USERNAMEのようにGITHUB_プレフィックスを避けるのがベストプラクティスです（後述）。

環境変数名のプレフィックスに注意

GITHUB_で始まる環境変数名はGitHubが予約しています。自分でSecretsやActionsの変数を作る際にGITHUB_プレフィックスを使うと意図しない動作を招く可能性があります。

やりがち	推奨
`GITHUB_USERNAME`	`GH_USERNAME`
`GITHUB_TOKEN_FOR_PACKAGES`	`GH_PACKAGES_TOKEN`
`GITHUB_DEPLOY_KEY`	`DEPLOY_KEY`

GH_TOKENとGITHUB_TOKENは同じトークンでも大丈夫

GH_TOKENには専用のPATを用意する必要はなく、GITHUB_TOKENをそのまま渡しても動きます。

steps:
  - name: gh コマンドでIssueを作成
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      gh issue create --title "タイトル" --body "本文"

別途PATを用意した方がいいケース

別リポジトリへのアクセスが必要（GITHUB_TOKENは自リポジトリのみ有効）
Organization全体の操作が必要
GITHUB_TOKENのデフォルト権限では足りないスコープが必要な場合

これらに該当しない場合はGITHUB_TOKENの使い回しで十分です。

まとめ

PATはGitHub Developer settingsから作成。作成直後しか表示されないので必ず保存する
GITHUB_TOKENはActionsが自動発行する一時トークン。自分で作成不要
GH_TOKENはgh CLIが参照する環境変数。GITHUB_TOKENより優先される
GITHUB_プレフィックスはGitHubの予約済み。自分の変数にはGH_を使う
ghcr.ioやGitHub Packagesではトークンとユーザー名をセットで管理する
同一リポジトリ内ならGH_TOKENにGITHUB_TOKENをそのまま使い回してOK