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

Конфигурация сборки Статические веб-приложения 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 Actions

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

Azure Pipelines

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

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

В следующем примере конфигурации отслеживается репозиторий для изменений. При отправке main фиксаций в ветвь приложение создается из app_location папки и файлов в интернете output_location . Кроме того, приложение в папке API доступно по пути сайта api .

GitHub Actions

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 проверки подлинности.

Azure Pipelines

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

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

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

Примечание.

В настоящее время можно определить app_build_command только Node.js api_build_command сборки. Чтобы указать версию Node.js, используйте engines поле в package.json файле.

GitHub Actions

...

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'

Azure Pipelines

...

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 скопировали файл, а также в выходной каталог.

GitHub Actions

...

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

Azure Pipelines

...

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.

GitHub Actions

...

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

Azure Pipelines

...

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 , задав свойство.

GitHub Actions

...

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

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

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

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

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

GitHub Actions

...

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

Azure Pipelines

...

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".

GitHub Actions

...

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

Azure Pipelines

...

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.

GitHub Actions

При настройке 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 Pipelines.

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

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