GitHub Actions の GITHUB_TOKEN とは?

GITHUB_TOKEN は GitHub がすべての workflow run のために作成する一時的な認証情報で、secret を保存せずに step が GitHub API に認証できるようにします。

ほとんどの workflow は GitHub と通信する必要があります。コメントの投稿、release の作成、tag のプッシュなどです。GITHUB_TOKEN はこのアクセスを自動的に提供し、リポジトリにスコープされ、run が終了すると失効します。

概要

run ごとに生成され、secrets.GITHUB_TOKEN および CLI 用の GH_TOKEN として公開される短命の installation token です。リポジトリに紐付けられ、job が完了すると失効します。

permissions:
  contents: read
  pull-requests: write
steps:
  - run: gh pr comment "$NUMBER" --body "Built!"
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

仕組み

GitHub は run の開始時に permissions: キーで定義された権限でトークンを発行します。step はそれを使って API 呼び出しを認証し、run が終了するとトークンは無効になります。

最小権限

デフォルトの権限は広範になり得るため、permissions: を明示的に設定し、各 job が必要とするものだけを付与してください。これにより、step が侵害された場合の影響範囲を限定できます。

なぜ重要か

GITHUB_TOKEN は、リポジトリ内の自動化のために personal access token を作成しローテーションする必要をなくします。自動的でスコープされ、かつ一時的であり、これがセキュアなデフォルトです。

関連概念

GITHUB_TOKEN はリポジトリの secret や permissions: キーと連携して動作します。cloud へのアクセスには OIDC が推奨される代替手段です。

重要なポイント

• GITHUB_TOKEN は自動生成された短命の run 用認証情報です。
• そのスコープは permissions: キーで設定されます。
• run が終了すると失効し、ローテーションは不要です。

関連ガイド