Azure へのデプロイ

pnpm 11/12 と npm の使い分けはコマンドとトラブルシューティングを参照してください。

SwallowKit プロジェクトの Azure リソースをプロビジョニングし、CI/CD を設定します。このガイドを完了すると、Azure Static Web Apps 上で Azure Functions バックエンドと Cosmos DB を使ったアプリケーションが動作する状態になります。

前提条件

Azure アカウント
Azure CLI (az) のインストール
GitHub アカウント（GitHub Actions を使用する場合）
Azure DevOps アカウント（Azure Pipelines を使用する場合）

クイックスタート

1. プロジェクト初期化

bash

npx swallowkit init my-app
cd my-app

初期化時に CI/CD プロバイダーを選択:

GitHub Actions
Azure Pipelines

2. Azure リソースのプロビジョニング

bash

npx swallowkit provision --resource-group my-app-rg \
  --location japaneast --swa-location eastasia

リージョンを省略した場合は対話式に選択します。初回実行では Resource Group が存在しないことを確認して infra/main.bicep をデプロイし、migration baseline 0 を Resource Group タグへ記録します。実行前には plan と Azure コマンドが表示され、承認が必要です。

このコマンドは Bicep テンプレートを使用して以下を作成します:

Azure Static Web Apps
Azure Functions (Flex Consumption)
Azure Cosmos DB（初期化時に選択した Free Tier または Serverless）
マネージド ID（サービス間の安全な接続）

非対話環境では --location、--swa-location、--approve を明示してください。CI/CD の secrets は後述の Azure CLI コマンドで取得します。

3. コードのプッシュ

コードをプッシュして CI/CD ワークフローをトリガーします：

bash

git add .
git commit -m "Initial deployment"
git push origin main

注意: このプッシュで CI/CD ワークフローが自動実行されますが、シークレットが未登録のため失敗します。これは想定内です——次のステップに進んでください。

4. キャンセル・シークレット登録・再実行

ステップ 4-1: 自動実行された CI/CD をキャンセル

初回プッシュでトリガーされた CI/CD はシークレットがないため成功しません。キャンセルしてください：

GitHub Actions: Actions タブ → 実行中のワークフローをクリック → Cancel workflow
Azure Pipelines: Pipelines → 実行中のパイプラインをクリック → Cancel

ステップ 4-2: Azure CLI で secrets / variables を取得して登録

GitHub Actions の場合

GitHub リポジトリの Settings → Secrets and variables → Actions
Azure CLI で取得した値を使って以下のシークレットを追加：

AZURE_STATIC_WEB_APPS_API_TOKEN
AZURE_FUNCTIONAPP_NAME
AZURE_FUNCTIONAPP_PUBLISH_PROFILE

Azure Pipelines の場合

Azure DevOps → Pipelines → Library → Variable groups
azure-deployment という名前のグループを作成
Azure CLI で取得した値を使って以下を追加：

AZURE_STATIC_WEB_APPS_API_TOKEN
AZURE_FUNCTIONAPP_NAME
AZURE_FUNCTIONAPP_PUBLISH_PROFILE

ステップ 4-3: CI/CD ワークフローを手動で再実行

GitHub Actions: Actions タブ → 失敗したワークフローを選択 → Re-run all jobs
Azure Pipelines: Pipelines → 失敗したパイプラインを選択 → Run pipeline

生成されるリソース

Azure Static Web Apps

目的: Next.js アプリケーションのホスティング
モード: Standalone（最適化されたデプロイサイズ）
機能:
- グローバル CDN
- 自動 HTTPS
- カスタムドメイン対応

Azure Functions

プラン: Flex Consumption
ランタイム: 初期化時に選択（TypeScript/Node.js 22、C#/.NET Isolated 10.0、Python 3.11）
機能:
- HTTP トリガー
- Cosmos DB バインディング
- Zod スキーマ検証

Azure Cosmos DB

モード: 初期化時に選択した Free Tier または Serverless
機能:
- 自動スケーリング
- グローバル分散
- RBAC によるアクセス制御

マネージド ID

種類: システム割り当てマネージド ID
目的: 接続文字列なしでサービス間を安全に接続
権限: Cosmos DB への読み取り/書き込みアクセス

CI/CD ワークフロー

生成されるファイル

.github/workflows/           # GitHub Actions の場合
├── static-web-app.yml       # SWA デプロイ
└── azure-functions.yml      # Functions デプロイ

pipelines/                   # Azure Pipelines の場合
├── static-web-app.yml
└── azure-functions.yml

ワークフローの動作

Static Web Apps ワークフロー:

トリガー: main ブランチへのプッシュ、app/**、components/**、lib/** の変更
処理:
1. Next.js を standalone モードでビルド
2. Azure Static Web Apps へデプロイ
3. プレビュー環境を作成（PR の場合）

Azure Functions ワークフロー:

トリガー: main ブランチへのプッシュ、functions/** の変更
処理:
1. 依存関係のインストール
2. TypeScript のビルド
3. Azure Functions へデプロイ

パスベーストリガー

効率的なデプロイのため、変更されたファイルに応じて適切なワークフローのみが実行されます:

フロントエンド変更（app/, components/, lib/）→ SWA のみデプロイ
バックエンド変更（functions/）→ Functions のみデプロイ
両方変更 → 両方デプロイ

環境変数

ローカル開発（`.env.local`）

bash

# Cosmos DB Emulator
COSMOS_DB_ENDPOINT=https://localhost:8081/
COSMOS_DB_KEY=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

# Azure Functions (ローカル)
BACKEND_API_URL=http://localhost:7071

本番環境（Azure）

bash

# Azure Functions
BACKEND_API_URL=https://<function-app-name>.azurewebsites.net

# Cosmos DB（マネージド ID 使用 - キー不要）
COSMOS_DB_ENDPOINT=https://<cosmosdb-account-name>.documents.azure.com:443/

重要: 本番環境では COSMOS_DB_KEY は不要です。マネージド ID が自動的に認証を処理します。

Azure での環境変数設定

Static Web Apps:

bash

az staticwebapp appsettings set \
  --name <swa-name> \
  --setting-names \
    BACKEND_API_URL=https://<function-name>.azurewebsites.net \
    COSMOS_DB_ENDPOINT=https://<cosmosdb-name>.documents.azure.com:443/

Azure Functions:

bash

az functionapp config appsettings set \
  --name <function-name> \
  --resource-group my-app-rg \
  --settings \
    COSMOS_DB_ENDPOINT=https://<cosmosdb-name>.documents.azure.com:443/

インフラストラクチャのカスタマイズ

差分 Infrastructure Migration

infra/
├── main.bicep               # メインオーケストレーション
├── main.parameters.json     # パラメータ
├── modules/                 # baseline リソース
└── migrations/
    ├── manifest.json        # version と checksum
    └── 0001-add-search/     # 追加リソース用の独立 Bicep

モデルを scaffold すると、新しい Cosmos DB コンテナーは migration として生成されます。任意の追加リソースは次のコマンドで作成します。

bash

npx swallowkit create-migration add-search
# infra/migrations/0001-add-search/main.bicep を編集
npx swallowkit provision -g my-app-rg --location japaneast --swa-location eastasia

provision は Resource Group タグの version/checksum とローカル manifest を比較し、未適用 migration だけを昇順に実行します。各 migration の成功後にタグを進めるため、失敗時は同じコマンドを再計画・再実行できます。適用済み migration は編集せず、修正用の新しい migration を追加してください。

旧バージョンで作成したプロジェクト

bash

npx swallowkit migrations init --legacy-baseline
npx swallowkit provision -g my-app-rg \
  --location japaneast --swa-location eastasia \
  --adopt-existing --baseline 0 --what-if

最初のコマンドは現在の infra/ を baseline 0 として記録するだけで、Azure を変更しません。adoption も main.bicep をデプロイせず、確認後に状態タグだけを追加します。what-if に Create/Delete が含まれる場合は、未デプロイ変更を migration へ切り出すまで停止します。Modify は警告として表示されるため、Portal で追加した Functions 設定などを確認してください。

Baseline の明示的な再適用

既存 baseline リソースを変更する必要がある場合だけ --reconcile --what-if を使います。

bash

npx swallowkit provision -g my-app-rg \
  --location japaneast --swa-location eastasia \
  --reconcile --what-if

reconcile は main.bicep 全体を再デプロイし、Functions の app settings など template 管理プロパティを戻す可能性があります。通常の provision が自動的に reconcile へ切り替わることはありません。

トラブルシューティング

デプロイが失敗する

症状: CI/CD パイプラインがエラーで失敗

解決策:

GitHub/Azure DevOps のログを確認
シークレットが正しく設定されているか確認
Azure リソースが正常にプロビジョニングされているか確認

bash

# リソースの確認
az resource list --resource-group my-app-rg --output table

Functions に接続できない

症状: BFF から Functions への呼び出しが失敗

解決策:

BACKEND_API_URL が正しく設定されているか確認
CORS 設定を確認

bash

az functionapp cors show \
  --name <function-name> \
  --resource-group my-app-rg

Functions が実行中か確認

bash

az functionapp show \
  --name <function-name> \
  --resource-group my-app-rg \
  --query "state" -o tsv

Cosmos DB 接続エラー

症状: "Unauthorized" または接続エラー

解決策:

マネージド ID が有効か確認

bash

az functionapp identity show \
  --name <function-name> \
  --resource-group my-app-rg

RBAC ロールが割り当てられているか確認

bash

az cosmosdb sql role assignment list \
  --account-name <cosmosdb-name> \
  --resource-group my-app-rg

エンドポイント URL が正しいか確認

ビルドが遅い

症状: Next.js ビルドに時間がかかる

解決策:

.next キャッシュを使用

yaml

# .github/workflows/static-web-app.yml
- uses: actions/cache@v3
  with:
    path: .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

standalone モードを確認（自動で有効）

次のステップ

CLI リファレンス - 全コマンドの詳細
Scaffold ガイド - CRUD コード生成

Azure へのデプロイ ​

目次 ​

前提条件 ​

クイックスタート ​

1. プロジェクト初期化 ​

2. Azure リソースのプロビジョニング ​

3. コードのプッシュ ​

4. キャンセル・シークレット登録・再実行 ​

ステップ 4-1: 自動実行された CI/CD をキャンセル ​

ステップ 4-2: Azure CLI で secrets / variables を取得して登録 ​

GitHub Actions の場合 ​

Azure Pipelines の場合 ​

ステップ 4-3: CI/CD ワークフローを手動で再実行 ​

生成されるリソース ​

Azure Static Web Apps ​

Azure Functions ​

Azure Cosmos DB ​

マネージド ID ​

CI/CD ワークフロー ​

生成されるファイル ​

ワークフローの動作 ​

パスベーストリガー ​

環境変数 ​

ローカル開発（.env.local） ​

本番環境（Azure） ​

Azure での環境変数設定 ​

インフラストラクチャのカスタマイズ ​

差分 Infrastructure Migration ​

旧バージョンで作成したプロジェクト ​

Baseline の明示的な再適用 ​

トラブルシューティング ​

デプロイが失敗する ​

Functions に接続できない ​

Cosmos DB 接続エラー ​

ビルドが遅い ​

次のステップ ​

Azure へのデプロイ

目次

前提条件

クイックスタート

1. プロジェクト初期化

2. Azure リソースのプロビジョニング

3. コードのプッシュ

4. キャンセル・シークレット登録・再実行

ステップ 4-1: 自動実行された CI/CD をキャンセル

ステップ 4-2: Azure CLI で secrets / variables を取得して登録

GitHub Actions の場合

Azure Pipelines の場合

ステップ 4-3: CI/CD ワークフローを手動で再実行

生成されるリソース

Azure Static Web Apps

Azure Functions

Azure Cosmos DB

マネージド ID

CI/CD ワークフロー

生成されるファイル

ワークフローの動作

パスベーストリガー

環境変数

ローカル開発（`.env.local`）

本番環境（Azure）

Azure での環境変数設定

インフラストラクチャのカスタマイズ

差分 Infrastructure Migration

旧バージョンで作成したプロジェクト

Baseline の明示的な再適用

トラブルシューティング

デプロイが失敗する

Functions に接続できない

Cosmos DB 接続エラー

ビルドが遅い

次のステップ