同じGitHub Actionsの設定なのに、新しく作ったリポジトリだけAWSへの認証が失敗する。その場合は、権限を増やす前に、OIDCトークンのsubとIAMロールの信頼ポリシーが一致しているかを確認しましょう。subは、AWSが「どのリポジトリの、どの実行を信頼するか」を判定するための情報です。
2026年10月10日、DevelopersIOで、この不一致を調べる検証記事が公開されました。本稿ではこれを入口に公式資料を確認し、新旧形式が混在する環境での確認順と、許可範囲を広げない修正方針を整理します。テクノヴァースで実機再現した結果ではなく、公開仕様に基づく解説です。情報基準日は2026年10月12日です。
10月の新機能ではなく、既存の仕様変更を確認する
GitHubは2026年4月23日に、不変の所有者ID・リポジトリIDを含むsubject claimを発表しています。公式告知では、7月15日より後に作成したリポジトリに新形式を適用し、同日より後のリネーム・移管も対象としています。既存リポジトリは明示的なオプトインがない限り影響を受けないと説明されているため、作成時期だけでなく、その後の変更も確認が必要です。対象はgithub.comで、GitHub Enterprise Serverは含まれません。GitHub公式変更告知
変更の背景は名前の再利用です。名前だけを信頼すると、以前の名前が別の所有者に使われた場合にも同じ識別文字列になり得ます。新形式は名前に数値IDを加えて識別します。これは認証失敗を見つけたら制限を外す、という変更ではありません。信頼したい対象を正しい形式で指定するための変更です。
最初に「認証前」と「認証後」を分ける
OIDCを使うと、GitHub側へ長期のAWS認証情報を保存せずにAWSへアクセスする構成を取れます。GitHubのトークンを使ってAWS側のロールを引き受けるため、workflowにはトークン取得の許可、AWS側には信頼関係の設定が必要です。id-token: writeはトークン取得を許可する設定であり、それだけでAWSリソースの変更権限を与えるものではありません。GitHubのAWS接続手順
次の表は、調査を始める場所を分けるための整理です。表示されたエラーだけで原因を断定せず、どのステップまで成功したかを合わせて確認します。
| 止まる段階 | 最初に照合するもの | 避けたい対処 |
|---|---|---|
| OIDCトークンを取得できない | workflow/jobの権限設定と実行条件 | IAMの操作権限だけを増やす |
| AWSのロールを引き受けられない | 対象ロール、OIDCプロバイダ、aud、subの条件 |
subを広いワイルドカードへ変える |
| ロール取得後のAWS操作で失敗する | 実行主体、対象リソース、適用される許可・拒否 | subだけを何度も書き換える |
認証後のリクエストも、AWSでは各種ポリシーに基づいて許可・拒否が評価されます。明示的な拒否が許可に優先するなどの規則があるため、「ロールを取得できた」と「目的の操作が許可される」は分けて扱います。AWSのポリシー評価ロジック
subはリポジトリ名だけでなく、実行文脈まで照合する
新形式か旧形式かに加え、environmentを使うか、ブランチ実行か、pull requestかでもsubjectは変わります。GitHubの公式リファレンスは、environmentを参照するjobではenvironment名、environmentを参照しないpull requestではpull_request、そのいずれでもないブランチ実行ではブランチ名を含む例を示しています。OIDCの公式リファレンス
下記は標準形式の読み方を示す仮例です。組織名・リポジトリ名・数値ID・環境名は自分の対象へ置き換え、subjectをカスタマイズしている場合は実際の設定も照合してください。
旧形式・mainブランチ:
repo:example-org/sample-app:ref:refs/heads/main
新形式・mainブランチ:
repo:example-org@111111/sample-app@222222:ref:refs/heads/main
新形式・production環境:
repo:example-org@111111/sample-app@222222:environment:productionブランチ用の条件を、そのままenvironmentを使うjobへ当てはめないことが大切です。environmentで信頼する場合は、どのブランチからその環境へデプロイできるかも、GitHub側の保護規則と合わせて確認します。トークンを調査するときは、生のトークン全体を共有ログや外部のデコードサイトへ貼らず、権限を持つ担当者が必要なclaimだけを確認する運用を推奨します。
信頼ポリシーは許可対象を限定したまま合わせる
以下は、標準のAWS向けaudienceを使い、新形式の特定リポジトリ・mainブランチだけを照合するCondition部分の仮例です。完全な信頼ポリシーではありません。実際には対象AWSアカウントのOIDCプロバイダ、Principal、Actionなども確認する必要があります。
{
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:example-org@111111/sample-app@222222:ref:refs/heads/main"
}
}
}GitHubのAWS接続手順には、新旧それぞれのsubを使う例があります。コピー元が公式でも、自分のリポジトリが送る形式と異なれば照合できません。AWSもGitHubのOIDCを信頼するロールでsubを評価し、アクセス元を限定するよう案内しています。AWSのGitHub OIDC設定
修正の目的は「本来許可したい実行を通す」ことです。成功させるためだけに組織全体・全ブランチへ条件を広げず、対象repoと実行文脈を明示しましょう。旧形式へ戻す前提で進めるのではなく、実際のsubjectと信頼条件をそろえる方針を取ります。
新旧混在を、変更管理の確認項目にする
複数リポジトリで共通のIAM設定テンプレートを使う場合、まず対象ごとの形式を棚卸しし、移行する単位を決めることを提案します。下記は公式仕様から整理した運用例であり、GitHubやAWSが一律に要求する手順ではありません。
- リポジトリ、所有者、数値ID、作成・リネーム・移管の履歴、OIDC設定、対象ロール、branch/environmentを対応付ける。
- 現行の信頼条件を保存し、必要な変更と担当者をレビューする。旧新併用が必要なら対象と終了条件を明示し、無期限の広い許可にしない。
- 本番影響を抑えた検証環境で、許可した実行から想定ロールを取得できることを確認する。
- 許可しないブランチ・環境などからはロールを取得できないことも、各条件に対応する方法で確認する。
- 対象のAWS操作まで確かめ、テンプレート・運用資料・再確認日を更新する。
実行主体の照合には、AWS STSのGetCallerIdentityが返すAccountやArnを利用できます。ただし、このAPIの成功は、デプロイ対象を変更する権限まで確認したことにはなりません。GetCallerIdentityの公式仕様
既存リポジトリが動いている場合も、それだけで共通テンプレートが新規リポジトリへ適用できるとは判断しないことが重要です。今後の新規作成・移管時のチェックへ、subjectと信頼条件の照合を加えてください。担当間で残す資料の考え方は、開発から運用への引き継ぎでも整理しています。自社で持つ設定・運用責任を確認したい場合は、クラウドの責任共有モデルも参考になります。