PR preview environments

This post is part of the Azure Static Web Apps with Blazor series.

A complete working example is available here: mongeon/code-examples · azure-swa-blazor/06-preview-environments.

This is one of the SWA features I find most underrated. Every time you open a pull request against your production branch, Azure automatically creates a temporary environment with its own URL. The reviewer can click the link, test the changes live, and approve or reject the PR. When the PR is closed, the environment is destroyed automatically.

No more sharing a staging server that’s “always a bit behind”, no more “it works on my machine”. Each PR gets its own isolated environment.

How does it work?

The GitHub Actions workflow generated by SWA already supports preview environments. Look at the on section of your workflow:

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

When a PR is opened against main, the workflow triggers and deploys to a temporary environment. The URL follows this format:

https://<your-hostname>-<pr-number>.<region>.azurestaticapps.net

For example, your first PR will be available at something like https://lively-moss-123456-1.eastus2.azurestaticapps.net.

The workflow also includes a close_pull_request_job that cleans up the environment when the PR is closed or merged:

close_pull_request_job:
  if: github.event_name == 'pull_request' && github.event.action == 'closed'
  runs-on: ubuntu-latest
  name: Close Pull Request
  steps:
    - name: Close Pull Request
      uses: Azure/static-web-apps-deploy@v1
      with:
        azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
        action: "close"

You don’t have to configure anything. It works as soon as the workflow is in place.

The GitHub bot

After deployment, an Azure Static Web Apps bot adds a comment to your PR with a link to the preview environment. The reviewer just has to click. If you push new commits to the same branch, the environment is updated automatically and the link stays the same.

Branch environments

Beyond PRs, you can also create environments for specific branches. This is useful if you have a dev or staging branch that you want to keep permanently accessible.

Add the branches to the push section of the workflow:

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

The branch environment URL is stable and includes the branch name:

https://<your-hostname>-dev.<region>.azurestaticapps.net

Unlike PR environments, branch environments persist as long as the branch exists. You can delete them manually in the Azure portal under the Environments tab of your Static Web App.

Named environments

If you want a staging environment that doesn’t depend on a branch name, you can use named environments. Add the deployment_environment property in your workflow:

- 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 }}
    action: "upload"
    app_location: "."
    api_location: "Api"
    output_location: "wwwroot"

The URL will be https://<your-hostname>-staging.<region>.azurestaticapps.net. Named environments persist until you explicitly delete them.

Environment-specific variables

Your preview environment will probably need different variables than production. For example, pointing to a test database instead of production.

In the Azure portal, under Static Web Apps > Environment variables, you can configure variables per environment. Each preview environment (PR, branch or named) has its own settings.

This is also possible via the Azure CLI:

az staticwebapp appsettings set \
  --name my-blazor-app \
  --resource-group my-rg \
  --environment-name "staging" \
  --setting-names "DATABASE_CONNECTION_STRING=my-staging-connection-string"

Limitations to know

The number of preview environments depends on your tier. The free tier allows 3 environments on top of production. The Standard tier allows 10.

Preview environments are publicly accessible by their URL, even if your GitHub repo is private. The URL is not indexed by search engines, but anyone with the link can access it. If that’s a concern, you can enable password protection in the Azure portal under Configuration > General settings > Protect staging environments.

Preview environments don’t support custom domains. They always use the azurestaticapps.net subdomain.

One last thing: linked backends (covered in article 3) don’t work with PR preview environments. Managed functions, however, are deployed to every preview environment.

Articles in this series

What is an Azure Static Web App?
The staticwebapp.config.json file
Adding an Azure Functions API
SWA’s built-in authentication
Local development with the swa CLI
PR preview environments (This article)

Happy deploying, and happy PR reviews.

This post was written with AI assistance and edited by me.