Configuración de compilación para Azure Static Web Apps

Artículo
11/06/2024

La configuración de compilación de Azure Static Web Apps utiliza Acciones de GitHub o Azure Pipelines. Cada sitio tiene un archivo de configuración YAML que controla cómo se construye e implementa. En este artículo se explican la estructura y las opciones del archivo.

En la tabla siguiente se enumeran los valores de configuración disponibles.

Propiedad	Descripción	Obligatorio
`app_location`	Esta carpeta contiene el código fuente de la aplicación de front-end. El valor es relativo a la raíz del repositorio en GitHub y la carpeta de trabajo actual en Azure DevOps. Cuando se usa con `skip_app_build: true`, este valor es la ubicación de salida de compilación de la aplicación.	Sí
`api_location`	Esta carpeta contiene el código fuente de la aplicación de API. El valor es relativo a la raíz del repositorio en GitHub y la carpeta de trabajo actual en Azure DevOps. Cuando se usa con `skip_api_build: true`, este valor es la ubicación de salida de compilación de la API.	No
`output_location`	Si la aplicación web ejecuta un paso de compilación, la ubicación de salida es la carpeta donde se generan los archivos públicos. Para la mayoría de los proyectos, `output_location` es relativo a `app_location`. Pero para los proyectos de .NET, la ubicación es relativa a la carpeta de salida.	No
`app_build_command`	Para las aplicaciones de Node.js, puede definir un comando personalizado para compilar la aplicación de contenido estático. Por ejemplo, para configurar una compilación de producción para una aplicación angular, cree un script NPM denominado `build-prod` para ejecutar `ng build --prod` y escriba `npm run build-prod` como comando personalizado. Si se deja en blanco, el flujo de trabajo intenta ejecutar los comandos `npm run build` o `npm run build:azure`.	No
`api_build_command`	Para las aplicaciones de Node.js, puede definir un comando personalizado para compilar la aplicación de API de Azure Functions.	No
`skip_app_build`	Establezca el valor en `true` para omitir la creación de la aplicación de front-end.	No
`skip_api_build`	Establezca el valor en `true` para omitir la creación de las funciones de la API.	No
`cwd` (Solo Azure Pipelines)	Ruta de acceso absoluta a la carpeta de trabajo. Su valor predeterminado es `$(System.DefaultWorkingDirectory)`.	No
`build_timeout_in_minutes`	Establezca este valor para personalizar el tiempo de espera de compilación. Su valor predeterminado es `15`.	No

Con estos valores, puede configurar Acciones de GitHub o Azure Pipelines a fin de ejecutar la integración continua o entrega continua (CI/CD) para la aplicación web estática.

Nombre y ubicación del archivo

La Acción de GitHub genera el archivo de configuración, que se almacena en la carpeta .github/workflows, denominada con el formato siguiente: azure-static-web-apps-<RANDOM_NAME>.yml.

De forma predeterminada, el archivo de configuración se almacena en la raíz del repositorio con el nombre azure-pipelines.yml.

Seguridad

Puede elegir entre dos directivas de autorización de implementación diferentes para proteger la configuración de compilación. Static Web Apps admite el uso de un token de implementación de Azure (recomendado) o un token de acceso de GitHub.

Siga estos pasos para establecer la directiva de autorización de implementación en la aplicación:

Aplicaciones nuevas: al crear la aplicación web estática, en la pestaña Configuración de implementación, realice una selección para la Directiva de autorización de implementación.
Aplicaciones existentes: para actualizar una aplicación existente, vaya a Configuración>Configuración>Configuración de implementación y realice una selección para la Directiva de autorización de implementación.

Configuración de compilación

La siguiente configuración de ejemplo supervisa los cambios en el repositorio. A medida que se insertan confirmaciones en la rama main, la aplicación se compila desde la carpeta app_location y los archivos de output_location se sirven a la web pública. Además, la aplicación de la carpeta api está disponible en la ruta api del sitio.

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)

En esta configuración:

La rama main se supervisa en busca de confirmaciones.
app_location apunta a la carpeta src que contiene los archivos de código fuente de la aplicación web. Este valor es relativo al directorio de trabajo (cwd). Para establecerlo en el directorio de trabajo, use /.
api_location apunta a la carpeta api que contiene la aplicación de Azure Functions para los puntos de conexión de API del sitio. Este valor es relativo al directorio de trabajo (cwd). Para establecerlo en el directorio de trabajo, use /.
output_location apunta a la carpeta public que contiene la versión final de los archivos de código fuente de la aplicación. Este valor es relativo a app_location. En los proyectos de .NET, la ubicación es relativa a la carpeta de salida.
cwd es una ruta de acceso absoluta que apunta al directorio de trabajo. Se establece de forma predeterminada en $(System.DefaultWorkingDirectory).
La variable $(deployment_token) apunta al token de implementación generado por Azure DevOps.

Nota:

app_location y api_location deben ser relativos al directorio de trabajo (cwd) y deben ser subdirectorios de cwd.

Token de implementación de Azure
Token de acceso de GitHub

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"

En esta configuración:

La rama main se supervisa en busca de confirmaciones.
Cuando una solicitud de incorporación de cambios se abre, se sincroniza, se vuelve a abrir o se cierra en la rama main, se desencadena un flujo de trabajo de Acciones de GitHub.
build_and_deploy_job se ejecuta al insertar confirmaciones o abrir una solicitud de incorporación de cambios en la rama indicada en la propiedad on.
app_location apunta a la carpeta src que contiene los archivos de código fuente de la aplicación web. Para establecer este valor en la raíz del repositorio, use /.
api_location apunta a la carpeta api que contiene la aplicación de Azure Functions para los puntos de conexión de API del sitio. Para establecer este valor en la raíz del repositorio, use /.
output_location apunta a la carpeta public que contiene la versión final de los archivos de código fuente de la aplicación. Es relativo a app_location. En los proyectos de .NET, la ubicación es relativa a la carpeta de salida de publicación.

No cambie los valores de repo_token, action y azure_static_web_apps_api_token, ya que Azure Static Web Apps los establece de forma automática.

El trabajo Cerrar solicitud de cambios cierra automáticamente la solicitud de cambios que desencadenó la compilación y la implementación. Este trabajo opcional no es necesario para que el proceso funcione.

Cuando se abre una solicitud de cambios, la Acción de GitHub de Azure Static Web Apps compila e implementa la aplicación en un entorno de ensayo. Después, el trabajo Cerrar solicitud de cambios comprueba si la solicitud de cambios sigue abierta y la cierra con un mensaje de finalización.

Este trabajo ayuda a mantener el flujo de trabajo de solicitud de cambios organizado y evita solicitudes de cambios obsoletas. Al cerrar automáticamente la solicitud de cambios, el repositorio permanece actualizado y el equipo recibe una notificación del estado.

El trabajo Cerrar solicitud de incorporación de cambios forma parte del flujo de trabajo de Acciones de GitHub de Azure Static Web Apps, cerrando la solicitud e cambios después de combinarla. La acción Azure/static-web-apps-deploy implementa la aplicación en Azure Static Web Apps, lo que requiere azure_static_web_apps_api_token para autenticación.

Comandos de compilación personalizados

En las aplicaciones de Node.js, puede controlar con precisión los comandos que se ejecutan durante el proceso de compilación de la aplicación o la API. En el ejemplo siguiente se muestra cómo definir la compilación con valores para app_build_command y api_build_command.

Nota:

Actualmente, solo puede definir app_build_command y api_build_command para compilaciones de Node.js. Para especificar la versión de Node.js, use el campo engines del archivo package.json.

...

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)

Omisión de la compilación de una aplicación front-end

Si necesita control total de la compilación para la aplicación de front-end, puede omitir la compilación automática e implementar la aplicación compilada en un paso anterior.

Para omitir la compilación de la aplicación de front-end:

Establezca app_location en la ubicación de los archivos que quiera implementar.
Establezca skip_app_build en true.
Establezca output_location en una cadena vacía ('').

Nota:

Asegúrese de que el archivo staticwebapp.config.json se haya copiado también en el directorio output.

...

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)

Omisión de la compilación de la API

Si quiere omitir la compilación de la API, puede omitir la compilación automática e implementar la API compilada en un paso anterior.

Pasos para omitir la compilación de la API:

En el archivo staticwebapp.config.json, establezca apiRuntime en el runtime y la versión correctos. Consulte Configuración de Azure Static Web Apps para ver la lista de runtimes y versiones admitidos.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Establezca skip_api_build en true.
Establezca api_location en la carpeta que contiene la aplicación de API compilada que se va a implementar. Esta ruta de acceso es relativa a la raíz del repositorio en Acciones de GitHub y cwd en 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)

Ampliación del tiempo de espera de compilación

De manera predeterminada, las compilaciones de API y aplicación están limitadas a 15 minutos. Puede extender el tiempo de espera de compilación si establece la propiedad build_timeout_in_minutes.

...

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)

Ejecución del flujo de trabajo sin secretos de implementación

A veces, necesita que el flujo de trabajo continúe procesando incluso cuando faltan algunos secretos. Para configurar el flujo de trabajo para continuar sin secretos definidos, establezca la variable de entorno SKIP_DEPLOY_ON_MISSING_SECRETS en true.

Cuando está habilitada, esta característica permite que el flujo de trabajo continúe sin implementar el contenido del sitio.

...

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

Variables de entorno

Puede establecer variables de entorno para la compilación a través de la sección env de la configuración de un trabajo.

Para más información sobre las variables de entorno usadas por Oryx, consulte Configuración de 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

Compatibilidad con monorrepositorios

Un monorrepositorio es un repositorio que contiene código para más de una aplicación. De manera predeterminada, el flujo de trabajo realiza el seguimiento de todos los archivos de un repositorio, pero se puede ajustar la configuración para que el destino sea una sola aplicación.

Para que un archivo de flujo de trabajo tenga como destino una única aplicación, especifique las rutas de acceso en las secciones push y pull_request.

Al configurar un repositorio único, el ámbito de configuración de cada aplicación se limita exclusivamente a los archivos de una sola aplicación. Los distintos archivos de flujo de trabajo residen en paralelo en la carpeta .github/workflows del repositorio.

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

En el ejemplo siguiente se muestra cómo agregar un nodo paths a las secciones push y pull_request de un archivo denominado 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

En este ejemplo, solo los cambios realizados en los siguientes archivos desencadenan una nueva compilación:

Cualquier archivo dentro de la carpeta app1
Cualquier archivo dentro de la carpeta api1
Cambios en el archivo de flujo de trabajo azure-static-web-apps-purple-pond.yml de la aplicación

Para admitir más de una aplicación en un único repositorio, cree un archivo de flujo de trabajo independiente y asócielo a otras instancias de Azure Pipelines.

Pasos siguientes

Revisión de las solicitudes de incorporación de cambios en entornos de pre-producción

Compartir vía

Configuración de compilación para Azure Static Web Apps

Nombre y ubicación del archivo

Seguridad

Configuración de compilación

Comandos de compilación personalizados

Omisión de la compilación de una aplicación front-end

Omisión de la compilación de la API

Ampliación del tiempo de espera de compilación

Ejecución del flujo de trabajo sin secretos de implementación

Variables de entorno

Compatibilidad con monorrepositorios

Pasos siguientes

Comentarios

Recursos adicionales