@ripla/godd-mcp 1.0.6 → 1.0.7-canary.2

package/templates/notes-docs/007_guides/setup_infra.template.md

@@ -118,11 +118,17 @@ terraform init && terraform apply
 godd notes deploy -y
 ```
 
+> **`godd notes deploy` の実行前に、ローカルの Docker daemon（Docker Desktop 等）を起動しておいてください。** 起動していない状態で実行すると `Cannot connect to the Docker daemon at unix:///.../docker.sock` で即失敗します。この前提は事前の `✓ 前提条件 OK` チェックでは検知されません。
+
 ### 4. Secrets Manager に値を設定
 
-Terraform 適用後、以下の3つのシークレットに値を投入します。
+Terraform が生成する ECS タスク定義（`ecs.tf`）は、下記のシークレットすべてを環境変数としてマッピングします。**使わない機能の値も投入しないとタスクが起動しません**（未投入のシークレットがあると `GetSecretValue` に失敗しタスクが起動しない、または起動直後にクラッシュします）。
 シークレット名の `{env}` は入力した環境名（例: `dev`）に置き換えてください。
 
+> **空文字列は投入できません。** AWS Secrets Manager の仕様上、空文字列（`""`）は投入不可です（エラー: `Invalid length for parameter SecretString, value: 0, valid min length: 1`）。すべての必須シークレットに値を入れてください。
+>
+> **AI コーディングアシスタント経由での書き込みがブロックされる場合があります。** `aws secretsmanager put-secret-value` は安全機構（承認フロー等）によりエージェント経由の実行が止まることがあります。その場合は自分のターミナルで直接実行してください。
+
 #### jwt-secret
 
 JWT アクセストークンの署名・検証（HS256）に使用します。32文字以上のランダム文字列を設定してください。
@@ -147,41 +153,65 @@ aws secretsmanager put-secret-value \
 
 > パスワードは後から変更できますが、初回起動前に必ず設定してください。
 
-#### github-token（必須）
-
-docs ファイルの読取・PR 操作・Issue 操作に使用します。GitHub で Fine-grained personal access token を発行してください。
-
-**トークンの発行手順:**
+#### GitHub 連携（GitHub App 必須）
 
-1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → **Generate new token**
-2. **Resource owner** でリポジトリのオーナーを選択
-3. **Repository access** で対象リポジトリを選択
-4. **Permissions** で以下を設定:
+> **PAT（`github-token` / `GITHUB_TOKEN`）は禁止です。** Fine-grained PAT や Machine User PAT は使用できません。ECS タスク定義は `GITHUB_TOKEN` を注入しません。
 
-**Repository Permissions**
+docs ファイルの読取・PR 操作・Issue 操作に GitHub API を使います。**GitHub App の3変数すべてが必須**です（未設定だと Notes はモックモードで動作し、実際のリポジトリを読み書きできません）。
 
-| Permission | Level | 用途 |
+| シークレット | 型 | 内容 |
 |---|---|---|
-| `Contents` | `Read and write` | docs ファイルの読取、作成、更新、削除、画像アップロード、branch/commit 操作 |
-| `Pull requests` | `Read and write` | PR 作成、PR 一覧/詳細取得、draft/ready 切替、PR close |
-| `Issues` | `Read and write` | Issue 一覧/作成/更新、PR への label 付与、label 一覧取得 |
+| `github-app-id` | **int** | GitHub App の App ID |
+| `github-app-private-key` | string | GitHub App の秘密鍵（PEM 全文） |
+| `github-app-installation-id` | **int** | GitHub App のインストール ID |
 
-**自動で付与される権限**
+PR / Issue の author が個人アカウントではなく Bot 名義になります。組織で GitHub App がまだ無い場合の作成手順:
 
-| Permission | Level | 用途 |
-|---|---|---|
-| `Metadata` | `Read-only` | リポジトリ基本情報の参照 |
+1. GitHub → Organization の Settings → Developer settings → GitHub Apps → **New GitHub App**
+2. App name を入力（Webhook は Active のチェックを外す）
+3. Repository permissions で `Contents: Read & write` / `Pull requests: Read & write` / `Issues: Read & write` を設定
+4. **Create GitHub App** → **Generate a private key** で `.pem` をダウンロード（このページの **App ID** もメモ）
+5. Install App → 対象 Organization → Only select repositories で対象リポジトリを追加 → URL 末尾の数字が Installation ID（`https://github.com/organizations/<org>/settings/installations/<ID>`）
 
-5. トークンを生成してコピー
+既に組織に GitHub App がある場合は、対象リポジトリへのアクセス権限追加のみで OK です（本ガイド [setup_godd_notes.md](./setup_godd_notes.md) のセットアップ手順を参照）。
 
 **AWS CLI での設定:**
 
 ```bash
 aws secretsmanager put-secret-value \
-  --secret-id godd-notes/{env}/github-token \
-  --secret-string "ghp_xxxxxxxxxxxx"
+  --secret-id godd-notes/{env}/github-app-id \
+  --secret-string "123456" \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/{env}/github-app-private-key \
+  --secret-string file://path/to/private-key.pem \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/{env}/github-app-installation-id \
+  --secret-string "987654321" \
+  --profile <PROFILE> \
+  --region ap-northeast-1
 ```
 
+> **int 型**（`github-app-id` / `github-app-installation-id`）は数値の文字列（例: `"123456"`）を指定してください。文字列ダミー（`"unused"`）は Pydantic 型検証で失敗し、ECS タスクが起動直後にクラッシュループします。
+
+#### PAT 廃止時の ECS 移行（既存環境 — 必須順序）
+
+`lifecycle.ignore_changes` により ECS サービスは Terraform の新 TD を自動採用しない。次の順序を守ること:
+
+1. **先にデプロイ**（GitHub Actions `deploy-notes` または `godd notes deploy`）
+   現行 TD をクローンし `GITHUB_TOKEN` シークレット注入を除去した新リビジョンを登録してサービスを更新する
+2. `aws ecs wait services-stable`（または CI の Wait）で **stable** を確認する
+3. **その後** `terraform apply`
+   `removed { destroy = false }` により state から `github-token` を外すが、AWS 上のシークレットはすぐには消えない（旧 TD 参照の事故を防ぐ）
+4. 全環境の稼働 TD に `GITHUB_TOKEN` が残っていないことを確認したら、Secrets Manager の `godd-notes/{env}/github-token` を **手動削除**する
+
+> 順序を逆（apply でシークレットを先に destroy）にすると、旧 TD のまま再デプロイされたタスクが起動失敗する。
+
 ### 5. GitHub Secrets に CI/CD 用の値を登録
 
 生成される `.github/workflows/deploy-notes.yml` は、フロントエンドデプロイ後の CloudFront キャッシュ無効化に GitHub Secrets の `CLOUDFRONT_DISTRIBUTION_ID` を参照します。Terraform 適用後に以下で登録してください。
@@ -194,6 +224,29 @@ gh secret set CLOUDFRONT_DISTRIBUTION_ID \
 
 > 未登録の場合、deploy-app ジョブはキャッシュ無効化を warning 付きでスキップします（ジョブは失敗しません）。S3 へのデプロイは完了しますが、CloudFront のキャッシュ TTL が切れるまで旧コンテンツが配信され続けるため、登録を推奨します。
 
+### 6. デプロイ後に ECS タスクが安定しない場合
+
+`aws ecs describe-services` の `runningCount` / `rolloutState` だけでは「`IN_PROGRESS` のまま進まない」以上のことが分からず、原因特定にはタスクの停止理由とアプリログまで追う必要があります。
+
+```bash
+# 1. 停止済みタスクを確認（起動直後にクラッシュしている場合はここに出る）
+aws ecs list-tasks --cluster godd-notes --service-name notes-api --desired-status STOPPED
+
+# 2. 停止理由・終了コードを確認
+aws ecs describe-tasks --cluster godd-notes --tasks <task-arn> \
+  --query 'tasks[0].{stoppedReason:stoppedReason,exitCode:containers[0].exitCode}'
+
+# 3. アプリのスタックトレースを確認
+aws logs describe-log-streams --log-group-name /ecs/godd-notes-api --order-by LastEventTime --descending
+aws logs get-log-events --log-group-name /ecs/godd-notes-api --log-stream-name <stream>
+```
+
+Secrets Manager の値を修正しても、既に起動中/クラッシュループ中の ECS サービスには自動反映されません。修正後は必ず再デプロイしてください。
+
+```bash
+aws ecs update-service --cluster godd-notes --service notes-api --force-new-deployment
+```
+
 ---
 
 ## 設定の永続化

package/templates/terraform/aws/ecs.tf.hbs

@@ -98,7 +98,6 @@ resource "aws_ecs_task_definition" "api" {
       { name = "DB_USER", valueFrom = "${aws_secretsmanager_secret.rds_credentials.arn}:username::" },
       { name = "DB_PASSWORD", valueFrom = "${aws_secretsmanager_secret.rds_credentials.arn}:password::" },
       { name = "JWT_SECRET", valueFrom = aws_secretsmanager_secret.jwt_secret.arn },
-      { name = "GITHUB_TOKEN", valueFrom = aws_secretsmanager_secret.github_token.arn },
       { name = "GITHUB_APP_ID", valueFrom = aws_secretsmanager_secret.github_app_id.arn },
       { name = "GITHUB_APP_PRIVATE_KEY", valueFrom = aws_secretsmanager_secret.github_app_private_key.arn },
       { name = "GITHUB_APP_INSTALLATION_ID", valueFrom = aws_secretsmanager_secret.github_app_installation_id.arn },
@@ -139,4 +138,13 @@ resource "aws_ecs_service" "api" {
     container_name   = "notes-api"
     container_port   = local.container_port
   }
+
+  # CI / `godd notes deploy` register image revisions; ignore TF drift on TD.
+  # Deploy paths strip legacy GITHUB_TOKEN secret refs when cloning TDs.
+  lifecycle {
+    ignore_changes = [
+      task_definition,
+      desired_count,
+    ]
+  }
 }

package/templates/terraform/aws/provider.tf.hbs

@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 1.5"
+  required_version = ">= 1.7"
 
   required_providers {
     aws = {

package/templates/terraform/aws/secrets.tf.hbs

@@ -17,9 +17,17 @@ resource "aws_secretsmanager_secret" "jwt_secret" {
   tags = local.tags
 }
 
-resource "aws_secretsmanager_secret" "github_token" {
-  name = "godd-notes/${local.env}/github-token"
-  tags = local.tags
+# PAT-era stacks may still have aws_secretsmanager_secret.github_token in state.
+# Drop it from Terraform management without destroying the AWS secret, so an
+# apply cannot orphan running task definitions that still inject GITHUB_TOKEN.
+# After CI/`godd notes deploy` has registered a TD without GITHUB_TOKEN and the
+# service is stable, delete the AWS secret manually (see setup_infra runbook).
+removed {
+  from = aws_secretsmanager_secret.github_token
+
+  lifecycle {
+    destroy = false
+  }
 }
 
 resource "aws_secretsmanager_secret" "github_app_id" {