Create a static web app

Creating a static web app needs staticwebapp/write in the resource group, and kernel/deployments/read to pick the repository from the boundary's deployment sources. The Owner, Contributor and Apps Operator roles have both.

Before you start

• A resource group to put the site in — see Create a resource group.
• A deployment source for GitHub, GitLab or Azure DevOps on the boundary — see Add a source. A GitLab or Azure DevOps source connected with an OAuth application takes you away from the page you are on, so connect it before you open the wizard.
• The finished site committed to the repository, with an index.html in the directory you want to serve.

Open the wizard

In the portal at https://portal.example.com, open Static Web Apps in the sidebar and choose Create Static Web Apps. The Create Static Web App wizard has five steps: Basics, Source, Routing, Networking and Review.

Basics

• Site name — 3 to 50 characters: lowercase letters, digits and hyphens, not starting or ending with a hyphen, and unique in the resource group. The name is part of the site's platform address and cannot be changed later.
• Boundary, Cluster and Resource group — where the site runs. Each is filled in for you when there is only one choice. A site stays on the cluster it was created on.

Source

• Deployment Source Type — GitHub, GitLab or Azure DevOps.
• The installation or connection to use. Connect Deployment Source adds one without leaving the wizard.
• Repository and Branch — Branch starts out as main and keeps that value when you pick the repository; it takes the repository's default branch only when it is empty. For a repository without a main branch, for example one whose default branch is master, choose the branch yourself, or the first deployment fails.
• Directory to serve — the folder in the repository that holds index.html, for example public or site/dist; . is the repository root. It is a path inside the repository: letters, digits, /, ., - and _, not starting with / and without ...

There are no build settings

The wizard asks for no build command, output directory, framework or environment variables, because nothing is built: the files in the directory are served as they are committed.

If your site needs a build first — React, Vue, Astro, Next.js, Hugo, anything with a build command — either create an app instead, or commit the built output and point Directory to serve at it. A directory whose package.json has a build script is refused when the site deploys.

Routing

• Single-page app routing — on by default. Paths that match no file are answered with /index.html, so client-side routes work on refresh and in deep links. Turn it off for a site of plain pages.
• 404 page — a page to serve for paths that match no file, such as /404.html. Leave it empty for the web server's default.
• Caching — Hashed assets (recommended), Cache all assets or No cache headers. What each sends is in Cache presets.
• Replicas — how many copies serve the site, from 0 to 10; 1 by default. With 0 the site is created stopped.

The first three can be changed later without a redeploy.

Networking

• Custom domain — optional. Leave it empty to serve the site on the platform address the wizard shows. A custom domain is a lowercase domain name such as www.example.com, without https://, port, path or trailing dot. It needs a DNS record pointing at the platform before its certificate can be issued; see Use a custom domain.

Your site will be served at shows the address the site will have. The platform address keeps working next to a custom domain.

Review and create

Review shows the site, its source and its routing. Choose Submit. The site appears in the list as Creating, then Packaging and Deploying while its first deployment runs, and Running when it serves. The first deployment's log is on the site's Deployments tab. If the site ends in Error, see Statuses.

Next steps

• Deploy and follow deployments
• Use a custom domain
• Routing and caching