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

Artigo
11/05/2024

A configuração de compilação dos Aplicativos Web Estáticos do Azure usa 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.

Property	Descrição	Obrigatório
`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: true`o , 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: true`o , 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.	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 Node.js aplicativos, 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

A ação 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 compilação. Os Aplicativos Web estáticos dão suporte ao uso de um token de implantação do Azure (recomendado) ou de 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, vá para Configurações>Configuração>Configuração Configuração Implantação e faça uma seleção para a política de autorização de Implantação.

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 main ramificação, o aplicativo é construído a partir da pasta e os app_location arquivos na output_location são servidos para a Web pública. Além disso, o aplicativo na pasta api está disponível no caminho do api site.

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 public pasta que contém a 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.
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_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

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"

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 public pasta que contém a 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.

O trabalho Fechar solicitação pull fecha automaticamente a solicitação pull que disparou a compilação e a implantação. Este trabalho opcional não é necessário para que o processo funcione.

Quando uma solicitação pull é aberta, a Ação GitHub dos Aplicativos Web Estáticos do Azure cria e implanta o aplicativo em um ambiente de preparação. Depois, o trabalho Fechar solicitação pull verifica se a solicitação pull 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 solicitações pull obsoletas. Ao fechar automaticamente o tempo de execução da solicitação pull, seu repositório permanece atualizado e sua equipe é notificada do status.

O trabalho Fechar solicitação pull faz parte do fluxo de trabalho Ações do GitHub dos aplicativos Web estáticos do Azure, fechando a solicitação pull depois que ela é mesclada. A Azure/static-web-apps-deploy ação implanta o aplicativo nos Aplicativos Web Estáticos do Azure, exigindo a azure_static_web_apps_api_token autenticação for.

Comandos de compilação personalizados

Para Node.js aplicativos, você pode ter um controle refinado sobre quais comandos são executados durante o processo de compilaçã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 Node.js, use o engines package.json campo no arquivo.

...

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

...

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

...

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

...

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 processar, mesmo quando alguns segredos estão faltando. Para configurar seu fluxo de trabalho para prosseguir sem segredos definidos, defina a SKIP_DEPLOY_ON_MISSING_SECRETS variável de ambiente como true.

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

...

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

Você pode definir variáveis de ambiente para sua compilação através 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 do Oryx.

...

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

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 paths nó às push seções e pull_request 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

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

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

Partilhar via

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

Nome e localização do ficheiro

Segurança

Compilar a configuração

Comandos de compilação personalizados

Ignorar a criação de aplicativos front-end

Ignorar a criação da API

Estender o tempo limite de compilação

Executar fluxo de trabalho sem segredos de implantação

Variáveis de ambiente

Suporte Monorepo

Próximos passos

Comentários

Recursos adicionais