Конфигурация сборки для Статические веб-приложения Azure

Статья
11/05/2024

Конфигурация сборки Статические веб-приложения Azure использует GitHub Actions или Azure Pipelines. У каждого сайта есть файл конфигурации YAML, который управляет тем, как создается и развертывается сайт. В этой статье описываются структура и параметры этого файла.

В следующей таблице перечислены доступные параметры конфигурации.

Свойство	Описание:	Обязательное поле
`app_location`	Эта папка содержит исходный код для внешнего приложения. Это значение относится к корневому каталогу репозитория в GitHub и текущей рабочей папке в Azure DevOps. При использовании с `skip_app_build: true`этим значением является расположение выходных данных сборки приложения.	Да
`api_location`	Эта папка, содержащая исходный код для приложения API. Это значение относится к корневому каталогу репозитория в GitHub и текущей рабочей папке в Azure DevOps. При использовании с `skip_api_build: true`этим значением является выходное расположение сборки API.	No
`output_location`	Если веб-приложение запускает шаг сборки, выходное расположение — это папка, в которой создаются общедоступные файлы. Для большинства проектов `output_location` относительно `app_location`. Однако для проектов .NET расположение относительно выходной папки.	No
`app_build_command`	Для приложений Node.js можно определить пользовательскую команду для создания приложения статического содержимого. Например, чтобы настроить рабочую сборку для приложения Angular, создайте скрипт npm с именем `build-prod`, который запускает `ng build --prod`, и введите настраиваемую команду `npm run build-prod`. Если оставить это поле пустым, рабочий процесс попытается выполнить команды `npm run build` или `npm run build:azure`.	No
`api_build_command`	Для приложений Node.js можно определить пользовательскую команду для создания приложения API Функции Azure.	No
`skip_app_build`	Установите значение `true`, чтобы пропустить сборку интерфейсного приложения.	No
`skip_api_build`	Задайте значение, чтобы `true` пропустить сборку функций API.	No
`cwd` (Только Azure Pipelines)	Абсолютный путь к рабочей папке. По умолчанию — `$(System.DefaultWorkingDirectory)`.	No
`build_timeout_in_minutes`	Задайте это значение, чтобы настроить время ожидания сборки. По умолчанию — `15`.	No

С помощью этих параметров можно настроить GitHub Actions или Azure Pipelines для выполнения непрерывной интеграции и непрерывной доставки (CI/CD) для статического веб-приложения.

Имя файла и расположение

Действие GitHub создает файл конфигурации и хранится в папке github/workflows с именем следующего формата: azure-static-web-apps-<RANDOM_NAME>.yml

По умолчанию файл конфигурации хранится в корне репозитория с именем azure-pipelines.yml.

Безопасность

Вы можете выбрать между двумя различными политиками авторизации развертывания для защиты конфигурации сборки. Статические веб-приложения поддерживает использование маркера развертывания Azure (рекомендуется) или маркера доступа GitHub.

Чтобы настроить политику авторизации развертывания в приложении, выполните следующие действия.

Новые приложения: при создании статического веб-приложения на вкладке "Конфигурация развертывания" выберите политику авторизации развертывания.
Существующие приложения. Чтобы обновить существующее приложение, перейдите к конфигурации развертывания конфигурации> параметров>и выберите политику авторизации развертывания.

Конфигурация построения

В следующем примере конфигурации отслеживается репозиторий для изменений. При отправке main фиксаций в ветвь приложение создается из app_location папки и файлов в интернете output_location . Кроме того, приложение в папке API доступно по пути сайта 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)

В этой конфигурации:

Ветвь main отслеживается для фиксаций.
Указывает app_location на src папку, содержащую исходные файлы для веб-приложения. Это значение относительно рабочего каталога (cwd). Чтобы установить его в рабочий каталог, используйте /.
Указывает api_location на api папку, содержащую приложение Функции Azure для конечных точек API сайта. Это значение относительно рабочего каталога (cwd). Чтобы установить его в рабочий каталог, используйте /.
Указывает output_location на public папку, содержащую окончательную версию исходных файлов приложения. Это значение относительно app_location. Для проектов .NET расположение относится к выходной папке.
Абсолютный cwd путь, указывающий на рабочий каталог. По умолчанию имеет значение $(System.DefaultWorkingDirectory).
Переменная $(deployment_token) указывает на созданный маркер развертывания Azure DevOps.

Примечание.

app_locationи api_location должен быть относительным к рабочему каталогу (cwd) и они должны быть подкаталогами.cwd

Маркер развертывания Azure
Маркер доступа 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"

В этой конфигурации:

Ветвь main отслеживается для фиксаций.
Рабочий процесс GitHub Actions активируется при запросе на вытягивание в main ветви: открытый, синхронизированный, вновь открытый или закрытый.
Выполняется build_and_deploy_job при отправке фиксаций или открытии запроса на вытягивание в ветви, указанной в свойстве on .
Указывает app_location на src папку, содержащую исходные файлы для веб-приложения. Чтобы задать это значение корневому каталогу репозитория, используйте /.
Указывает api_location на api папку, содержащую приложение Функции Azure для конечных точек API сайта. Чтобы задать это значение корневому каталогу репозитория, используйте /.
Указывает output_location на public папку, содержащую окончательную версию исходных файлов приложения. Это относительно app_location. Для проектов .NET расположение относится к папке выходных данных публикации.

Не изменяйте значения для repo_token, actionи azure_static_web_apps_api_token по мере их установки Статические веб-приложения Azure.

Задание "Закрыть запрос на вытягивание" автоматически закрывает запрос на вытягивание, активировав сборку и развертывание. Это необязательное задание не требуется для работы процесса.

При открытии запроса на вытягивание Статические веб-приложения Azure GitHub Action создает и развертывает приложение в промежуточной среде. После этого задание "Закрыть запрос на вытягивание" проверяет, открыт ли запрос на вытягивание и закрывает его с сообщением о завершении.

Это задание помогает организовать рабочий процесс запроса на вытягивание и предотвратить устаревшие запросы на вытягивание. При автоматическом закрытии запроса на вытягивание репозиторий обновляется, и ваша команда уведомляет о состоянии.

Задание "Закрыть запрос на вытягивание" является частью рабочего процесса Статические веб-приложения Azure GitHub Actions, закрывая запрос на вытягивание после объединения. Действие Azure/static-web-apps-deploy развертывает приложение в Статические веб-приложения Azure, требуя azure_static_web_apps_api_token проверки подлинности.

Команды настраиваемой сборки

Для приложений Node.js можно точно контролировать выполнение команд во время сборки приложения или API. В следующем примере показано, как определить сборку со значениями и app_build_command api_build_command.

Примечание.

В настоящее время можно определить app_build_command только Node.js api_build_command сборки. Чтобы указать версию Node.js, используйте engines поле в 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)

Пропуск сборки внешнего приложения

Если вам нужен полный контроль над сборкой для внешнего приложения, можно обойти автоматическую сборку и развернуть приложение, встроенное на предыдущем шаге.

Чтобы пропустить сборку интерфейсного приложения, выполните следующие действия.

Задайте app_location расположение файлов, которые требуется развернуть.
Задайте для параметра skip_app_build значение true.
Задайте output_location для пустой строки ('').

Примечание.

Убедитесь, что вы staticwebapp.config.json скопировали файл, а также в выходной каталог.

...

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)

Пропустить сборку API

Если вы хотите пропустить сборку API, можно обойти автоматическую сборку и развернуть API, встроенный на предыдущем шаге.

Чтобы пропустить сборку API, выполните следующие действия.

В файле staticwebapp.config.json задайте apiRuntime правильную среду выполнения и версию. Сведения о настройке Статические веб-приложения Azure для списка поддерживаемых сред выполнения и версий.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Задайте для параметра skip_api_build значение true.
Задайте папку api_location , содержащую встроенное приложение API для развертывания. Этот путь относительно корневого каталога репозитория в GitHub Actions и cwd в 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)

Расширение времени ожидания сборки

По умолчанию сборки приложения и API ограничены 15 минутами. Вы можете продлить время ожидания сборки 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)

Запуск рабочего процесса без секретов развертывания

Иногда вам нужно, чтобы рабочий процесс продолжал обрабатываться, даже если отсутствуют некоторые секреты. Чтобы настроить рабочий процесс для продолжения без определенных секретов, задайте для переменной SKIP_DEPLOY_ON_MISSING_SECRETS среды значение true.

При включении эта функция позволяет рабочему процессу продолжать работу без развертывания содержимого сайта.

...

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

Переменные среды

Вы можете задать переменные среды для сборки, используя раздел env в конфигурации задания.

Дополнительные сведения о переменных среды, используемых Oryx, см. в разделе "Конфигурация 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

Поддержка единого репозитория

Единым называется репозиторий, который содержит код для нескольких приложений. По умолчанию в файле рабочего процесса отслеживаются все файлы в репозитории, но его можно настроить отдельно для конкретного приложения.

Чтобы назначить файл рабочего процесса для одного приложения, нужно указать пути в разделах push и pull_request.

При настройке monorepo каждая статическая конфигурация приложения ограничена только файлами для одного приложения. Разные файлы рабочих процессов находятся в папке . GitHub/Workflows репозитория одновременно.

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

В следующем примере показано, как добавить узел paths в разделы push и pull_request файла с именем 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

В этом примере только изменения, внесенные в следующие файлы, активируют новую сборку:

все файлы в папке app1;
все файлы в папке api1.
Изменения в файле рабочего процесса azure-static-web-apps-purple-pond.yml для приложения

Чтобы поддерживать несколько приложений в одном репозитории, создайте отдельный файл рабочего процесса и свяжите его с различными azure Pipelines.

Следующие шаги

Проверка запросов на вытягивание в подготовительных средах

Поделиться через

Конфигурация сборки для Статические веб-приложения Azure

Имя файла и расположение

Безопасность

Конфигурация построения

Команды настраиваемой сборки

Пропуск сборки внешнего приложения

Пропустить сборку API

Расширение времени ожидания сборки

Запуск рабочего процесса без секретов развертывания

Переменные среды

Поддержка единого репозитория

Следующие шаги

Обратная связь

Дополнительные ресурсы