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

A configuração de build dos Aplicativos Web Estáticos do Azure é alimentada por GitHub Actions ou Azure Pipelines. Cada site tem um arquivo de configuração YAML que controla a maneira 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ário
app_location	Essa pasta contém o código-fonte para o aplicativo de front-end. O valor está relacionado à raiz do repositório GitHub e à pasta de trabalho atual no Azure DevOps. Quando usado com skip_app_build: true, esse valor será o local de saída de compilação do aplicativo.	Sim
api_location	Essa pasta que contém o código-fonte para o aplicativo de API. O valor está relacionado à raiz do repositório GitHub e à pasta de trabalho atual no Azure DevOps. Quando usado com skip_api_build: true, esse valor será o local de saída da compilação da API.	Não
output_location	Se o aplicativo Web executa uma etapa de build, o local de saída é a pasta em que os arquivos públicos são gerados. Para a maioria dos projetos, o output_location está relacionado ao app_location. No entanto, para projetos .NET, o local está relacionado à 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 chamado build-prod para executar ng build --prod e insira-o npm run build-prod como o comando personalizado. Se for deixado em branco, o fluxo de trabalho tentará executar os comandos npm run build ou 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 para ignorar a compilação do aplicativo de front-end.	Não
skip_api_build	Defina o valor como true para ignorar a compilação das funções da API.	Não
cwd (Azure Pipelines somente)	Caminho absoluto para a pasta de trabalho. Assume o padrão de $(System.DefaultWorkingDirectory).	Não
build_timeout_in_minutes	De definir esse valor para personalizar o tempo de build. Assume o padrão de 15.	Não

Com essas definições, você pode configurar o GitHub Actions ou Azure Pipelines para executar a CI/CD (integração contínua e entrega contínua) para o aplicativo Web estático.

Nome e localização do arquivo

GitHub Actions

O arquivo de configuração é gerado pelo GitHub e armazenado na pasta .github/workflows, chamada 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.

Configuração de compilação

A configuração de exemplo a seguir monitora as alterações do repositório. À medida que as confirmações são enviadas para o branch main, o aplicativo é criado na pasta app_location e os arquivos no output_location são disponibilizados para a 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:

• As confirmações do branch main são monitoradas.
• Um fluxo de trabalho do GitHub Actions é disparado quando uma solicitação de pull no branch main é: aberta, sincronizada, reaberta ou fechada.
• O build_and_deploy_job é executado quando você envia as confirmações ou abre uma solicitação de pull em relação ao branch listado na propriedade on.
• O app_location aponta para a pasta src que contém os arquivos de origem para o aplicativo Web. Para definir esse valor como a raiz do repositório, use /.
• O api_location aponta para a pasta api que contém o aplicativo Azure Functions para os pontos de extremidade de API do site. Para definir esse valor como a raiz do repositório, use /.
• O output_location aponta para a pasta public que contém a versão final dos arquivos de origem do aplicativo. Ele é relativo a app_location. Para projetos .NET, o local está relacionado à pasta de saída de publicação.

Não altere os valores de repo_token, action e azure_static_web_apps_api_token, pois 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:

• As confirmações do branch main são monitoradas.
• O app_location aponta para a pasta src que contém os arquivos de origem para o aplicativo Web. Esse valor é relativo ao diretório de trabalho (cwd). Para defini-lo como o diretório de trabalho, use /.
• O api_location aponta para a pasta api 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 como o diretório de trabalho, use /.
• O output_location aponta para a pasta public que contém a versão final dos arquivos de origem do aplicativo. Esse valor é relativo a app_location. Para projetos .NET, o local está relacionado à pasta de saída de publicação.
• O cwd é um caminho absoluto que aponta para o diretório de trabalho. O padrão é $(System.DefaultWorkingDirectory).
• A variável $(deployment_token) aponta para o token de implantação gerado do Azure DevOps.

Observação

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

Comandos de compilação personalizados

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

Observação

No momento, você só pode definir app_build_command e api_build_command para builds Node.js. Para especificar a versão de Node.js, use o campo engines no arquivo 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)

Ignorar criação de aplicativo de front-end

Se você precisar de controle total do build para o aplicativo de front-end, pode ignorar o build automático e implantar o aplicativo criado em uma etapa anterior.

Para ignorar o build do aplicativo de front-end:

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

Observação

Certifique-se de ter o arquivo staticwebapp.config.json copiado também no 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 você quiser ignorar a compilação da API, poderá 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 runtime e a versão corretos. Consulte Configurar Aplicativos Web Estáticos do Azure para a lista de runtimes e versões com suporte.

  {
    "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 implantação. Esse caminho é relativo à raiz do repositório em GitHub Actions e cwd no 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)

Estender o tempo de build

Por padrão, os builds do aplicativo e da API são limitados a 15 minutos. Você pode estender o tempo de build definindo a propriedade 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)

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 para configurar seu fluxo de trabalho para true 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

É possível definir variáveis de ambiente para sua compilação por meio 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 a mono repositório

Um mono repositório é 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 é possível ajustar a configuração para direcionar um único aplicativo.

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

GitHub Actions

Ao configurar um monorepo, cada aplicativo estático tem seu próprio arquivo de configuração com escopo definido como somente arquivos em um único aplicativo. Os diferentes arquivos de fluxo de trabalho residem 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 paths nó a push e pull_request seções de um arquivo chamado 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

Nesse exemplo, somente as alterações feitas nos seguintes arquivos disparam um novo build:

• Quaisquer arquivos dentro da pasta App1
• Quaisquer arquivos dentro da pasta App1
• 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 o associe a um Azure Pipelines diferente.

Próximas etapas

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