Configuração de compilação para Aplicativos Web Estáticos do Azure

A configuração de compilação dos Aplicativos Web Estáticos do Azure é alimentada por Ações do GitHub ou Pipelines do Azure. Cada site tem um arquivo de configuração YAML que controla como um site é criado e implantado. Este artigo explica a estrutura e as opções do arquivo.

A tabela a seguir lista as definições de configuração disponíveis.

Propriedade	Descrição	Necessária
app_location	Esta pasta contém o código-fonte do seu aplicativo front-end. O valor é relativo à raiz do repositório no GitHub e à pasta de trabalho atual no Azure DevOps. Quando usado com skip_app_build: trueo , esse valor é o local de saída de compilação do aplicativo.	Sim
api_location	Esta pasta que contém o código-fonte para seu aplicativo de API. O valor é relativo à raiz do repositório no GitHub e à pasta de trabalho atual no Azure DevOps. Quando usado com skip_api_build: trueo , esse valor é o local de saída de compilação da API.	Não
output_location	Se seu aplicativo Web executar uma etapa de compilação, o local de saída será a pasta onde os arquivos públicos serão gerados. Para a maioria dos projetos, o output_location é relativo ao app_location. No entanto, para projetos .NET, o local é relativo à pasta de saída de publicação.	Não
app_build_command	Para aplicativos Node.js, você pode definir um comando personalizado para criar o aplicativo de conteúdo estático. Por exemplo, para configurar uma compilação de produção para um aplicativo Angular, crie um script npm nomeado build-prod para ser executado ng build --prod e inserido npm run build-prod como o comando personalizado. Se deixado em branco, o fluxo de trabalho tenta executar os npm run build comandos or npm run build:azure .	Não
api_build_command	Para aplicativos Node.js, você pode definir um comando personalizado para criar o aplicativo de API do Azure Functions.	Não
skip_app_build	Defina o valor como true ignorar a criação do aplicativo front-end.	Não
skip_api_build	Defina o valor como true ignorar a criação das funções da API.	Não
cwd (Somente Pipelines do Azure)	Caminho absoluto para a pasta de trabalho. O padrão é $(System.DefaultWorkingDirectory).	Não
build_timeout_in_minutes	Defina esse valor para personalizar o tempo limite de compilação. O padrão é 15.	Não

Com essas configurações, você pode configurar as Ações do GitHub ou os Pipelines do Azure para executar a integração contínua/entrega contínua (CI/CD) para seu aplicativo Web estático.

Nome e localização do ficheiro

GitHub Actions

O arquivo de configuração é gerado pelo GitHub e armazenado na pasta .github/workflows , nomeada usando o seguinte formato: azure-static-web-apps-<RANDOM_NAME>.yml.

Azure Pipelines

Por padrão, o arquivo de configuração é armazenado na raiz do repositório com o nome azure-pipelines.yml.

Compilar a configuração

O exemplo de configuração a seguir monitora as alterações no repositório. À medida que as confirmações são enviadas para a ramificação, o aplicativo é construído a partir da pasta e os arquivos na output_location são servidos para a mainapp_location Web pública. Além disso, o aplicativo na pasta api está disponível no caminho do api site.

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"

Nesta configuração:

• A main filial é monitorada quanto a confirmações.
• Um fluxo de trabalho de Ações do GitHub é acionado quando uma solicitação pull na main ramificação é: aberta, sincronizada, reaberta ou fechada.
• O build_and_deploy_job é executado quando você envia por push commits ou abre uma solicitação pull contra a ramificação listada on na propriedade.
• O app_location aponta para a src pasta que contém os arquivos de origem para o aplicativo Web. Para definir esse valor para a raiz do repositório, use /.
• O api_location aponta para a api pasta que contém o aplicativo Azure Functions para os pontos de extremidade de API do site. Para definir esse valor para a raiz do repositório, use /.
• O output_location aponta para a pasta que contém a public versão final dos arquivos de origem do aplicativo. É relativo a app_location. Para projetos .NET, o local é relativo à pasta de saída de publicação.

Não altere os valores de repo_token, actione azure_static_web_apps_api_token como eles são definidos para você pelos Aplicativos Web Estáticos do Azure.

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)

Nesta configuração:

• A main filial é monitorada quanto a confirmações.
• O app_location aponta para a src pasta que contém os arquivos de origem para o aplicativo Web. Esse valor é relativo ao diretório de trabalho (cwd). Para defini-lo para o diretório de trabalho, use /.
• O api_location aponta para a api pasta que contém o aplicativo Azure Functions para os pontos de extremidade de API do site. Esse valor é relativo ao diretório de trabalho (cwd). Para defini-lo para o diretório de trabalho, use /.
• O output_location aponta para a pasta que contém a public versão final dos arquivos de origem do aplicativo. Este valor é relativo a app_location. Para projetos .NET, o local é relativo à pasta de saída de publicação.
• O cwd é um caminho absoluto apontando para o diretório de trabalho. O padrão é $(System.DefaultWorkingDirectory).
• A $(deployment_token) variável aponta para o token de implantação do Azure DevOps gerado.

Nota

app_locatione devem ser relativos ao diretório de trabalho (cwd) e api_location devem ser subdiretórios em cwd.

Comandos de compilação personalizados

Para aplicativos Node.js, você pode ter um controle refinado sobre quais comandos são executados durante o processo de criação do aplicativo ou da API. O exemplo a seguir mostra como definir build com valores para app_build_command e api_build_command.

Nota

Atualmente, você só pode definir app_build_command e api_build_command para Node.js compilações. Para especificar a versão .js nó, use o enginespackage.json campo no arquivo.

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)

Ignorar a criação de aplicativos front-end

Se você precisar de controle total da compilação para seu aplicativo front-end, poderá ignorar a compilação automática e implantar o aplicativo criado em uma etapa anterior.

Para ignorar a criação do aplicativo front-end:

• Defina app_location para o local os arquivos que você deseja implantar.
• Defina skip_app_build como true.
• Defina output_location como uma cadeia de caracteres vazia ('').

Nota

Certifique-se de ter seu staticwebapp.config.json arquivo copiado também para o diretório de saída .

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)

Ignorar a criação da API

Se quiser ignorar a criação da API, você pode ignorar a compilação automática e implantar a API criada em uma etapa anterior.

Etapas para ignorar a criação da API:

• No arquivo staticwebapp.config.json, defina apiRuntime como o tempo de execução e a versão corretos. Consulte Configurar Aplicativos Web Estáticos do Azure para obter a lista de tempos de execução e versões suportados.

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

• Defina skip_api_build como true.
• Defina api_location para a pasta que contém o aplicativo de API criado para implantar. Esse caminho é relativo à raiz do repositório em Ações do GitHub e cwd em Pipelines do Azure.

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)

Estender o tempo limite de compilação

Por padrão, as compilações do aplicativo e da API são limitadas a 15 minutos. Você pode estender o tempo limite de compilação definindo a build_timeout_in_minutes propriedade.

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)

Executar fluxo de trabalho sem segredos de implantação

Às vezes, você precisa que seu fluxo de trabalho continue a processar, mesmo quando alguns segredos estão faltando. Defina a SKIP_DEPLOY_ON_MISSING_SECRETS variável de ambiente como true para configurar seu fluxo de trabalho para prosseguir sem segredos definidos.

Quando habilitado, esse recurso permite que o fluxo de trabalho continue sem implantar o conteúdo do site.

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

Variáveis de ambiente

Você pode definir variáveis de ambiente para sua compilação através da env seção de configuração de um trabalho.

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

Suporte Monorepo

Um monorepo é um repositório que contém código para mais de um aplicativo. Por padrão, o fluxo de trabalho rastreia todos os arquivos em um repositório, mas você pode ajustar a configuração para direcionar um único aplicativo.

Para direcionar um arquivo de fluxo de trabalho para um único aplicativo, especifique caminhos nas push seções e pull_request .

GitHub Actions

Quando você configura um monorepo, cada configuração de aplicativo estático tem como escopo apenas arquivos para um único aplicativo. Os diferentes arquivos de fluxo de trabalho vivem lado a lado na pasta .github/workflows do repositório.

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

O exemplo a seguir demonstra como adicionar um nó às seções e pull_request de um paths arquivo chamado azure-static-web-apps-purple-pond.yml.push

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

Neste exemplo, somente as alterações feitas nos seguintes arquivos acionam uma nova compilação:

• Todos os arquivos dentro da pasta app1
• Todos os arquivos dentro da pasta api1
• Alterações no arquivo de fluxo de trabalho azure-static-web-apps-purple-pond.yml do aplicativo

Azure Pipelines

Para dar suporte a mais de um aplicativo em um único repositório, crie um arquivo de fluxo de trabalho separado e associe-o a diferentes Pipelines do Azure.

Próximos passos

Revisar solicitações pull em ambientes de pré-produção