Skapa konfiguration för Azure Static Web Apps

Azure Static Web Apps-byggkonfigurationen använder antingen GitHub Actions eller Azure Pipelines. Varje plats har en YAML-konfigurationsfil som styr hur en plats skapas och distribueras. I den här artikeln beskrivs filens struktur och alternativ.

I följande tabell visas de tillgängliga konfigurationsinställningarna.

Property	Beskrivning	Obligatoriskt
app_location	Den här mappen innehåller källkoden för klientdelsprogrammet. Värdet är relativt lagringsplatsens rot i GitHub och den aktuella arbetsmappen i Azure DevOps. När det används med skip_app_build: trueär det här värdet appens byggutdataplats.	Ja
api_location	Den här mappen som innehåller källkoden för ditt API-program. Värdet är relativt lagringsplatsens rot i GitHub och den aktuella arbetsmappen i Azure DevOps. När det används med skip_api_build: trueär det här värdet API:ets byggutdataplats.	Nej
output_location	Om webbappen kör ett byggsteg är utdataplatsen den mapp där de offentliga filerna genereras. För de flesta projekt output_location är i förhållande till app_location. För .NET-projekt är platsen dock relativ till utdatamappen.	Nej
app_build_command	För Node.js program kan du definiera ett anpassat kommando för att skapa det statiska innehållsprogrammet. Om du till exempel vill konfigurera en produktionsversion för ett Angular-program skapar du ett npm-skript med namnet build-prod för att köra ng build --prod och ange npm run build-prod som anpassat kommando. Om det lämnas tomt försöker arbetsflödet köra kommandona npm run build eller npm run build:azure .	Nej
api_build_command	För Node.js program kan du definiera ett anpassat kommando för att skapa Azure Functions API-programmet.	Nej
skip_app_build	Ange värdet till true för att hoppa över att skapa klientdelsappen.	Nej
skip_api_build	Ange värdet till true för att hoppa över att skapa API-funktionerna.	Nej
cwd (Endast Azure Pipelines)	Absolut sökväg till arbetsmappen. Standardvärdet är $(System.DefaultWorkingDirectory).	Nej
build_timeout_in_minutes	Ange det här värdet för att anpassa tidsgränsen för bygget. Standardvärdet är 15.	Nej

Med de här inställningarna kan du konfigurera GitHub Actions eller Azure Pipelines för att köra kontinuerlig integrering/kontinuerlig leverans (CI/CD) för din statiska webbapp.

Filnamn och plats

GitHub-åtgärden genererar konfigurationsfilen och lagras i mappen .github/workflows med följande format: azure-static-web-apps-<RANDOM_NAME>.yml.

Som standard lagras konfigurationsfilen i roten på lagringsplatsen med namnet azure-pipelines.yml.

Säkerhet

Du kan välja mellan två olika principer för distributionsauktorisering för att skydda byggkonfigurationen. Static Web Apps stöder antingen användning av en Azure-distributionstoken (rekommenderas) eller en GitHub-åtkomsttoken.

Använd följande steg för att ange principen för distributionsauktorisering i din app:

• Nya appar: När du skapar din statiska webbapp väljer du auktoriseringsprincipen Distribution på fliken Distributionskonfiguration.

• Befintliga appar: Om du vill uppdatera en befintlig app går du till Konfigurationskonfigurationskonfiguration för inställningar>>och gör ett val för auktoriseringsprincipen för distribution.

Skapa konfiguration

Följande exempelkonfiguration övervakar lagringsplatsen för ändringar. När incheckningar skickas till grenen main skapas programmet från app_location mappen och filerna i output_location hanteras på den offentliga webben. Dessutom är programmet i api-mappen tillgängligt under webbplatsens api sökväg.

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)

I den här konfigurationen:

• Grenen main övervakas för incheckningar.
• Pekar app_location på mappen src som innehåller källfilerna för webbappen. Det här värdet är relativt arbetskatalogen (cwd). Om du vill ange den till arbetskatalogen använder du /.
• Pekar api_location på mappen api som innehåller Azure Functions-programmet för webbplatsens API-slutpunkter. Det här värdet är relativt arbetskatalogen (cwd). Om du vill ange den till arbetskatalogen använder du /.
• Pekar output_location på mappen public som innehåller den slutliga versionen av appens källfiler. Det här värdet är relativt till app_location. För .NET-projekt är platsen relativ till utdatamappen.
• cwd är en absolut sökväg som pekar på arbetskatalogen. Standardvärdet är $(System.DefaultWorkingDirectory).
• Variabeln $(deployment_token) pekar på den genererade Azure DevOps-distributionstoken.

Kommentar

app_location och api_location måste vara i förhållande till arbetskatalogen (cwd) och de måste vara underkataloger under cwd.

Azure-distributionstoken

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"

GitHub-åtkomsttoken

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"

I den här konfigurationen:

• Grenen main övervakas för incheckningar.
• Ett GitHub Actions-arbetsflöde utlöses när en pull-begäran på grenen main öppnas, synkroniseras, öppnas igen eller stängs.
• Körs build_and_deploy_job när du push-överför incheckningar eller öppnar en pull-begäran mot grenen som anges i on egenskapen.
• Pekar app_location på mappen src som innehåller källfilerna för webbappen. Om du vill ange det här värdet till lagringsplatsens rot använder du /.
• Pekar api_location på mappen api som innehåller Azure Functions-programmet för webbplatsens API-slutpunkter. Om du vill ange det här värdet till lagringsplatsens rot använder du /.
• Pekar output_location på mappen public som innehåller den slutliga versionen av appens källfiler. Den är relativ till app_location. För .NET-projekt är platsen relativ till mappen publicera utdata.

Ändra inte värdena för repo_token, actionoch azure_static_web_apps_api_token som de har angetts för dig av Azure Static Web Apps.

Jobbet Stäng pull-begäran stänger automatiskt pull-begäran som utlöste bygget och distributionen. Det här valfria jobbet krävs inte för att processen ska fungera.

När en pull-begäran öppnas skapar och distribuerar Azure Static Web Apps GitHub Action appen till en mellanlagringsmiljö. Därefter kontrollerar jobbet Stäng pull-begäran om pull-begäran fortfarande är öppen och stänger den med ett slutförandemeddelande.

Det här jobbet hjälper dig att hålla arbetsflödet för pull-begäran ordnat och förhindrar inaktuella pull-begäranden. När körningen automatiskt stänger pull-begäran förblir lagringsplatsen uppdaterad och ditt team meddelas om statusen.

Jobbet Stäng pull-begäran är en del av GitHub Actions-arbetsflödet för Azure Static Web Apps och stänger pull-begäran när den har slagits samman. Åtgärden Azure/static-web-apps-deploy distribuerar appen till Azure Static Web Apps, vilket kräver azure_static_web_apps_api_token autentisering.

Anpassade build-kommandon

För Node.js program kan du ta detaljerad kontroll över vilka kommandon som körs under app- eller API-byggprocessen. I följande exempel visas hur du definierar build med värden för app_build_command och api_build_command.

Kommentar

För närvarande kan du bara definiera app_build_command och api_build_command för Node.js versioner. Om du vill ange Node.js version använder du fältet engines i package.json filen.

...

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)

Hoppa över att skapa klientdelsapp

Om du behöver fullständig kontroll över bygget för klientdelsappen kan du kringgå den automatiska versionen och distribuera appen som skapades i ett tidigare steg.

Så här hoppar du över att skapa klientdelsappen:

• Ange app_location den plats som filerna du vill distribuera.
• Ställ in skip_app_build på true.
• Ange output_location till en tom sträng ('').

Kommentar

Kontrollera att du har kopierat filen staticwebapp.config.json till utdatakatalogen.

...

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)

Hoppa över att skapa API:et

Om du vill hoppa över att skapa API:et kan du kringgå den automatiska versionen och distribuera API:et som skapades i ett tidigare steg.

Steg för att hoppa över att skapa API:et:

• I filen staticwebapp.config.json anger du apiRuntime till rätt körning och version. Se Konfigurera Azure Static Web Apps för listan över körnings- och versioner som stöds.

  {
    "platform": {
      "apiRuntime": "node:16"
    }
  }
  

• Ställ in skip_api_build på true.

• Ange api_location till den mapp som innehåller den skapade API-appen som ska distribueras. Den här sökvägen är relativ till lagringsplatsens rot i GitHub Actions och cwd i 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)

Utöka tidsgränsen för bygge

Som standard är app- och API-versionerna begränsade till 15 minuter. Du kan utöka tidsgränsen för bygget genom att ange egenskapen 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)

Köra arbetsflöde utan distributionshemligheter

Ibland behöver du arbetsflödet för att fortsätta bearbeta även när vissa hemligheter saknas. Om du vill konfigurera arbetsflödet så att det fortsätter utan definierade hemligheter anger du SKIP_DEPLOY_ON_MISSING_SECRETS miljövariabeln till true.

När den här funktionen är aktiverad kan arbetsflödet fortsätta utan att distribuera webbplatsens innehåll.

...

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

Miljövariabler

Du kan ange miljövariabler för din version via env avsnittet i ett jobbs konfiguration.

Mer information om de miljövariabler som används av Oryx finns i Oryx-konfiguration.

...

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

Stöd för monorepo

En monorepo är en lagringsplats som innehåller kod för mer än ett program. Som standard spårar arbetsflödet alla filer på en lagringsplats, men du kan justera konfigurationen så att den riktar sig mot en enda app.

Om du vill rikta en arbetsflödesfil till en enda app anger du sökvägar i avsnitten push och pull_request .

När du konfigurerar en monorepo begränsas varje konfiguration av statiska appar endast till filer för en enda app. De olika arbetsflödesfilerna finns sida vid sida i lagringsplatsens .github/workflows-mapp .

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

I följande exempel visas hur du lägger till en paths nod i avsnitten push och pull_request i en fil med namnet 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

I det här exemplet utlöser endast ändringar som görs i följande filer en ny version:

• Alla filer i app1-mappen
• Alla filer i mappen api1
• Ändringar i appens azure-static-web-apps-purple-pond.yml arbetsflödesfil

Om du vill ha stöd för fler än ett program på en enda lagringsplats skapar du en separat arbetsflödesfil och associerar den med olika Azure Pipelines.

Nästa steg

Granska pull-begäranden i förproduktionsmiljöer