Welcome to Week 1, Day 6 of #30DaysOfSWA!!

We're almost at the end of week 1!! 🎉

So far, we've learned how we can use the static assets hosting (Azure Static Web Apps) and serverless API (Azure Functions) capabilities to build and deploy a web application in a scalable and cost-effective way. And we learned to configure and secure our Static Web App to suit our needs. So what else do we need to talk about?

Deployment options? Let's do it!! We've talked about the default experience so far: deploy from a production branch, using GitHub Actions for CI/CD. But how do we handle previewing the Static Web App before production deploys? Let's talk about previewing SWA in pull requests, on non-production branches, and in pre-configured named environments that make our staging workflows more productive.

What We'll Cover

What types of deployment does SWA support?
Previewing: in Pull Requests
Previewing: in Non-Production Branches
Previewing: in Named Environments
Deploying: to Custom Domains
Exercise: Review PR using SWA Preview Capability

About the Author(s)

Michail (Misha) Shaposhnikov is a Software Engineer at Microsoft working with the Azure Static Web Apps product amongst other things. Find him at mishapos on GitHub

Deployment Types

When we think about deployment, we are typically thinking of two kinds of environments: production which serve as the primary endpoint for real world use, and staging that can be used for internal testing, early validation of preview releases.

Azure Static Web Apps has built-in support for four types of environments:

Production: This is the real world deployment endpoint that is indexed by search engines, and associated with the custom domain (if configured).
Pull Request (PR): This is a temporary environment setup for a Pull Request, and torn down when that PR is closed.
Branch: This is a environment you can set up for non-production branches, at a stable URL for the lifetime of the branch.
Named: The above environments have URLs that reflect their PR (number) or branch (name). You can also configure a stable preview environment with a fixed name, associated with some deployment context (e.g., an interim release)

Production deploys have URLs like <DEFAULT-HOSTNAME>-<NUMBER>.azurestaticapps.net where the DEFAULT-HOSTNAME is unique for each application.

With preview environments, the URL looks like: <DEFAULT_HOSTNAME>-<BRANCH_OR_ENVIRONMENT_NAME>.<LOCATION>.azurestaticapps.net where the LOCATION reflects the deployment region, and the BRANCH_OR_ENVIRONMENT_NAME can also take the form of a branch name, a named environment, or a number in the case of pull requests.

Let's take a brief look at each of these.

Pull Requests

Currently Pull Request preview environments are available for projects hosted in GitHub, and configured to use GitHub Actions by Azure Static Web Apps:

Every PR to a watched branch gets a dedicated but temporary pre-production staging environment that is torn down when the PR is closed.
Use it to validate changes, perform sanity checks, etc.
The environment is automatically rebuilt and deployed if new commits are made to the branch associated with an active PR.
The staged environment is publicly visible event if your GitHub repo is private - though the URL is not easily discoverable (i.e., not indexed by search engines) by default.

Learn how to preview Pull Requests in Azure Static Web Apps.

Branches

Preview environments for branches will have stable URLs. Configure them in the relevant GitHub Actions or Azure Pipelines workflow files as shown in this example.

For example, in a GitHub Actions context, this involves two steps:

set the production_branch property to the branch you want to use as the source for that production deployment.
list all other branches that you want preview environments for under trigger (Azure Pipelines) or push: branches (in GitHub Actions).

You can use a wildcare (** for GitHub Actions, * for Azure Pipelines) if you want to track all branches for preview environment support.

Here's an example GitHub Actions config file - the production environment is built from the main branch, and separate preview environments are built for the other listed branches (dev and staging).

Learn how to create branch preview environments in Azure Static Web Apps.

name: Azure Static Web Apps CI/CD

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

jobs:
  build_and_deploy_job:
    ...
    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:
          ...
          production_branch: "main"

Named Environments

Sometimes, you want to have a non-production preview environment that is at stable URL (not tied to a specific PR number or branch name), and that gets rebuilt on commits to all tracked branches in the configuration file.

Just like with branches, this requires a manual change to your default configuration file (GitHub Actions or Azure Pipelines) as shown in this example.

In the GitHub Actions case, the steps are:

Set the deployment_environment property (in the relevant build job) to be the name you want to use for this preview environment
List the branches you want associated with this named environment under push: branches - commits to those will result in rebuild/deploy to this environment.

Here's an example GitHub Actions configuration file - this sets up a named environment called release which gets updated when changes are made to any branch (reflected by the ** wildcard), and deployed to a site with a URL like <DEFAULT_HOST_NAME>-release.<LOCATION>.azurestaticapps.net.

Learn about named preview environments in Azure Static Web Apps

name: Azure Static Web Apps CI/CD

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

jobs:
  build_and_deploy_job:
    ...
    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:
          ...
          deployment_environment: "release"

Custom Domains

You may have noticed that default deployment URLs - in the form XXX.azurestaticapps.net for production environments or XXX.<LOCATION>.azurestaticapps.net for preview environments - are not exactly user friendly for use and recall.

Adding a custom domain helps. Azure Static Apps makes that easy with options to also configure subdomains and an apex domain! Here, given a domain like www.azure.com, azure.com is the apex domain and www is the relevant subdomain.

So how do you configure these? You have two options:

Use an external DNS Provider (if your domain registrar supports it)
Use Azure DNS (to manage your DNS domain, even if purchased elsewhere)

To keep this post short, we won't go into details for each of these options. Instead check out these links based on the direction you want to go in:

Setup Apex Domain - with Azure DNS | with External Provider
Setup Subdomain - with Azure DNS | with External Provider

How-Tos: Watch It!

Prefer a Video Walkthrough to understand the process? We have you covered with the Azure Tips And Tricks: Static Web Apps series. Check out this video to understand how you can setup a custom domain for your Static Web App!

Exercise: Try it!

Pull Requests are critical to having a productive open source or multi-contributor project, so it's important to know how Azure Static Apps works in setting up pre-production environments for validating the changes proposed in a pull-request, before merging it for production deployment.

Get hands-on experience with the process by completing this tutorial on an existing Azure Static Web Apps project.

At present, the staged pre-production environment for Pull Requests is available only for GitHub Actions deployments - so make sure you pick a GitHub-hosted SWA project that already had the default workflows set up.

#06: Previewing Static Web Apps