--- title: "google-github-actions/authとは｜Workload Identity連携の設定と鍵JSONからの移行判断" url: "https://www.issoh.co.jp/tech/details/16953/" published: 2026-08-25 updated: 2026-09-27 categories: ["GitHub"] publisher: "株式会社一創" --- # google-github-actions/authとは｜Workload Identity連携の設定と鍵JSONからの移行判断 Google CloudへデプロイするGitHub Actionsを組むとき、最初に詰まるのは認証です。サービスアカウントの鍵JSONをシークレットへ貼れば動きますが、その鍵は失効日を持たず、漏れた瞬間から誰でも同じ権限で叩けます。google-github-actions/authは、この鍵を配らずにGitHubのOIDCトークンをGoogle Cloudの短命な資格情報へ交換するアクションです。この記事では2026年8月25日時点の最新である v3.0.0（2025年8月28日公開）を前提に、プールとプロバイダの作成、属性条件の書き方、直接連携とサービスアカウント経由の分岐、鍵JSONからの移行順までを整理します。ワークフローの書き方そのものは[GitHub Actionsとは？できること・使い方とCI/CD自動化の解説記事](https://www.issoh.co.jp/column/details/3005/)、パイプライン全体の設計は[CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準を解説](https://www.issoh.co.jp/column/details/13002/)を前提にしています。 ## まとめ：authの設定前に決める3つの分岐 結論から書きます。新規に組むなら、プールへ直接IAMを与える直接連携を既定にしてください。中間のサービスアカウントを置かない分だけ権限の経路が短くなる。ただし直接連携のトークンは寿命が最大10分で、OAuth 2.0アクセストークンやIDトークンの生成もできません。この2つが要る構成だけ、サービスアカウント経由へ倒します。 2つ目の分岐は属性条件です。プロバイダには必ず属性条件を付け、しかもリポジトリ名や組織名ではなく数値のIDで書いてください。名前で書くと、リポジトリや組織を消したあとに同名を取得した第三者が同じ入口を通れます。 3つ目は版です。v3.0.0はNode 24実行になり、retries・backoff・backoff\_limitの3入力が削除されました。ランナーが古いまま上げると起動しません。鍵JSONからの移行は、並走期間を作ってから鍵を消し、最後に組織ポリシーで鍵の新規作成を塞ぐ順に進めます。 ## google-github-actions/authが担う処理とトークンの流れ このアクションは認証だけを担当し、デプロイもコマンド実行もしません。処理を分解しておくと、失敗したときにGitHub側とGoogle Cloud側のどちらを見ればよいか切り分けられます。 ### OIDCトークン取得から資格情報ファイル出力までを分ける3段階 処理は3段です。第1段で、実行環境からGitHubのOIDCプロバイダへ署名付きトークンを要求します。このトークンにはリポジトリ名・組織名・ブランチといった主張（クレーム）が載っている。第2段で、そのトークンをGoogle CloudのSecurity Token Serviceへ送り、プロバイダの属性条件を通過したら連携済みの資格情報へ交換されます。第3段で、交換した資格情報をファイルへ書き出します。 トークンの構造そのものと、なぜIDトークンが第三者に検証できるのかは[OIDC（OpenID Connect）とは？仕組み・OAuthとの違いをわかりやすく解説](https://www.issoh.co.jp/tech/details/6532/)で扱っています。ここで押さえておきたいのは寿命です。公式READMEは、GitHubのOIDCトークンが5分で失効し、派生した資格情報も同じく5分で失効すると明記しています。長時間走るジョブの終盤で認証エラーが出たら、権限ではなく寿命を疑ってください。 ### permissionsにid-tokenの書き込み権限がないと起動しない 第1段のトークン要求は、ジョブに権限が与えられていないと通りません。ワークフロー側で次のように宣言します。 ``` jobs: deploy: permissions: contents: 'read' id-token: 'write' ``` この権限がないままauthを呼ぶと、Google Cloud側の設定が正しくてもトークン要求の段で落ちます。permissionsブロックを書くと既定の権限セットが置き換わるため、チェックアウトに要る contents の読み取りも並べて書いてください。GITHUB\_TOKENの既定権限と最小権限の組み方は[GitHub Actionsのpermissions｜GITHUB\_TOKENの既定権限と最小権限の設計](https://www.issoh.co.jp/tech/details/16937/)に整理しています。 ### 資格情報ファイルの置き場所とcheckoutを先に置く配線順 create\_credentials\_fileは既定でtrueです。生成されたファイルは GITHUB\_WORKSPACE の下へ置かれ、GOOGLE\_APPLICATION\_CREDENTIALS・CLOUDSDK\_AUTH\_CREDENTIAL\_FILE\_OVERRIDE・GOOGLE\_GHA\_CREDS\_PATH の3つの環境変数から参照されます。ジョブ終了時にはpostアクションが消します。 ここで配線順の制約が出ます。GITHUB\_WORKSPACE はチェックアウトが作るため、authをactions/checkoutより前に置くと書き出し先が用意されていません。公式READMEも、資格情報ファイルを使うならcheckoutを先に置くよう指示しています。Dockerベースのアクションへ資格情報を渡す構成では、この順序が守られていないと後続だけが無言で認証なしになります。 ## プールとプロバイダを作り属性条件でGitHubからの入口を絞る Google Cloud側の作業は、プールを1つ、その配下にプロバイダを1つ作るだけ。ただし属性条件の書き方で安全性が大きく変わります。 ### プール作成とプロバイダ作成で指定する2つのgcloudコマンド プールは組織単位で1つ作り、プロバイダをリポジトリ群ごとに分けるのが扱いやすい形です。 ``` gcloud iam workload-identity-pools create "github" \ --project="${PROJECT_ID}" \ --location="global" \ --display-name="GitHub Actions Pool" ``` 続いてプロバイダを作ります。発行者URIは固定値です。 ``` gcloud iam workload-identity-pools providers create-oidc "my-repo" \ --project="${PROJECT_ID}" \ --location="global" \ --workload-identity-pool="github" \ --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \ --attribute-condition="assertion.repository_owner == 'my-github-org'" \ --issuer-uri="https://token.actions.githubusercontent.com" ``` ワークフローへ渡す workload\_identity\_provider には、プロバイダの完全な資源名を指定します。先頭の projects に続くのはプロジェクトIDではなくプロジェクト番号です。アクション側はプロジェクト番号からIDを逆引きできないため、gcloudを後段で使うなら project\_id も明示してください。 ### マッピングしていないクレームを属性条件やIAMに書けない理由 属性マッピングと属性条件は役割が違います。マッピングは、トークンのクレームをGoogle Cloud側の属性名へ写す作業。条件は、写した属性に対する通過判定です。公式READMEは、条件式やIAMポリシーで参照する前に、対象のクレームを必ずマッピングしておく必要があると強調しています。 ここを飛ばすと、条件を書いたつもりで常に偽になり、権限の問題に見える失敗が出ます。ブランチや環境名で絞りたいなら、対応する属性をマッピングへ足してから条件に書いてください。 ### 組織名ではなく数値IDを属性条件に使うsquatting対策 ここが多くの日本語ハンズオンと分かれる箇所です。属性条件の定番は repository\_owner を組織名で比較する形ですが、公式のセキュリティ考慮ドキュメントは数値のID項目を使うよう明記しています。理由は単純で、リポジトリや組織を削除すると同じ名前を第三者が取得でき、そのとき条件は素通りするからです。 ``` assertion.repository_owner_id == '1342004' && assertion.repository_id == '260064828' ``` 数値IDはGitHubのAPIで取得できます。名前は変わりうるが番号は再利用されない、という性質の差がそのまま安全性の差になる。IAMバインディングで主体を書くときも同じで、リポジトリを名前で書いた版と数値IDで書いた版では事故の起き方が変わります。ワイルドカードは、意図を説明できないなら書かないでください。 ## 直接連携とサービスアカウント経由を実務の要件と制約で分ける判断軸 設定方法は3通りですが、実務で選ぶのは前の2つです。3つ目の鍵JSONは、後述の適用外に当たる場合の逃げ道として残ります。 ### プールへ直接IAMを与える直接連携の利点と運用上の2つの制約 直接連携では、プールの主体そのものへGoogle Cloudリソースの権限を与えます。中間のサービスアカウントが要らないため、権限の経路は最短になります。 ``` gcloud secrets add-iam-policy-binding "my-secret" \ --project="${PROJECT_ID}" \ --role="roles/secretmanager.secretAccessor" \ --member="principalSet://iam.googleapis.com/${POOL_ID}/attribute.repository/${REPO}" ``` 制約は2つあります。第1に、すべてのGoogle Cloudサービスがこの形式の主体を受け付けるわけではなく、対象サービスの資料で対応を確認する必要がある。第2に、得られるトークンの寿命は最大10分です。ビルドから配布まで一続きで10分を超える処理を単一のトークンで通す構成には向きません。 ### トークンを取り出す構成ではサービスアカウント経由へ切り替える token\_format にアクセストークンやIDトークンを指定して値を取り出す構成は、直接連携では成立しません。公式READMEは、これらを生成するにはサービスアカウントのメールアドレスを渡し、プールがそのサービスアカウントに対して workloadIdentityUser のロールを持つ必要があると書いています。バインドの対象がリソースではなくサービスアカウントになる点が直接連携との差です。 ``` gcloud iam service-accounts add-iam-policy-binding \ "my-sa@${PROJECT_ID}.iam.gserviceaccount.com" \ --project="${PROJECT_ID}" \ --role="roles/iam.workloadIdentityUser" \ --member="principalSet://iam.googleapis.com/${POOL_ID}/attribute.repository/${REPO}" ``` アクセストークンの寿命は既定・上限とも1時間で、組織ポリシーで延長を許可した場合に限り12時間まで伸ばせます。GKEのPodへ同じ考え方を適用する場合の実行主体と紐づけは[Workload Identityとは？GKEでキーレス認証を実現する仕組みと設定を解説](https://www.issoh.co.jp/tech/details/5256/)が扱っており、こちらはKubernetes側のサービスアカウントが主語になります。 ### 直接連携とサービスアカウント経由の適用範囲を1枚の表で見比べる | 観点 | 直接連携 | サービスアカウント経由 | | ------------- | ------ | ----------- | | 中間資源 | なし | サービスアカウント1つ | | 権限の付与先 | 対象リソース | サービスアカウント | | トークン寿命 | 最大10分 | 既定1時間 | | token\_format | 使えない | 使える | | 対応サービス | 限定あり | 制限は実質なし | 選び方は単純です。Secret ManagerやCloud Storageへ短時間触るだけなら直接連携、トークンを別のツールへ手渡す必要があるならサービスアカウント経由。迷ったら直接連携から始め、詰まった時点で切り替えるほうが権限の棚卸しは楽になります。 ## setup-gcloudやコンテナ配布へ資格情報を安全に渡す配線手順 authは資格情報を置くところまでで止まり、デプロイは後続のステップが担います。届いているかを確かめる観点を持っておきます。 ### setup-gcloudと組み合わせる最小構成のワークフロー gcloudコマンドを使うなら setup-gcloud を後ろに置きます。2026年8月25日時点の最新は v3.0.1（2025年8月28日公開）で、authと同じくNode 24実行です。 ``` steps: - uses: 'actions/checkout@v5' - uses: 'google-github-actions/auth@v3' with: project_id: 'my-project' workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/github/providers/my-repo' - uses: 'google-github-actions/setup-gcloud@v3' - run: 'gcloud storage ls' ``` ここで1つ落とし穴があります。gsutil は、このアクションが書き出した資格情報を読みません。公式READMEが明示的に注意しており、代わりに gcloud storage を使うよう案内している。既存スクリプトを持ち込んだとき、この1点だけ認証が通らない形で表面化します。 ### コンテナのpushとデプロイの実行時に要る3つのIAMロール コンテナを配る構成では、認証のあとに Docker のクレデンシャルヘルパーを設定します。gcloud auth configure-docker にレジストリのホスト名を渡す形。リポジトリの形式や保管料金は[Artifact Registryとは？Google Cloudの成果物リポジトリの仕組み・料金とContainer Registry移行を実装者目線で解説](https://www.issoh.co.jp/tech/details/15559/)にまとめてあります。 権限は、push側に artifactregistry.writer、デプロイ側に run.developer と、実行サービスアカウントを差し替える serviceAccountUser の3つ。デプロイ先の課金や起動条件は[Cloud Runとは？GCPのサーバーレスコンテナの仕組み・料金とGKE/Cloud Functionsとの違いを実装者目線で解説](https://www.issoh.co.jp/tech/details/15435/)で扱っています。権限を1つのサービスアカウントへ束ねると初回は速いのですが、ビルド用とデプロイ用を分けておくと、あとで片方だけ止める判断ができます。 ### プロジェクトIDが後続ステップへ伝わらないときに確認する箇所 export\_environment\_variables は既定でtrueで、CLOUDSDK\_PROJECT・GOOGLE\_CLOUD\_PROJECT を含む5つのプロジェクト系変数が後続へ渡ります。falseにすると、後続のライブラリは自力でプロジェクトを解決できません。プロジェクトが見つからないというエラーが出たら、権限ではなくこの入力とproject\_idの指定を先に確認してください。承認ゲートや環境別のシークレットを挟む構成なら、[GitHub ActionsのEnvironments｜承認ゲートと環境別シークレットの設計](https://www.issoh.co.jp/tech/details/16935/)と合わせて、どの環境のプロバイダを使うかまで含めて設計します。 ## 鍵JSONからOIDCへ移行する順序と、鍵を残す例外条件の判断軸 既に鍵JSONで動いている環境をどう畳むか。ここは順序を誤ると全部の自動化が同時に止まります。 ### 並走期間を挟んで鍵JSONを安全に消すまでの具体的な4つの移行手順 手順は4つです。第1に、プールとプロバイダを作り、既存のサービスアカウントへ workloadIdentityUser を付ける。第2に、ワークフローの認証ステップだけを credentials\_json から workload\_identity\_provider へ差し替え、他は触らずに1回通します。第3に、全ワークフローが通ったことを確認してから、シークレットに置いた鍵とGoogle Cloud側の鍵を削除する。第4に、組織ポリシーでサービスアカウント鍵の新規作成を禁止します。 第4を先にやると、既存の自動化が一斉に止まります。逆に第3を飛ばすと、鍵が残ったまま連携も動く状態が固定され、監査で必ず指摘される。Google CloudのIAMベストプラクティスが鍵を避けるよう勧める理由も、鍵で認証された操作は監査ログから実行者を特定できない点にあります。Terraform側から同じ設計を組む場合の認証とbackendの分担は[TerraformでGCPを構築する手順｜google 7系の認証とGCSバックエンド設計](https://www.issoh.co.jp/tech/details/16544/)に整理しました。 ### Firebase Admin SDKとgsutilという2つの適用外 連携で置き換えられないものが2つあります。1つはFirebase Admin SDKで、公式READMEが連携方式に対応していないと明示しており、この経路だけは鍵JSONを使う判断になる。もう1つは前述のgsutilで、これはコマンドを gcloud storage へ寄せれば解決します。 例外を残す場合も、鍵の置き先は1リポジトリの1シークレットに限定し、権限は当該サービスに閉じたロールだけへ絞ってください。例外が2つ以上に増えたら、それは移行が終わっていない状態です。 ### AWS側のOIDC連携も設計は同じでサービスごとの用語だけが違う マルチクラウドの現場では、AWS側にも同種の連携を敷いているはずです。設計の骨格は同じで、GitHubの発行者を信頼させ、条件でリポジトリを絞り、短命の資格情報を取る形になります。違うのは用語で、AWSではIAM OIDCプロバイダと信頼ポリシーが対応物になる。構築手順は[GitHub ActionsとTerraformでAWSのCI/CDを構築する手順（OIDC・S3ネイティブロック対応）](https://www.issoh.co.jp/tech/details/2715/)にあります。両方を1つのワークフローへ同居させる場合、認証ステップが2つ並び、別々の資格情報ファイルを書く点だけ注意してください。[AWS・Google Cloud・Azureのインフラ構築](https://www.issoh.co.jp/service/system/aws/)では、こうしたCI/CDの認証設計から本番移行までを受託しています。 ## v3への更新で壊れる箇所と、導入を見送る環境条件と実務の判断軸 ### v3.0.0が持ち込んだNode 24化と廃止された3入力の変更点 v3.0.0は2025年8月28日の公開で、破壊的変更は2点です。1点目は実行環境がNode 24へ上がったこと。2点目は retries・backoff・backoff\_limit の3入力が削除されたことです。v2系のワークフローでこれらを書いていた場合、v3へ上げると入力そのものが消えているため、リトライ挙動を前提にした運用は成り立ちません。断続的な失敗を吸収したいなら、ジョブ側の再実行やステップの条件分岐で組み直してください。 Node 24化はセルフホストランナーに効きます。ランナーのバージョンが古いと、アクションのエントリポイントを起動できません。ラベル指定と実行基盤の更新は[GitHub Actionsのruns-on｜ラベル指定の記法と-latest更新・arm64への備え](https://www.issoh.co.jp/tech/details/16929/)で扱っています。 ### 可動タグではなくコミットSHAで依存アクションを固定する基準 uses に書く参照をメジャー版の可動タグにしておくと、上流が同じタグを付け替えた瞬間に実行内容が変わります。認証を担うアクションは、その差が資格情報の扱いへ直結します。外部の権限へ触るアクションはコミットSHAで固定し、更新は明示的な作業として扱うのが安全側の運用です。固定の手順と自動更新の組み方は[SHA Pinningとは？GitHub ActionsをコミットSHAで固定する方法【Enforce設定・pinact】](https://www.issoh.co.jp/tech/details/10238/)にまとめています。 ### 採用条件と、鍵JSONのままで運用を続けてよい場面の判断基準 採用条件は3つのうち2つで判断してください。Google Cloudのリソースへ書き込むワークフローがある、リポジトリまたはワークフローが2つ以上ある、外部の共同作業者がコミットできる。2つ以上に当てはまるなら連携へ移してください。鍵の棚卸しコストが設定コストを上回ります。 逆に見送ってよい場面もあります。数日で捨てる検証用リポジトリで、触るのが1人、権限が読み取りだけという構成。この規模ではプールとプロバイダの管理対象が増える分だけ手間が勝ちます。もう1つはGitHub Enterprise Serverの古い版で、OIDCトークンの発行に対応していない環境。この場合は連携が成立しないため、鍵を短命に回す運用で凌ぎ、本体の更新計画へ載せてください。 ## よくある質問 ### google-github-actions/authは何をするアクションですか？ GitHub ActionsからGoogle Cloudへ認証するためだけのアクションです。GitHubのOIDCトークンを取得し、Workload Identity連携でGoogle Cloudの短命な資格情報へ交換し、後続ステップが読める資格情報ファイルと環境変数を用意します。デプロイやコマンド実行は担当しないため、gcloudを使うなら setup-gcloud を後ろに置きます。2026年8月25日時点の最新は v3.0.0 です。 ### サービスアカウントは必ず作る必要がありますか？ いいえ。プールの主体へ直接IAMを与える直接連携なら、サービスアカウントを作らずに済みます。ただし2つの制約があり、この形式の主体に対応していないサービスでは使えず、トークンの寿命も最大10分に制限されます。token\_format でアクセストークンやIDトークンを取り出す構成も直接連携では成立しないため、その場合はサービスアカウントを1つ用意してください。 ### 属性条件は組織名で書けばよいですか？ 組織名でも動きますが、公式のセキュリティ考慮ドキュメントは数値IDを勧めています。リポジトリや組織を削除すると同じ名前を第三者が取得でき、名前で書いた条件はその第三者のトークンも通してしまうためです。repository\_owner\_id と repository\_id をGitHubのAPIで取得し、この2つで比較する条件にしてください。条件に書く属性は、先に属性マッピングへ登録しておく必要があります。 ### 認証は通るのに後続のステップだけ失敗するのはなぜですか？ 切り分け先は3つあります。1つ目は資格情報ファイルの置き場所で、actions/checkout より前にauthを置くと作業ディレクトリが未作成のため書き出せません。2つ目は gsutil で、このコマンドは書き出された資格情報を読まないため gcloud storage へ置き換えます。3つ目はプロジェクトIDの伝達で、export\_environment\_variables を false にしていると後続がプロジェクトを解決できません。 ### v2からv3へ上げるときに壊れる箇所はどこですか？ 2か所です。実行環境がNode 24になったため、セルフホストランナーが古い場合はアクションが起動しません。もう1か所は入力で、retries・backoff・backoff\_limit の3つがv3.0.0で削除されています。この3つを書いたワークフローは、リトライの前提が消えた状態になります。上げる前にランナーの版を確認し、リトライはジョブ側の再実行へ組み替えてください。 ## 関連記事 - [Workload Identityとは？GKEでキーレス認証を実現する仕組みと設定を解説](https://www.issoh.co.jp/tech/details/5256/)：GKEのPodを実行主体にした場合の紐づけはこちらです。 - [OIDC（OpenID Connect）とは？仕組み・OAuthとの違いをわかりやすく解説](https://www.issoh.co.jp/tech/details/6532/)：トークンの構造と検証の考え方を先に押さえられます。 - [GitHub ActionsとTerraformでAWSのCI/CDを構築する手順（OIDC・S3ネイティブロック対応）](https://www.issoh.co.jp/tech/details/2715/)：AWS側で同じ設計を敷くときの対応物です。 - [TerraformでGCPを構築する手順｜google 7系の認証とGCSバックエンド設計](https://www.issoh.co.jp/tech/details/16544/)：Terraform側の認証とstate設計の分担を確認できます。 - [CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準を解説](https://www.issoh.co.jp/column/details/13002/)：パイプライン全体から見直したい場合の入口です。 --- 出典: [google-github-actions/authとは｜Workload Identity連携の設定と鍵JSONからの移行判断]()（株式会社一創）