Configuration de build pour Azure Static Web Apps

Article
11/06/2024

La configuration de build Azure Static Web Apps utilise GitHub Actions ou Azure Pipelines. Chaque site dispose d’un fichier de configuration YAML qui contrôle le mode de génération et de déploiement d’un site. Cet article explique la structure et les options de ce fichier.

Le tableau suivant répertorie les paramètres de configuration disponibles.

Propriété	Description	Obligatoire
`app_location`	Ce dossier contient le code source pour votre application frontale. La valeur est relative par rapport à la racine du dépôt dans GitHub et au dossier de travail actuel dans Azure DevOps. Quand elle est utilisée avec `skip_app_build: true`, cette valeur est l’emplacement de sortie de génération de l’application.	Oui
`api_location`	Ce dossier contenant le code source pour votre application d’API. La valeur est relative par rapport à la racine du dépôt dans GitHub et au dossier de travail actuel dans Azure DevOps. Quand elle est utilisée avec `skip_api_build: true`, cette valeur est l’emplacement de sortie de génération de l’API.	Non
`output_location`	Si votre application web exécute une étape de génération, l’emplacement de sortie est le dossier dans lequel les fichiers publics sont générés. Pour la plupart des projets, `output_location` est relatif par rapport à `app_location`. En revanche, pour les projets .NET, l’emplacement est relatif au dossier de sortie.	Non
`app_build_command`	Pour les applications Node.js, vous pouvez définir une commande personnalisée pour générer l’application de contenu statique. Par exemple, pour configurer une build de production pour une application Angular, créez un script NPM nommé `build-prod` pour exécuter `ng build --prod` et entrez `npm run build-prod` comme commande personnalisée. Si elle n’est pas renseignée, le flux de travail tente d’exécuter les commandes `npm run build` ou `npm run build:azure`.	Non
`api_build_command`	Pour les applications Node.js, vous pouvez définir une commande personnalisée pour générer l’application d’API Azure Functions.	Non
`skip_app_build`	Affectez la valeur `true` pour ignorer la génération de l’application front-end.	Non
`skip_api_build`	Définissez la valeur sur `true` pour ignorer la génération des fonctions API.	Non
`cwd` (Azure Pipelines uniquement)	Chemin d’accès absolu au dossier de travail. La valeur par défaut est `$(System.DefaultWorkingDirectory)`.	Non
`build_timeout_in_minutes`	Définissez cette valeur pour personnaliser le délai d’expiration de la génération. La valeur par défaut est `15`.	Non

Avec ces paramètres, vous pouvez configurer des GitHub Actions ou Azure Pipelines pour exécuter l’intégration continue/la livraison continue (CI/CD) pour votre application web statique.

Nom du fichier et emplacement

L’action GitHub génère le fichier config et est stocké dans le dossier .github/workflows, nommé en utilisant le format suivant : azure-static-web-apps-<RANDOM_NAME>.yml.

Par défaut, le fichier de configuration est stocké à la racine de votre dépôt, sous le nom azure-pipelines.yml.

Sécurité

Vous pouvez choisir entre deux stratégies d’autorisation de déploiement différentes pour sécuriser la configuration de votre build. Static Web Apps prend en charge l’utilisation d’un jeton de déploiement Azure (recommandé) ou d’un jeton d’accès GitHub.

Pour définir la stratégie d’autorisation de déploiement dans votre application, procédez comme suit :

Nouvelles applications : lors de la création de votre application web statique, sous l’onglet Configuration du déploiement, effectuez une sélection pour la stratégie d’autorisation de déploiement.
Applications existantes : pour mettre à jour une application existante, accédez à Paramètres>Configuration>Configuration du déploiement, puis effectuez une sélection pour la stratégie d’autorisation de déploiement.

Configuration de build

L’exemple de configuration suivant surveille les modifications du dépôt. Les validations étant envoyées à la branche main, l’application est générée à partir du dossier app_location et les fichiers dans output_location sont servis au web public. En outre, l’application dans le dossier api est disponible dans le chemin d’accès api du site.

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)

Dans cette configuration :

La branche main est surveillée pour les validations.
app_location pointe vers le dossier src contenant les fichiers sources pour l’application web. Cette valeur est relative au répertoire de travail (cwd). Pour la définir dans le répertoire de travail, utilisez /.
api_location pointe vers le dossier apicontenant l’application Azure Functions pour les points de terminaison d’API du site. Cette valeur est relative au répertoire de travail (cwd). Pour la définir dans le répertoire de travail, utilisez /.
output_location pointe vers le dossier public contenant la version finale des fichiers sources de l’application. Cette valeur est relative à app_location. Pour les projets .NET, l’emplacement est relatif au dossier de sortie.
cwd est un chemin d’accès absolu qui pointe vers le répertoire de travail. Sa valeur par défaut est $(System.DefaultWorkingDirectory).
La variable $(deployment_token) pointe vers le jeton de déploiement Azure DevOps généré.

Remarque

app_location et api_location doivent être relatifs au répertoire de travail (cwd) et doivent être des sous-répertoires sous cwd.

Jeton de déploiement Azure
Jeton d’accès 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"

Dans cette configuration :

La branche main est surveillée pour les validations.
Un flux de travail GitHub Actions est déclenché quand une demande de tirage (pull request) sur la branche main est ouverte, synchronisée, rouverte ou fermée.
La commande build_and_deploy_job s’exécute quand vous envoyez des validations ou ouvrez une demande de tirage (pull request) sur la branche indiquée dans la propriété on.
app_location pointe vers le dossier src contenant les fichiers sources pour l’application web. Pour définir cette valeur sur la racine du référentiel, utilisez /.
api_location pointe vers le dossier apicontenant l’application Azure Functions pour les points de terminaison d’API du site. Pour définir cette valeur sur la racine du référentiel, utilisez /.
output_location pointe vers le dossier public contenant la version finale des fichiers sources de l’application. Il est relatif à app_location. Pour les projets .NET, l’emplacement est relatif au dossier de sortie de la publication.

Ne modifiez pas les valeurs de repo_token, action et azure_static_web_apps_api_token, car elles sont définies pour vous par Azure Static Web Apps.

Le travail Fermer la demande de tirage (pull request) ferme automatiquement la demande de tirage qui a déclenché la génération et le déploiement. Ce travail facultatif n’est pas nécessaire pour que le processus fonctionne.

Lorsqu’une demande de tirage (pull request) est ouverte, Azure Static Web Apps GitHub Actions génère et déploie l’application dans un environnement intermédiaire. Ensuite, le travail Fermer la demande de tirage (pull request) vérifie si la demande de tirage est toujours ouverte et la ferme avec un message d’achèvement.

Ce travail permet de conserver votre flux de travail de demande de tirage organisé et empêche les demandes de tirage obsolètes. Le runtime fermant automatiquement la demande de tirage, votre référentiel reste à jour et votre équipe est avertie de l’état.

La tâche Fermer la demande de tirage (pull request) fait partie du flux de travail GitHub Actions d’Azure Static Web Apps, fermant la demande de tirage une fois celle-ci fusionnée. L’action Azure/static-web-apps-deploy déploie l’application sur Azure Static Web Apps, nécessitant azure_static_web_apps_api_token pour l’authentification.

Commandes de compilation personnalisées

Pour les applications Node.js, vous pouvez contrôler avec précision les commandes exécutées pendant le processus de génération d’une application ou d’une API. L’exemple suivant montre comment définir la génération avec des valeurs pour app_build_command et api_build_command.

Remarque

Actuellement, vous pouvez uniquement définir app_build_command et api_build_command pour les builds Node.js. Pour spécifier la version Node.js, utilisez le champ engines dans le fichier package.json.

...

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)

Ignorer la génération de l’application frontale

Si vous avez besoin d’un contrôle total de la génération pour votre application frontale, vous pouvez contourner la génération automatique et déployer l’application générée à l’étape précédente.

Pour ignorer la génération de l’application frontale :

Définissez app_location sur l’emplacement des fichiers que vous souhaitez déployer.
Affectez la valeur skip_app_build à true.
Définissez output_location sur une chaîne vide ('').

Remarque

Assurez-vous que votre fichier staticwebapp.config.json est copié également dans le répertoire output.

...

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)

Ignorer la génération de l’API

Si vous souhaitez ignorer la génération de l’API, vous pouvez contourner la génération automatique et déployer l’API générée à l’étape précédente.

Étapes à suivre pour ignorer la création de l’API :

Dans le fichier staticwebapp.config.json, définissez apiRuntime sur le runtime et la version appropriés. Reportez-vous à Configurer Azure Static Web Apps pour obtenir la liste des runtimes et des versions pris en charge.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Affectez la valeur skip_api_build à true.
Définissez api_location sur le dossier contenant l’application API générée à déployer. Ce chemin est relatif à la racine du dépôt dans GitHub Actions et cwd dans Azure Pipelines.

...

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)

Prolonger le délai d’attente de la génération

Par défaut, les générations d’application et d’API sont limitées à 15 minutes. Vous pouvez prolonger le délai d’attente de la génération en définissant la propriété 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)

Exécuter un flux de travail sans secrets de déploiement

Parfois, vous avez besoin que votre flux de travail continue le traitement même si certains secrets sont manquants. Pour configurer votre flux de travail de façon à ce qu’il s’exécute sans secrets définis, définissez la variable d’environnement SKIP_DEPLOY_ON_MISSING_SECRETS sur true.

Lorsqu’elle est activée, cette fonctionnalité permet au flux de travail de continuer sans déployer le contenu du site.

...

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

Variables d'environnement

Vous pouvez définir des variables d’environnement pour votre build via la section env de la configuration d’un travail.

Pour plus d’informations sur les variables d’environnement utilisées par Oryx, consultez Configuration 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

Prise en charge de référentiel unique

Un référentiel unique est un référentiel qui contient du code pour plusieurs applications. Par défaut, le flux de travail suit tous les fichiers d’un référentiel, mais vous pouvez ajuster la configuration pour cibler une seule application.

Pour cibler un fichier de flux de travail sur une seule application, vous spécifiez les chemins d’accès dans les sections push et pull_request.

Lorsque vous configurez un référentiel unique, chaque application statique ne cible que les fichiers d’une seule application. Les différents fichiers de flux de travail sont placés côte à côte dans le dossier .github/workflows du référentiel.

├── .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

L’exemple suivant montre comment ajouter un nœud paths aux sections push et pull_request d’un fichier nommé azure-static-web-apps-purple-pond.yml.

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

Dans cet exemple, seules les modifications apportées aux fichiers suivants déclenchent une nouvelle génération :

Tous les fichiers contenus dans le dossier app1
Tous les fichiers contenus dans le dossier api1
Modifications apportées au fichier de flux de travail azure-static-web-apps-purple-pond.yml de l’application

Pour prendre en charge plusieurs applications dans un seul dépôt, créez un fichier de flux de travail distinct et associez-le à des pipelines Azure différents.

Étapes suivantes

Passer en revue les demandes de tirage (pull request) dans les environnements de préproduction

Partage via

Configuration de build pour Azure Static Web Apps

Nom du fichier et emplacement

Sécurité

Configuration de build

Commandes de compilation personnalisées

Ignorer la génération de l’application frontale

Ignorer la génération de l’API

Prolonger le délai d’attente de la génération

Exécuter un flux de travail sans secrets de déploiement

Variables d'environnement

Prise en charge de référentiel unique

Étapes suivantes

Commentaires

Ressources supplémentaires