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

Artigo
06/11/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.

Nome e local do arquivo

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.

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

Segurança

Você pode escolher entre duas políticas de autorização de implantação diferentes para proteger sua configuração de build. Os Aplicativos Web Estáticos dão suporte ao uso de um token de implantação do Azure (recomendado) ou a um token de acesso do GitHub.

Use as seguintes etapas para definir a política de autorização de implantação em seu aplicativo:

Novos aplicativos: ao criar seu aplicativo Web estático, na guia Configuração de implantação, faça uma seleção para a Política de autorização de implantação.
Aplicativos existentes: para atualizar um aplicativo existente, acesse Configurações>Configuração>Configuração de implantação e faça uma seleção para a Política de autorização de implantação.

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.

YAML

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 .

Token de identidade
Token de acesso do Azure

yml

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"

yml

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 do GitHub Actions dos Aplicativos Web Estáticos do Azure, 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.

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.

yml

...

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'

YAML

...

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.

yml

...

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

yml

...

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.

JSON
```
{
  "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.

yml

...

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

yml

...

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.

YAML

...

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

yml

...

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. Para configurar o fluxo de trabalho para continuar sem segredos definidos, defina a variável de ambiente SKIP_DEPLOY_ON_MISSING_SECRETS como true.

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

YAML

...

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

YAML

...

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.

YAML

...

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

yml

...

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.

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.

files

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

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

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

Compartilhar via

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

Nome e local do arquivo

Segurança

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