Configuration de build pour Azure Static Web Apps

  • Article

La configuration de build Azure Static Web Apps est optimisée par 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 par rapport au dossier de sortie de publication. 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 et emplacement du fichier

Le fichier de configuration est généré par GitHub et stocké dans le dossier github/workflows, nommé en utilisant le format suivant : azure-static-web-apps-<RANDOM_NAME>.yml.

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.

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.

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'

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.
  • Définissez skip_app_build sur 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

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"
  }
}
  • Définissez skip_api_build sur 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

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

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

Parfois, vous avez besoin de votre flux de travail pour continuer à traiter même quand certains secrets sont manquants. Définissez la variable d’environnement SKIP_DEPLOY_ON_MISSING_SECRETS pour true configurer votre flux de travail pour continuer sans secrets définis.

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

Variables d'environnement

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

...

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

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

Étapes suivantes

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