Troubleshoot
GitHub Actions のデプロイが失敗する時の対処
最終更新: 2026-04-24
症状
main ブランチ push 後の自動デプロイが赤くなる
- Permission denied (publickey) が頻発
- docker pull rate limit で止まる
- DB migration 失敗で traffic 切替前に終了
- sudo 権限エラー
想定される原因
- 1
SSH 鍵が deploy ユーザーに登録されていない
新しい鍵を Secrets に入れたが authorized_keys に反映されていない。
確認: deploy ユーザーの ~/.ssh/authorized_keys
- 2
sudoers 設定不足
systemctl reload / docker compose を sudoers で許可していない。
確認: sudo -l で許可コマンド確認
- 3
Docker Hub pull rate limit
匿名 pull は 100/6h 制限。login してないまま連続 deploy で到達。
確認: Actions ログに 'toomanyrequests' 文字列
- 4
DB マイグレーション失敗
既存データとスキーマ差分で migrate が落ちる。blue / green 切替前に死ぬ。
確認: migration logs / drizzle-kit / prisma migrate ログ
- 5
Secrets 取得失敗
環境変数名の typo / OIDC 設定不備で Secrets が空文字になる。
確認: Actions の env dump ログ(マスク)
対処手順
- Actions ログで具体的なエラーメッセージを特定
- SSH 鍵は ed25519 を発行、deploy 専用ユーザーに登録
- Docker Hub は Secrets に token を入れて login 済みに
- DB migrate を blue/green の切替前に実行、失敗したら rollout を止める
- /tools/github-actions の雛形で動作するワークフローを参照
よくある質問
デプロイが 5 分以上かかる
multi-stage Dockerfile + GHCR キャッシュ + --cache-from で短縮。/guides/github-actions-vps-deploy 参照。
secrets を workflow_dispatch 時に流出させたくない
echo やデバッグで secrets 値を露出しない + GitHub の Secret masking を信頼しない設計が推奨。