Partage via

Configuration de build pour Azure Static Web Apps

  • Article

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.

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.

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.

Le travail Fermer la demande de tirage (pull request) fait partie du flux de travail GitHub Actions 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'

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

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

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 que votre flux de travail continue le traitement même si certains secrets sont manquants. Définissez la variable d’environnement SKIP_DEPLOY_ON_MISSING_SECRETS sur true pour configurer votre flux de travail à 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.

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

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