Azure Static Web Apps のビルド構成

[アーティクル]
11/08/2024

Azure Static Web Apps のビルド構成では、GitHub Actions または Azure Pipelines が使用されます。サイトごとに、サイトのビルドとデプロイの方法を制御する YAML 構成ファイルがあります。この記事では、ファイルの構造とオプションについて説明します。

使用可能な構成設定について、次の表で説明します。

プロパティ	内容	必須
`app_location`	このフォルダーには、フロントエンドアプリケーションのソースコードが含まれています。値は、GitHub のリポジトリのルートと Azure DevOps の現在の作業フォルダーに対して相対的です。 `skip_app_build: true` と一緒に使用すると、この値はアプリのビルド出力の場所になります。	はい
`api_location`	このフォルダーには、API アプリケーションのソースコードが含まれています。値は、GitHub のリポジトリのルートと Azure DevOps の現在の作業フォルダーに対して相対的です。 `skip_api_build: true` と一緒に使用すると、この値は API のビルド出力の場所になります。	いいえ
`output_location`	Web アプリでビルドステップを実行する場合、出力場所は、パブリックファイルが生成されるフォルダーになります。ほとんどのプロジェクトでは、`output_location` は `app_location` に対して相対的です。ただし、.NET プロジェクトの場合、その場所は出力フォルダーに対する相対パスです。	いいえ
`app_build_command`	Node.js アプリケーションの場合は、静的コンテンツアプリケーションをビルドするためのカスタムコマンドを定義できます。たとえば、Angular アプリケーションの運用ビルドを構成するには、`build-prod` という名前の npm スクリプトを作成して `ng build --prod` を実行し、カスタムコマンドとして `npm run build-prod` を入力します。空白のままにすると、ワークフローでは `npm run build` または `npm run build:azure` コマンドの実行が試みられます。	いいえ
`api_build_command`	Node.js アプリケーションの場合、Azure Functions API アプリケーションをビルドするためのカスタムコマンドを定義できます。	いいえ
`skip_app_build`	フロントエンドアプリのビルドをスキップするには、値を `true` に設定します。	いいえ
`skip_api_build`	API 関数のビルドをスキップするには、値を `true` に設定します。	いいえ
`cwd` (Azure Pipelines のみ)	作業フォルダーへの絶対パス。既定値は `$(System.DefaultWorkingDirectory)` です。	いいえ
`build_timeout_in_minutes`	ビルドタイムアウトをカスタマイズするには、この値を設定します。既定値は `15` です。	いいえ

これらの設定を使用すると、静的 Web アプリの継続的インテグレーションと継続的デリバリー (CI/CD) を実行するために、GitHub Actions または Azure Pipelines を設定できます。

ファイル名と場所

GitHub アクションによって構成ファイルが生成され、.github/workflows フォルダーに格納されます。名前は次の形式です: azure-static-web-apps-<RANDOM_NAME>.yml。

既定では、構成ファイルは、リポジトリのルートに azure-pipelines.yml という名前で格納されます。

セキュリティ

ビルド構成をセキュリティで保護するために、2 つの異なるデプロイ承認ポリシーから選択できます。 Static Web Apps では、Azure デプロイトークン (推奨)、または GitHub アクセストークンの使用がサポートされています。

アプリでデプロイ承認ポリシーを設定するには、次の手順に従います。

新しいアプリ: 静的 Web アプリを作成する場合、[デプロイの構成] タブで、[デプロイ承認ポリシー] を選択します。
既存のアプリ: 既存のアプリを更新するには、[設定]>[構成]>[デプロイの構成] の順に移動し、[デプロイ承認ポリシー] を選択します。

[ビルド構成]

次のサンプル構成では、リポジトリの変更を監視します。コミットが main ブランチにプッシュされると、app_location フォルダーからアプリケーションがビルドされ、output_location 内のファイルがパブリック Web に提供されます。さらに、api フォルダー内のアプリケーションが、サイトの api パスで使用可能になります。

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

この構成では次のようになります。

main ブランチのコミットが監視されます。
app_location は、Web アプリのソースファイルが格納されている src フォルダーを指します。この値は作業ディレクトリ (cwd) に対する相対パスです。これを作業ディレクトリに設定するには、/ を使用します。
api_location は、サイトの API エンドポイントの Azure Functions アプリケーションが格納されている api フォルダーを指します。この値は作業ディレクトリ (cwd) に対する相対パスです。これを作業ディレクトリに設定するには、/ を使用します。
output_location は、アプリのソースファイルの最終バージョンが格納されている public フォルダーを指します。この値は、app_location に対する相対パスです。 .NET プロジェクトの場合、その場所は出力フォルダーに対する相対パスです。
cwd は、作業ディレクトリを指す絶対パスです。既定値は $(System.DefaultWorkingDirectory) です。
$(deployment_token) 変数は、生成された Azure DevOps デプロイトークンを指します。

Note

app_location と api_location は、作業ディレクトリ (cwd) に対する相対パスであり、cwd のサブディレクトリである必要があります。

Azure デプロイトークン
GitHub アクセストークン

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    permissions:
       id-token: write
       contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Install OIDC Client from Core Package
        run: npm install @actions/core@1.6.0 @actions/http-client
      - name: Get Id Token
        uses: actions/github-script@v6
        id: idtoken
        with:
           script: |
               const coredemo = require('@actions/core')
               return await coredemo.getIDToken()
           result-encoding: string
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_WATER }}
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "dist/angular-basic" # Built app content directory - optional
          production_branch: "dev"
          github_id_token: ${{ steps.idtoken.outputs.result }}
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_WATER_030D91C1E }}
          action: "close"

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations ######
          app_location: "src" # App source code path relative to repository root
          api_location: "api" # Api source code path relative to repository root - optional
          output_location: "public" # Built app content directory, relative to app_location - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

この構成では次のようになります。

main ブランチのコミットが監視されます。
ブランチで pull request が開かれた、同期された、再度開かれた、または閉じられたときに、GitHub Actions のワークフローがトリガーmainされます。
on プロパティにリストされているブランチに対してコミットをプッシュするか pull request を開くと、build_and_deploy_job が実行されます。
app_location は、Web アプリのソースファイルが格納されている src フォルダーを指します。この値をリポジトリのルートに設定するには、/ を使用します。
api_location は、サイトの API エンドポイントの Azure Functions アプリケーションが格納されている api フォルダーを指します。この値をリポジトリのルートに設定するには、/ を使用します。
output_location は、アプリのソースファイルの最終バージョンが格納されている public フォルダーを指します。これは、app_location に対する相対パスです。 .NET プロジェクトの場合、その場所は発行出力フォルダーに対する相対パスです。

repo_token、action、および azure_static_web_apps_api_token の値は、Azure Static Web Apps によって設定されるため、変更しないでください。

Close Pull Request ジョブは、ビルドとデプロイをトリガーしたプル要求を自動的に閉じます。このオプションのジョブは、プロセスを機能させるために必要ありません。

pull request が開かれると、Azure Static Web Apps GitHub アクションによってアプリがビルドされ、ステージング環境にデプロイされます。その後、Close Pull Request ジョブは、pull request がまだ開いているかどうかを確認し、完了メッセージで閉じます。

このジョブは、pull request ワークフローを整理し、古い pull request を防ぐのに役立ちます。ランタイムが pull request を自動的に閉じると、リポジトリは最新の状態のままになり、チームに状態が通知されます。

Close Pull Request ジョブは Azure Static Web Apps GitHub Actions ワークフローの一部であり、マージ後の pull request を閉じます。 Azure/static-web-apps-deploy アクションは、認証に azure_static_web_apps_api_token を必要とするアプリを Azure Static Web Apps にデプロイします。

カスタムビルドコマンド

Node.js アプリケーションの場合、アプリまたは API のビルドプロセス中に実行されるコマンドをきめ細かく制御できます。次の例は、app_build_command と api_build_command の値を使用してビルドを定義する方法を示しています。

Note

現在、Node.js ビルド用の app_build_command と api_build_command のみを定義できます。 Node.js バージョンを指定するには、package.json ファイル内の engines フィールドを使用します。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: '/'
  api_location: 'api'
  output_location: 'dist'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

フロントエンドアプリのビルドをスキップする

フロントエンドアプリのビルドを完全に制御する必要がある場合は、前のステップでビルドしたアプリの自動ビルドとデプロイをバイパスできます。

フロントエンドアプリのビルドをスキップするには:

app_location をデプロイするファイルの場所に設定します。
skip_app_build を true に設定します。
output_location を空の文字列 ('') に設定します。

注意

"出力" ディレクトリに staticwebapp.config.json ファイルもコピーされていることを確認してください。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

API のビルドをスキップする

API のビルドをスキップする場合、自動ビルドをバイパスし、前の手順でビルドした API をデプロイできます。

API のビルドをスキップする手順:

staticwebapp.config.json ファイルで、apiRuntime を正しいランタイムとバージョンに設定します。サポートされているランタイムとバージョンの一覧については、「Azure Static Web Apps の構成」を参照してください。
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
skip_api_build を true に設定します。
api_location は、デプロイするビルド済み API アプリを含むフォルダーに設定します。このパスは、GitHub Actions のリポジトリルートおよび Azure Pipelines 内の cwd に対して相対的です。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: "src" # App source code path relative to repository root
  api_location: "api" # Api source code path relative to repository root - optional
  output_location: "public" # Built app content directory, relative to app_location - optional
  skip_api_build: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

ビルドタイムアウトの延長

既定では、アプリと API のビルドは 15 分に制限されています。 build_timeout_in_minutes プロパティを設定することで、ビルドタイムアウトを延長できます。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

デプロイシークレットを使用せずにワークフローを実行する

一部のシークレットが見つからない場合でも、ワークフローを処理し続ける必要がある場合があります。定義されたシークレットなしで続行するようにワークフローを構成するには、SKIP_DEPLOY_ON_MISSING_SECRETS 環境変数を true に設定します。

この機能を有効にすると、サイトのコンテンツをデプロイせずにワークフローを続行できます。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

環境変数

ビルドの環境変数を設定するには、ジョブの構成の env セクションを使用します。

Oryx で使用される環境変数の詳細については、「Oryx 構成」を参照してください。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Monorepo のサポート

Monorepo は、複数のアプリケーションのコードが格納されているリポジトリです。ワークフローでは、既定でリポジトリ内のすべてのファイルを追跡しますが、1 つのアプリを対象とするように構成を調整できます。

1 つのアプリに対してワークフローファイルをターゲットにするには、push セクションと pull_request セクションにパスを指定します。

monorepo を設定すると、各静的アプリ構成のスコープは、1 つのアプリのファイルのみになります。リポジトリの .github/workflows フォルダー内で異なるワークフローファイルが同時に存在します。

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

次の例では、azure-static-web-apps-purple-pond.yml という名前のファイルの push セクションと pull_request セクションに paths ノードを追加する方法を示しています。

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

この例では、次のファイルに加えられた変更によってのみ、新しいビルドがトリガーされます。

app1 フォルダー内のすべてのファイル
api1 フォルダー内のすべてのファイル
アプリの azure-static-web-apps-purple-pond.yml ワークフローファイルへの変更

1 つのリポジトリで複数のアプリケーションをサポートするには、別のワークフローファイルを作成し、それを異なる複数の Azure Pipelines に関連付けます。

次のステップ

運用前環境で pull request を確認する

次の方法で共有

Azure Static Web Apps のビルド構成

ファイル名と場所

セキュリティ

[ビルド構成]

カスタムビルドコマンド

フロントエンドアプリのビルドをスキップする

API のビルドをスキップする

ビルドタイムアウトの延長

デプロイシークレットを使用せずにワークフローを実行する

環境変数

Monorepo のサポート

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Static Web Apps のビルド構成

ファイル名と場所

セキュリティ

[ビルド構成]

カスタム ビルド コマンド

フロントエンド アプリのビルドをスキップする

API のビルドをスキップする

ビルド タイムアウトの延長

デプロイ シークレットを使用せずにワークフローを実行する

環境変数

Monorepo のサポート

次のステップ

フィードバック

その他のリソース

カスタムビルドコマンド

フロントエンドアプリのビルドをスキップする

ビルドタイムアウトの延長

デプロイシークレットを使用せずにワークフローを実行する