From fd1170d29770acd9fbe11e042dd2f3c385cef8ab Mon Sep 17 00:00:00 2001 From: r-ikeda Date: Tue, 5 May 2026 07:17:14 +0900 Subject: [PATCH 1/2] =?UTF-8?q?README:=20AWS=20=E3=82=BB=E3=83=83=E3=83=88?= =?UTF-8?q?=E3=82=A2=E3=83=83=E3=83=97=E5=AE=8C=E4=BA=86=E3=82=92=E5=8F=8D?= =?UTF-8?q?=E6=98=A0=E3=80=81=E3=83=87=E3=83=97=E3=83=AD=E3=82=A4=E6=89=8B?= =?UTF-8?q?=E9=A0=86=E3=82=92=E4=B8=BB=E8=BB=B8=E3=81=AB=E5=86=8D=E7=B7=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OIDC Provider と IAM Role github-actions-ic-gr-deploy の作成は完了済み。 日常運用に必要な「prod に push されたら自動デプロイ」の手順を前面に出し、長い AWS 初回セットアップ手順は「災害復旧 / 再構築」セクションへ移動。あわせて失敗時の切り分けポイントを追加。 Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 82 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 49 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index c2878e3..73d008a 100644 --- a/README.md +++ b/README.md @@ -34,21 +34,41 @@ develop ← 機能ブランチからの PR を集約（デフォルト） `prod` ブランチへの push で GitHub Actions が自動デプロイする。手動操作は不要。 +### 手順（推奨：PR 経由） + +GitHub UI から段階的に PR を立てる。 + +1. `develop` 上で動作確認（`npm run dev` / プレビュー環境など） +2. `develop → main` の PR を作成・マージ（ステージング相当） +3. `main → prod` の PR を作成・マージ（**push された瞬間に本番デプロイが走る**） +4. Actions タブで `Deploy to ic-gr.net` ジョブが完走するのを確認 +5. `https://www.ic-gr.net/` を全ページ + 直リンクハードリロードで確認 + +### 手順（緊急時：CLI から直接） + +`prod` への push が直接走るため取り扱い注意。 + ```bash -# 例: develop で動作確認 → main でステージ確認 → prod に進める git checkout main && git merge --no-ff develop && git push git checkout prod && git merge --no-ff main && git push # ← ここでデプロイ起動 ``` -ワークフロー: +### ワークフロー | ファイル | トリガ | やること | |---|---|---| | `.github/workflows/ci.yml` | `develop` / `main` / `prod` への PR | `npm run lint` + `npm run build` | -| `.github/workflows/deploy.yml` | `prod` への push（または手動 dispatch） | `next build` → `aws s3 sync out/` → CloudFront invalidation | +| `.github/workflows/deploy.yml` | `prod` への push（または手動 `workflow_dispatch`） | `next build` → `aws s3 sync out/` → CloudFront invalidation | GitHub Actions は **OIDC で IAM Role を assume する**ので、リポジトリに長期 AWS 認証情報を置かない。 +### 失敗時の挙動 + +- **CI ジョブが赤** → コードまたは型の問題。原因を直して PR を更新する +- **deploy ジョブが赤（assume role 失敗）** → IAM Role の信頼ポリシーがリポジトリ名・ブランチを正しく指しているか確認（[トラブルシュート](#災害復旧--再構築)） +- **deploy ジョブが赤（s3 sync / invalidation 失敗）** → 権限ポリシー、もしくは S3 / CloudFront のリソース ID 不一致を疑う +- **デプロイは完走したのに反映されない** → CloudFront のキャッシュ。invalidation が走っているはずだが、ブラウザ側のキャッシュも疑う（DevTools → Disable cache）。`E3CUYP7CXV3V06`（`*.ic-gr.com` 系）には invalidation を撃っていない + ### 緊急時の手動デプロイ（フォールバック） ローカルから AWS CLI で同じ操作を実行できる。 @@ -80,24 +100,37 @@ aws --profile ic-gr cloudfront create-invalidation \ `output: 'export'` + `trailingSlash: true` により、各ルートが `out//index.html` で生成される。CloudFront の Custom Error Response 設定なしでハードリロードでも 200 が返る。 -### 初回セットアップ手順（`prod` 初回 push 前に一度だけ実施） +> **AWS 側の初回セットアップは完了済み**（OIDC Provider と IAM Role `github-actions-ic-gr-deploy` は作成済み）。日常運用では追加の AWS 操作は不要。再構築が必要になった場合のみ [災害復旧 / 再構築](#災害復旧--再構築) を参照。 + +--- -ローカルで `aws --profile ic-gr` を使う前提で記載。Console で行っても可。 +## 災害復旧 / 再構築 -#### 1. GitHub OIDC Provider を作成 +AWS リソースを誤って消したり別アカウントへ引越す際の手順。日常運用では使わない。 + +### OIDC Provider と IAM Role の再作成 + +`aws --profile ic-gr` で以下を順に実行する。 ```bash +# 1. OIDC Provider aws --profile ic-gr iam create-open-id-connect-provider \ --url https://token.actions.githubusercontent.com \ --client-id-list sts.amazonaws.com \ --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1 -``` -> サムプリントは GitHub 公式の値。詳細は [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) を参照。既に作成済みのアカウントではこのコマンドはスキップする。 +# 2. IAM Role（trust-policy.json と role-policy.json を作ってから） +aws --profile ic-gr iam create-role \ + --role-name github-actions-ic-gr-deploy \ + --assume-role-policy-document file://trust-policy.json -#### 2. デプロイ用 IAM Role を作成 +aws --profile ic-gr iam put-role-policy \ + --role-name github-actions-ic-gr-deploy \ + --policy-name deploy \ + --policy-document file://role-policy.json +``` -信頼ポリシー（`trust-policy.json`）: +`trust-policy.json`（GitHub Actions に AssumeRole を許可する条件）: ```json { @@ -122,7 +155,7 @@ aws --profile ic-gr iam create-open-id-connect-provider \ } ``` -権限ポリシー（`role-policy.json`）: +`role-policy.json`（このロールが実行できるアクション）: ```json { @@ -147,30 +180,13 @@ aws --profile ic-gr iam create-open-id-connect-provider \ } ``` -作成コマンド: - -```bash -aws --profile ic-gr iam create-role \ - --role-name github-actions-ic-gr-deploy \ - --assume-role-policy-document file://trust-policy.json - -aws --profile ic-gr iam put-role-policy \ - --role-name github-actions-ic-gr-deploy \ - --policy-name deploy \ - --policy-document file://role-policy.json -``` - -### 動作確認 - -セットアップ後、初回は手動トリガーで安全に確認できる: +### 切り分けのポイント -1. GitHub の `Actions` タブ → `Deploy to ic-gr.net` → `Run workflow` → ブランチ `prod` を指定 -2. ジョブが完走したら `https://www.ic-gr.net/` を全ページ + 直リンクハードリロードで確認 +deploy ジョブが落ちた時の典型的な原因: -エラーが出たら主に以下のいずれか: -- IAM Role の信頼ポリシー（`sub` 条件）がリポジトリ名・ブランチ名と一致していない -- IAM Role の権限ポリシーで S3 / CloudFront の対象リソース ARN が違う -- OIDC Provider のサムプリントが古い（GitHub 側のキー更新時） +- **AssumeRole 失敗**: 信頼ポリシーの `sub` がリポジトリ名・ブランチ名と一致していない（リネーム後など） +- **S3 / CloudFront 操作で `AccessDenied`**: 権限ポリシーで指定したリソース ARN が違う +- **OIDC Provider 認証エラー**: GitHub 側のキー更新でサムプリントが古くなった可能性 --- From 570f53bbd09f0e81343d48c74d5ed15e3fa3c052 Mon Sep 17 00:00:00 2001 From: r-ikeda Date: Tue, 5 May 2026 07:19:52 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=E3=83=96=E3=83=A9=E3=83=B3=E3=83=81?= =?UTF-8?q?=E9=81=8B=E7=94=A8=E3=82=92=20develop=20=E2=86=92=20prod=20?= =?UTF-8?q?=E3=81=AE=202=20=E6=AE=B5=E9=9A=8E=E3=81=AB=E5=A4=89=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ステージング環境を持たないため main を経由する 3 段階運用をやめ、develop での動作確認後にそのまま prod に進める方針に揃える。 - README.md / CLAUDE.md: フロー図と手順を develop → prod に更新 - .github/workflows/ci.yml: PR トリガから main を削除 main ブランチ自体は当面残すが、新規 PR ターゲットとしては使わない。 Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/ci.yml | 2 +- CLAUDE.md | 8 +++----- README.md | 20 +++++++------------- 3 files changed, 11 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a197136..90676b9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,7 +2,7 @@ name: CI on: pull_request: - branches: [develop, main, prod] + branches: [develop, prod] jobs: build: diff --git a/CLAUDE.md b/CLAUDE.md index 7d2b72c..5f53cc4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,12 +22,11 @@ npm run lint develop ← 機能ブランチからの PR を集約 │ ▼ - main ← ステージング想定 - │ - ▼ prod ← push されると本番デプロイ ``` +ステージング環境は存在しない。`develop` で動作確認後にそのまま `prod` へ進める。 + ワークフロー: - `.github/workflows/ci.yml` — PR 時に `npm run lint` + `npm run build` を実行 - `.github/workflows/deploy.yml` — `prod` push をトリガに `next build` → `aws s3 sync out/` → CloudFront invalidation @@ -113,7 +112,6 @@ ic-gr-website/ ## ブランチ運用 - `develop` （デフォルト）: 機能ブランチからの PR を集約 -- `main`: ステージング相当 - `prod`: push されると本番デプロイ -- 旧 `gh-pages` ブランチは GitHub Pages 時代の遺物。今は不要なので削除して問題ない +- 旧 `main` / `gh-pages` ブランチは過去の遺物。ステージングは持たない運用に変更したため `main` は使わない - 機能ブランチは `feature/` 命名で `develop` から切る diff --git a/README.md b/README.md index 73d008a..f7fae2a 100644 --- a/README.md +++ b/README.md @@ -20,13 +20,11 @@ npm run lint develop ← 機能ブランチからの PR を集約（デフォルト） │ ▼ - main ← ステージング相当 - │ - ▼ prod ← push されると本番デプロイ ``` 機能ブランチは `feature/` 命名で `develop` から切る。 +ステージング環境は存在しないため、`develop` での動作確認後にそのまま `prod` へ進める。 --- @@ -36,28 +34,24 @@ develop ← 機能ブランチからの PR を集約（デフォルト） ### 手順（推奨：PR 経由） -GitHub UI から段階的に PR を立てる。 - -1. `develop` 上で動作確認（`npm run dev` / プレビュー環境など） -2. `develop → main` の PR を作成・マージ（ステージング相当） -3. `main → prod` の PR を作成・マージ（**push された瞬間に本番デプロイが走る**） -4. Actions タブで `Deploy to ic-gr.net` ジョブが完走するのを確認 -5. `https://www.ic-gr.net/` を全ページ + 直リンクハードリロードで確認 +1. `develop` 上で動作確認（`npm run dev` でローカル確認、必要なら機能ブランチを develop に取り込む） +2. `develop → prod` の PR を作成・マージ（**push された瞬間に本番デプロイが走る**） +3. Actions タブで `Deploy to ic-gr.net` ジョブが完走するのを確認 +4. `https://www.ic-gr.net/` を全ページ + 直リンクハードリロードで確認 ### 手順（緊急時：CLI から直接） `prod` への push が直接走るため取り扱い注意。 ```bash -git checkout main && git merge --no-ff develop && git push -git checkout prod && git merge --no-ff main && git push # ← ここでデプロイ起動 +git checkout prod && git merge --no-ff develop && git push # ← ここでデプロイ起動 ``` ### ワークフロー | ファイル | トリガ | やること | |---|---|---| -| `.github/workflows/ci.yml` | `develop` / `main` / `prod` への PR | `npm run lint` + `npm run build` | +| `.github/workflows/ci.yml` | `develop` / `prod` への PR | `npm run lint` + `npm run build` | | `.github/workflows/deploy.yml` | `prod` への push（または手動 `workflow_dispatch`） | `next build` → `aws s3 sync out/` → CloudFront invalidation | GitHub Actions は **OIDC で IAM Role を assume する**ので、リポジトリに長期 AWS 認証情報を置かない。