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

Artigo
06/03/2024

A configuração de compilação dos Aplicativos Web Estáticos do Azure usa o GitHub Actions ou o 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	Obrigató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.	Yes
`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 é relativo à pasta de saída.	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.

A ação do GitHub gera o arquivo de configuração e é armazenada na pasta .github/workflows, nomeada usando o seguinte formato: azure-static-web-apps-<RANDOM_NAME>.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
Azure Pipelines

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.

O trabalho Fechar Solicitação de Pull fecha automaticamente a pull request que disparou a compilação e a implantação. Esse trabalho opcional não é necessário para que o processo funcione.

Quando uma pull request é aberta, o Aplicativos Web Estáticos do Azure no GitHub Actions cria e implanta o aplicativo em um ambiente de preparação. Depois disso, o trabalho Fechar Pull Request verifica se a pull request ainda está aberta e a fecha com uma mensagem de conclusão.

Esse trabalho ajuda a manter seu fluxo de trabalho de pull request organizado e evita pull requests obsoletas. Com o runtime fechando automaticamente a pull request, o seu repositório permanece atualizado e a sua equipe é notificada sobre o status.

O trabalho Fechar Pull Request faz parte do fluxo de trabalho dos Aplicativos Web Estáticos do Azure no GitHub Actions, fechando a pull request depois que ela é mesclada. A ação Azure/static-web-apps-deploy implanta o aplicativo no Aplicativos Web Estáticos do Azure, exigindo o azure_static_web_apps_api_token para autenticação.

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 é relativo à pasta de saída.
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
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: '/'
  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)

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.
Definir skip_app_build para 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
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/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)

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"
  }
}
```
Definir skip_api_build para 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
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)

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
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'
  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)

Executar fluxo de trabalho sem segredos de implantação

Às vezes, você precisa que seu fluxo de trabalho continue a ser processado mesmo quando alguns segredos estiverem ausentes. Defina a variável de ambiente SKIP_DEPLOY_ON_MISSING_SECRETS como true para configurar o fluxo de trabalho para prosseguir sem os segredos definidos.

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

GitHub Actions
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'
  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

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.

Para obter mais informações sobre as variáveis de ambiente usadas pelo Oryx, consulte Configuração Oryx.

GitHub Actions
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'
  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

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
Azure Pipelines

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

Próximas etapas

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

Compartilhar via

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

Nome e local do arquivo

Configuração de compilação

Comandos de compilação personalizados

Ignorar criação de aplicativo de front-end

Ignorar a criação da API

Estender o tempo de build

Executar fluxo de trabalho sem segredos de implantação

Variáveis de ambiente

Suporte a mono repositório

Próximas etapas

Comentários

Recursos adicionais