docs: Update GitHub Secrets setup guide with OIDC troubleshooting

- Add detailed OIDC provider creation steps
- Add IAM role trust policy examples
- Add troubleshooting section for 'Request ARN is invalid' error
- Include verification commands for OIDC and IAM setup
- Add step-by-step setup instructions for multi-account deployment

Author: Hirose-Sebastian-Taikai

GITHUB_SECRETS_SETUP.md

@@ -1,46 +1,105 @@
-# GitHub Secrets設定ガイド
+# GitHub Secrets Setup Guide
+
+## 概要
+このドキュメントでは、GitHub ActionsでAWS CloudFormationにデプロイするために必要なGitHub SecretsとIAMロールの設定手順を説明します。
 
 ## 必要なGitHub Secrets
 
-### 開発環境用
-- **`AWS_ROLE_ARN_DEV`**: 開発環境用のIAMロールARN
-  - 例: `arn:aws:iam::123456789012:role/LambdaFramework-github-actions-role-dev`
+### 1. AWS_ROLE_ARN_DEV (開発環境用)
+- **説明**: 開発環境（deployブランチ）で使用するIAMロールのARN
+- **例**: `arn:aws:iam::123456789012:role/LambdaFramework-github-actions-role`
 
-### 本番環境用
-- **`AWS_ROLE_ARN_PROD`**: 本番環境用のIAMロールARN
-  - 例: `arn:aws:iam::987654321098:role/LambdaFramework-github-actions-role-prod`
+### 2. AWS_ROLE_ARN_PROD (本番環境用)
+- **説明**: 本番環境（mainブランチ）で使用するIAMロールのARN
+- **例**: `arn:aws:iam::123456789012:role/LambdaFramework-github-actions-role`
 
-## 設定手順
+## IAMロールとOIDCプロバイダーの設定
 
-### 1. GitHub Secretsの設定
+### 1. OIDCプロバイダーの作成
 
-1. GitHubリポジトリの **Settings** → **Secrets and variables** → **Actions** に移動
-2. **New repository secret** をクリック
-3. 以下のSecretsを追加:
+#### 開発環境用AWSアカウント
+```bash
+# OIDCプロバイダーの作成
+aws iam create-open-id-connect-provider \
+  --url https://token.actions.githubusercontent.com \
+  --client-id-list sts.amazonaws.com \
+  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
 
+# 作成されたOIDCプロバイダーのARNを確認
+aws iam list-open-id-connect-providers
 ```
-Name: AWS_ROLE_ARN_DEV
-Value: arn:aws:iam::<DEV_ACCOUNT_ID>:role/<DEV_ROLE_NAME>
 
-Name: AWS_ROLE_ARN_PROD
-Value: arn:aws:iam::<PROD_ACCOUNT_ID>:role/<PROD_ROLE_NAME>
+#### 本番環境用AWSアカウント
+```bash
+# OIDCプロバイダーの作成
+aws iam create-open-id-connect-provider \
+  --url https://token.actions.githubusercontent.com \
+  --client-id-list sts.amazonaws.com \
+  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
+
+# 作成されたOIDCプロバイダーのARNを確認
+aws iam list-open-id-connect-providers
 ```
 
 ### 2. IAMロールの作成
 
-各AWSアカウントで以下のIAMロールを作成:
-
 #### 開発環境用IAMロール
 ```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "Federated": "arn:aws:iam::YOUR_DEV_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
+      },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+          "token.actions.githubusercontent.com:sub": "repo:cloudnative-co/python-lambda-frame:ref:refs/heads/deploy"
+        }
+      }
+    }
+  ]
+}
+```
+
+#### 本番環境用IAMロール
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "Federated": "arn:aws:iam::YOUR_PROD_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
+      },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+          "token.actions.githubusercontent.com:sub": "repo:cloudnative-co/python-lambda-frame:ref:refs/heads/main"
+        }
+      }
+    }
+  ]
+}
+```
+
+### 3. IAMポリシーの作成
+
+#### 開発環境用IAMポリシー
+```json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
       "Effect": "Allow",
       "Action": [
         "cloudformation:*",
-        "lambda:*",
         "s3:*",
+        "lambda:*",
         "iam:*",
         "logs:*"
       ],
@@ -50,7 +109,7 @@ Value: arn:aws:iam::<PROD_ACCOUNT_ID>:role/<PROD_ROLE_NAME>
 }
 ```
 
-#### 本番環境用IAMロール
+#### 本番環境用IAMポリシー
 ```json
 {
   "Version": "2012-10-17",
@@ -59,8 +118,8 @@ Value: arn:aws:iam::<PROD_ACCOUNT_ID>:role/<PROD_ROLE_NAME>
       "Effect": "Allow",
       "Action": [
         "cloudformation:*",
-        "lambda:*",
         "s3:*",
+        "lambda:*",
         "iam:*",
         "logs:*"
       ],
@@ -70,53 +129,115 @@ Value: arn:aws:iam::<PROD_ACCOUNT_ID>:role/<PROD_ROLE_NAME>
 }
 ```
 
-### 3. OIDCプロバイダーの設定
+## トラブルシューティング
+
+### 1. "Request ARN is invalid" エラーの解決
+
+#### A. OIDCプロバイダーの確認
+```bash
+# OIDCプロバイダーが存在するか確認
+aws iam list-open-id-connect-providers
+
+# 特定のOIDCプロバイダーの詳細を確認
+aws iam get-open-id-connect-provider --open-id-connect-provider-arn arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com
+```
+
+#### B. IAMロールの信頼関係の確認
+```bash
+# IAMロールの詳細を確認
+aws iam get-role --role-name LambdaFramework-github-actions-role
+
+# 信頼関係（Trust Policy）を確認
+aws iam get-role-policy --role-name LambdaFramework-github-actions-role --policy-name trust-policy
+```
+
+#### C. 正しいロールARNの確認
+```bash
+# 利用可能なIAMロールを一覧表示
+aws iam list-roles --query 'Roles[?contains(RoleName, `LambdaFramework`)].RoleName' --output table
+```
+
+### 2. よくある問題と解決方法
+
+#### A. OIDCプロバイダーが存在しない
+```bash
+# OIDCプロバイダーを作成
+aws iam create-open-id-connect-provider \
+  --url https://token.actions.githubusercontent.com \
+  --client-id-list sts.amazonaws.com \
+  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
+```
+
+#### B. 信頼関係が正しくない
+- IAMロールの信頼関係で、正しいOIDCプロバイダーARNを指定
+- 正しいリポジトリ名とブランチ名を指定
+
+#### C. GitHub Secretsが設定されていない
+- GitHubリポジトリのSettings → Secrets and variables → Actions
+- `AWS_ROLE_ARN_DEV`と`AWS_ROLE_ARN_PROD`を設定
 
-各AWSアカウントでGitHub Actions用のOIDCプロバイダーを設定:
+## 設定手順
 
+### 1. AWS CLIでOIDCプロバイダーを作成
 ```bash
-# 開発環境
+# 開発環境用
 aws iam create-open-id-connect-provider \
   --url https://token.actions.githubusercontent.com \
   --client-id-list sts.amazonaws.com \
   --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
 
-# 本番環境
+# 本番環境用
 aws iam create-open-id-connect-provider \
   --url https://token.actions.githubusercontent.com \
   --client-id-list sts.amazonaws.com \
   --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
 ```
 
-## デプロイ先の確認
+### 2. IAMロールを作成
+```bash
+# 開発環境用ロール
+aws iam create-role --role-name LambdaFramework-github-actions-role --assume-role-policy-document file://trust-policy-dev.json
+
+# 本番環境用ロール
+aws iam create-role --role-name LambdaFramework-github-actions-role --assume-role-policy-document file://trust-policy-prod.json
+```
+
+### 3. IAMポリシーをアタッチ
+```bash
+# 開発環境用ポリシー
+aws iam put-role-policy --role-name LambdaFramework-github-actions-role --policy-name LambdaFramework-github-actions-policy --policy-document file://policy-dev.json
+
+# 本番環境用ポリシー
+aws iam put-role-policy --role-name LambdaFramework-github-actions-role --policy-name LambdaFramework-github-actions-policy --policy-document file://policy-prod.json
+```
+
+### 4. GitHub Secretsを設定
+1. GitHubリポジトリにアクセス
+2. Settings → Secrets and variables → Actions
+3. New repository secretをクリック
+4. `AWS_ROLE_ARN_DEV`と`AWS_ROLE_ARN_PROD`を設定
+
+## デプロイ環境マッピング
 
-| ブランチ | AWSアカウント | スタック名 | 環境 |
-|---------|-------------|-----------|------|
-| `main` | 本番アカウント | `lambda-framework-prod` | production |
-| `deploy` | 開発アカウント | `lambda-framework-dev` | development |
+| ブランチ | 環境 | AWSロール | GitHub Secret |
+|---------|------|-----------|---------------|
+| main | production | LambdaFramework-github-actions-role | AWS_ROLE_ARN_PROD |
+| deploy | development | LambdaFramework-github-actions-role | AWS_ROLE_ARN_DEV |
 
-## ローカルデプロイ
+## ローカルデプロイコマンド
 
-### Bash版
+### 開発環境
 ```bash
-# 開発環境（デフォルトAWS Profile）
 ./deploy-env.sh development
+```
 
-# 開発環境（指定AWS Profile）
-./deploy-env.sh development dev-profile
-
-# 本番環境（指定AWS Profile）
-./deploy-env.sh production prod-profile
+### 本番環境
+```bash
+./deploy-env.sh production
 ```
 
 ### PowerShell版
 ```powershell
-# 開発環境（デフォルトAWS Profile）
 .\deploy-env.ps1 development
-
-# 開発環境（指定AWS Profile）
-.\deploy-env.ps1 development dev-profile
-
-# 本番環境（指定AWS Profile）
-.\deploy-env.ps1 production prod-profile
+.\deploy-env.ps1 production
 ```