Konfigurace sestavení pro Azure Static Web Apps

  • Článek

Konfigurace sestavení Azure Static Web Apps používá GitHub Actions nebo Azure Pipelines. Každá lokalita má konfigurační soubor YAML, který řídí, jak je lokalita sestavená a nasazená. Tento článek vysvětluje strukturu a možnosti souboru.

Následující tabulka uvádí dostupná nastavení konfigurace.

Vlastnost Popis Povinní účastníci
app_location Tato složka obsahuje zdrojový kód pro front-endovou aplikaci. Hodnota je relativní vzhledem ke kořenovému adresáři úložiště na GitHubu a aktuální pracovní složce v Azure DevOps. Při použití skip_app_build: trues touto hodnotou je výstupní umístění sestavení aplikace. Ano
api_location Tato složka, která obsahuje zdrojový kód pro vaši aplikaci API. Hodnota je relativní vzhledem ke kořenovému adresáři úložiště na GitHubu a aktuální pracovní složce v Azure DevOps. Při použití skip_api_build: trues touto hodnotou je výstupní umístění sestavení rozhraní API. No
output_location Pokud vaše webová aplikace spustí krok sestavení, je výstupním umístěním složka, ve které se vygenerují veřejné soubory. U většiny projektů output_location je relativní vzhledem k app_location. U projektů .NET je však umístění relativní vzhledem k výstupní složce. No
app_build_command Pro Node.js aplikace můžete definovat vlastní příkaz pro sestavení aplikace statického obsahu.

Pokud chcete například nakonfigurovat produkční sestavení pro aplikaci Angular, vytvořte skript npm s názvem build-prod pro spuštění ng build --prod a zadejte npm run build-prod jako vlastní příkaz. Pokud je tento pracovní postup prázdný, pokusí se spustit npm run build příkazy nebo npm run build:azure příkazy.		 No
api_build_command Pro Node.js aplikace můžete definovat vlastní příkaz pro sestavení aplikace rozhraní API služby Azure Functions. No
skip_app_build Nastavte hodnotu tak, aby true se přeskočila sestavení front-endové aplikace. No
skip_api_build Nastavte hodnotu tak, aby true se přeskočí vytváření funkcí rozhraní API. No
cwd
(jenom Azure Pipelines)		 Absolutní cesta k pracovní složce Výchozí hodnota $(System.DefaultWorkingDirectory)je . No
build_timeout_in_minutes Nastavte tuto hodnotu tak, aby se přizpůsobil časový limit sestavení. Výchozí hodnota 15je . No

Pomocí těchto nastavení můžete nastavit GitHub Actions nebo Azure Pipelines tak, aby spouštěly kontinuální integraci a průběžné doručování (CI/CD) pro vaši statickou webovou aplikaci.

Název a umístění souboru

Akce GitHubu vygeneruje konfigurační soubor a je uložena ve složce .github/workflows s názvem pomocí následujícího formátu: azure-static-web-apps-<RANDOM_NAME>.yml

Ve výchozím nastavení je konfigurační soubor uložen v kořenovém adresáři úložiště s názvem azure-pipelines.yml.

Zabezpečení

Pro zabezpečení konfigurace sestavení si můžete vybrat mezi dvěma různými zásadami autorizace nasazení. Static Web Apps podporuje buď použití tokenu nasazení Azure (doporučeno), nebo přístupového tokenu GitHubu.

Pomocí následujících kroků nastavte zásady autorizace nasazení ve vaší aplikaci:

  • Nové aplikace: Když vytvoříte statickou webovou aplikaci, na kartě Konfigurace nasazení vyberte zásadu autorizace nasazení.

  • Existující aplikace: Pokud chcete aktualizovat existující aplikaci, přejděte do konfigurace nasazení konfigurace nastavení>>a vyberte zásady autorizace nasazení.

Konfigurace sestavení

Následující ukázková konfigurace monitoruje změny úložiště. Když se potvrzení nasdílí do main větve, aplikace se sestaví ze app_location složky a soubory v souboru, které output_location se obsluhují na veřejném webu. Kromě toho je aplikace ve složce api k dispozici v cestě webu 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)

V této konfiguraci:

  • Větev main se monitoruje pro potvrzení.
  • Odkazuje app_location na src složku, která obsahuje zdrojové soubory webové aplikace. Tato hodnota je relativní vzhledem k pracovnímu adresáři (cwd). Chcete-li jej nastavit na pracovní adresář, použijte /.
  • Odkazuje api_location na api složku, která obsahuje aplikaci Azure Functions pro koncové body rozhraní API webu. Tato hodnota je relativní vzhledem k pracovnímu adresáři (cwd). Chcete-li jej nastavit na pracovní adresář, použijte /.
  • Odkazuje output_location na public složku, která obsahuje konečnou verzi zdrojových souborů aplikace. Tato hodnota je relativní k app_location. U projektů .NET je umístění relativní vzhledem k výstupní složce.
  • Jedná se cwd o absolutní cestu odkazující na pracovní adresář. Výchozí hodnota je $(System.DefaultWorkingDirectory).
  • $(deployment_token) Proměnná odkazuje na vygenerovaný token nasazení Azure DevOps.

Poznámka:

app_locationa api_location musí být relativní k pracovnímu adresáři (cwd) a musí být podadresářem .cwd

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"

V této konfiguraci:

  • Větev main se monitoruje pro potvrzení.
  • Pracovní postup GitHub Actions se aktivuje , když je žádost o přijetí změn ve main větvi otevřená, synchronizovaná, znovu otevřená nebo uzavřená.
  • Spustí se build_and_deploy_job , když nasdílíte potvrzení nebo otevřete žádost o přijetí změn ve větvi uvedené ve on vlastnosti.
  • Odkazuje app_location na src složku, která obsahuje zdrojové soubory webové aplikace. Pokud chcete tuto hodnotu nastavit na kořen úložiště, použijte /.
  • Odkazuje api_location na api složku, která obsahuje aplikaci Azure Functions pro koncové body rozhraní API webu. Pokud chcete tuto hodnotu nastavit na kořen úložiště, použijte /.
  • Odkazuje output_location na public složku, která obsahuje konečnou verzi zdrojových souborů aplikace. Je to relativní vzhledem k app_location. U projektů .NET je umístění relativní vzhledem k výstupní složce publikování.

Neměňte hodnoty pro repo_token, actiona azure_static_web_apps_api_token protože jsou nastavené pro vás službou Azure Static Web Apps.

Úloha Zavřít žádost o přijetí změn automaticky zavře žádost o přijetí změn, která aktivovala sestavení a nasazení. Tato volitelná úloha není nutná, aby proces fungoval.

Po otevření žádosti o přijetí změn se akce GitHubu Azure Static Web Apps sestaví a nasadí aplikaci do přípravného prostředí. Potom úloha Zavřít žádost o přijetí změn zkontroluje, jestli je žádost o přijetí změn stále otevřená, a zavře ji zprávou o dokončení.

Tato úloha pomáhá udržovat pracovní postup žádosti o přijetí změn uspořádaný a zabraňuje zastaralým žádostem o přijetí změn. Modul runtime automaticky zavře žádost o přijetí změn, vaše úložiště zůstane aktuální a váš tým bude upozorněn na stav.

Úloha Zavřít žádost o přijetí změn je součástí pracovního postupu Azure Static Web Apps GitHub Actions a po sloučení žádost o přijetí změn zavře. Akce Azure/static-web-apps-deploy nasadí aplikaci do Azure Static Web Apps, která vyžaduje azure_static_web_apps_api_token ověření.

Vlastní příkazy sestavení

U Node.js aplikací můžete jemně odstupňovanou kontrolu nad tím, jaké příkazy se spouštějí během procesu sestavení aplikace nebo rozhraní API. Následující příklad ukazuje, jak definovat sestavení s hodnotami pro app_build_command a api_build_command.

Poznámka:

V současné době můžete definovat app_build_command pouze sestavení Node.js.api_build_command Pokud chcete zadat Node.js verzi, použijte engines pole v package.json souboru.

...

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)

Přeskočit vytváření front-endové aplikace

Pokud potřebujete úplnou kontrolu nad sestavením pro front-endovou aplikaci, můžete obejít automatické sestavení a nasadit aplikaci integrovanou v předchozím kroku.

Pokud chcete přeskočit vytváření front-endové aplikace:

  • Nastavte app_location umístění souborů, které chcete nasadit.
  • Nastavte skip_app_build na hodnotu true.
  • Nastaví output_location se na prázdný řetězec ('').

Poznámka:

Ujistěte se, že jste soubor staticwebapp.config.json zkopírovali i do výstupního adresáře.

...

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)

Přeskočení vytváření rozhraní API

Pokud chcete přeskočit sestavování rozhraní API, můžete obejít automatické sestavení a nasadit rozhraní API vytvořené v předchozím kroku.

Postup pro přeskočení sestavení rozhraní API:

  • V souboru staticwebapp.config.json nastavte apiRuntime správný modul runtime a verzi. Seznam podporovaných modulů runtime a verzí najdete v tématu Konfigurace Azure Static Web Apps .

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

  • Nastavte skip_api_build na hodnotu true.

  • Nastavte api_location složku obsahující vytvořenou aplikaci API, která se má nasadit. Tato cesta je relativní vzhledem ke kořenovému adresáři úložiště v GitHub Actions a cwd v 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)

Prodloužení časového limitu sestavení

Ve výchozím nastavení jsou buildy aplikací a rozhraní API omezené na 15 minut. Časový limit sestavení můžete prodloužit nastavením build_timeout_in_minutes vlastnosti.

...

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)

Spuštění pracovního postupu bez tajných kódů nasazení

Někdy potřebujete, aby pracovní postup pokračoval v procesu i v případě, že chybí některé tajné kódy. Pokud chcete nakonfigurovat pracovní postup tak, aby pokračoval bez definovaných tajných kódů, nastavte proměnnou SKIP_DEPLOY_ON_MISSING_SECRETS prostředí na truehodnotu .

Pokud je tato funkce povolená, umožňuje pracovnímu postupu pokračovat bez nasazení obsahu webu.

...

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

Proměnné prostředí

Proměnné prostředí pro sestavení můžete nastavit prostřednictvím env části konfigurace úlohy.

Další informace o proměnných prostředí používaných nástrojem Oryx naleznete v tématu Konfigurace 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

Podpora monorepo

Monorepo je úložiště, které obsahuje kód pro více než jednu aplikaci. Ve výchozím nastavení pracovní postup sleduje všechny soubory v úložišti, ale konfiguraci můžete upravit tak, aby cílila na jednu aplikaci.

Pokud chcete soubor pracovního postupu cílit na jednu aplikaci, zadáte cesty v push částech.pull_request

Když nastavíte monorepo, každá konfigurace statické aplikace je vymezená jenom na soubory pro jednu aplikaci. Různé soubory pracovního postupu jsou vedle sebe ve složce .github/workflows úložiště.

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

Následující příklad ukazuje, jak přidat paths uzel do push oddílů pull_request souboru s názvem 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

V tomto příkladu aktivují nové sestavení pouze změny provedené v následujících souborech:

  • Všechny soubory ve složce app1
  • Všechny soubory ve složce api1
  • Změny souboru pracovního postupu azure-static-web-apps-purple-pond.yml aplikace

Pokud chcete podporovat více než jednu aplikaci v jednom úložišti, vytvořte samostatný soubor pracovního postupu a přidružte ho k různým kanálům Azure Pipelines.

Další kroky

Kontrola žádostí o přijetí změn v předprodukčním prostředí