GitHub Actions workflows for Azure Static Web Apps Preview

When you create a new Azure Static Web App resource, Azure generates a GitHub Actions workflow to control the app's continuous deployment. The workflow is driven by a YAML file. This article details the structure and options of the workflow file.

Deployments are initiated by triggers, which run jobs that are defined by individual steps.

File location

When you link your GitHub repository to Azure Static Web Apps, a workflow file is added to the repository.

Follow these steps to view the generated workflow file.

  1. Open the app's repository on GitHub.
  2. From the Code tab, click on the .github/workflows folder.
  3. Click on the file with a name that looks like azure-static-web-apps-<RANDOM_NAME>.yml.

The YAML file in your repository will be similar to the following example:

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@v0.0.1-preview
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: 'upload'
          ###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
          app_location: '/' # App source code path
          api_location: 'api' # Api source code path - optional
          output_location: 'dist' # Built app content directory - 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@v0.0.1-preview
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
          action: 'close'

Triggers

A GitHub Actions trigger notifies a GitHub Actions workflow to run a job based off event triggers. Triggers are listed using the on property in the workflow file.

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

Through settings associated with the on property, you can define which branches trigger a job, and set triggers to fire for different pull request states.

In this example, a workflow is started as the main branch changes. Changes that start the workflow include pushing commits and opening pull requests against the chosen branch.

Jobs

Each event trigger requires an event handler. Jobs define what happens when an event is triggered.

In the Static Web Apps workflow file, there are two available jobs.

Name Description
build_and_deploy_job Executes when you push commits or open a pull request against the branch listed in the on property.
close_pull_request_job Executes ONLY when you close a pull request, which removes the staging environment created from pull requests.

Steps

Steps are sequential tasks for a job. A step carries out actions like installing dependencies, running tests, and deploying your application to production.

A workflow file defines the following steps.

Job Steps
build_and_deploy_job
  1. Checks out the repository in the Action's environment.
  2. Builds and deploys the repository to Azure Static Web Apps.
close_pull_request_job
  1. Notifies Azure Static Web Apps that a pull request has closed.

Build and deploy

The step named Build and Deploy builds and deploys to your Azure Static Web Apps instance. Under the with section, you can customize the following values for your deployment.

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
  repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
  action: 'upload'
  ###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
  app_location: '/' # App source code path
  api_location: 'api' # Api source code path - optional
  output_location: 'dist' # Built app content directory - optional
  ###### End of Repository/Build Configurations ######
Property Description Example Required
app_location Location of your application code. Enter / if your application source code is at the root of the repository, or /app if your application code is in a directory called app. Yes
api_location Location of your Azure Functions code. Enter /api if your app code is in a folder called api. If no Azure Functions app is detected in the folder, the build doesn't fail, the workflow assumes you don't want an API. No
output_location Location of the build output directory relative to the app_location. If your application source code is located at /app, and the build script outputs files to the /app/build folder, then set build as the output_location value. No

The repo_token, action, and azure_static_web_apps_api_token values are set for you by Azure Static Web Apps shouldn't be manually changed.

Custom build commands

You can have fine-grained control over what commands run during a deployment. The following commands can be defined under a job's with section.

The deployment always calls npm install before any custom command.

Command Description
app_build_command Defines a custom command to run during deployment of the static content application.

For example, to configure a production build for an Angular application create an npm script named build-prod to run ng build --prod and enter npm run build-prod as the custom command. If left blank, the workflow tries to run the npm run build or npm run build:azure commands.
api_build_command Defines a custom command to run during deployment of the Azure Functions API application.

Skip app build

If you need full control over how your front-end application is built, you can add custom build steps in your workflow. Then you can configure the Static Web Apps action to bypass the automatic build process and just deploy the app that was built in a previous step.

To skip building the app, set skip_app_build to true and app_location to the location of the folder to deploy.

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
  repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
  action: 'upload'
  ###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
  app_location: 'dist' # Application build output generated by a previous step
  api_location: 'api' # Api source code path - optional
  output_location: '' # Leave this empty
  skip_app_build: true
  ###### End of Repository/Build Configurations ######
Property Description
skip_app_build Set the value to true to skip building the front-end app.

Note

You can only skip the build for the front-end app. If your app has an API, it'll still be built by the Static Web Apps GitHub Action.

Route file location

You can customize the workflow to look for the staticwebapp.config.json in any folder in your repository. The following property can be defined under a job's with section.

Property Description
routes_location Defines the directory location where the staticwebapp.config.json file is found. This location is relative to the root of the repository.

Being explicit about the location of your staticwebapp.config.json file is particularly important if your front-end framework build step does not move this file to the output_location by default.

Environment variables

You can set environment variables for your build via the env section of a job's configuration.

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@v0.0.1-preview
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: 'upload'
          ###### Repository/Build Configurations
          app_location: '/'
          api_location: 'api'
          output_location: 'public'
          ###### End of Repository/Build Configurations ######
        env: # Add environment variables here
          HUGO_VERSION: 0.58.0

Monorepo support

A monorepo is a repository that contains code for more than one application. By default, a Static Web Apps workflow file tracks all the files in a repository, but you can adjust it to target a single app. Therefore, for monorepos, each static app has it's own configuration file which lives side-by-side in the repository's .github/workflows folder.

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

To target a workflow file to a single app, you specify paths in the push and pull_request sections.

The following example demonstrates how to add a paths node to the push and pull_request sections of a file named 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

In this instance, only changes made to following files trigger a new build:

  • Any files inside the app1 folder
  • Any files inside the api1 folder
  • Changes to the app's azure-static-web-apps-purple-pond.yml workflow file

Next steps