Skip to main content

Deploy a static site

In this tutorial, you review and publish plain HTML/CSS or a Vite TypeScript frontend with App Service Builder. Use Portal or Builder CLI, verify the hosted site, and delete the test app when finished. Neither sample needs a web process or a hosted Vite development server.

Prerequisites​

  • Private Preview access, an authorized subscription, and an available region. Use development/test workloads only.
  • A GitHub account that can fork the sample and authorize source access.
  • Confirmation that your preview environment supports the selected sample.
  • For optional local changes and checks: Git and Node.js 24; Vite also uses npm. You do not need these tools locally to deploy a committed fork with Portal.

Already using Azure Static Web Apps? Use the Builder evaluation guide to assess required features before testing a separate preview app. It is not a production migration procedure.

Prepare your source​

Choose the source type for this test and keep the same fork throughout deployment.

Fork the static HTML sample. For local changes, clone your fork:

git clone https://github.com/<your-github-account>/app-service-builder-static-html.git
cd app-service-builder-static-html

Builder serves only committed files in public/; this sample has no language build. Follow the repository README for local checks and keep secrets and unintended files out of public/.

Keep the manifest at repository root and push changes to the branch you intend to deploy. Do not select public/ or dist/ as the app source root.

Review build and output settings​

SettingHTML/CSSVite TypeScript
Component rolestaticstatic
Platform/buildNo platform or buildnodejs, version "24"; recognized Vite build
Static outputpublic, beneath the component source rootdist, beneath the generated build root
App path//
Server startupNo run blockNo run block

See the manifest guide for static output semantics.

Create and deploy the app​

Keep the fork, branch, and root builder.yaml you prepared above. Builder deploys committed GitHub source, not uncommitted local files.

Open the App Service Builder Portal. Your Azure account needs permission to create and deploy Microsoft.Web/builderApps resources. Creating a resource group also requires permission to create groups in the selected subscription.

  1. Sign in to the Portal with the Microsoft account authorized for your subscription.
  2. Select the subscription and choose Create.
  3. In Connect GitHub, sign in to GitHub and authorize the OAuth App. Keep Use my repository selected to deploy the fork you prepared above. Choose the account or organization that owns your fork, then select that repository and branch. Use Change account if you need a different GitHub account, or Refresh access after changing repository permissions. Select Next.
  4. In Choose approach, confirm the selected repository and branch. Keep Let Builder handle it selected. The App Service Builder GitHub App needs access to this repository to read your code, build it, and deploy your app. Signing in to GitHub alone does not grant this access. If prompted, select Install GitHub App and grant access to your selected repository, or add it to an existing installation. Close the GitHub window to refresh access, or select Refresh access after approval. Select Next when Builder is connected and GitHub App access confirmed are shown.
  5. In App details, enter an app name and select the subscription, resource group, and offered location. To create a resource group, select Create new, enter its name, and choose Resource group region. Select Add. The group appears as (new) and is created when you submit. Its region stores the resource group's metadata and does not change the app's region. Select Next.
  6. On Review and create, confirm the app, repository, branch, subscription, resource group, and app region. Select Create and deploy.
  7. Open the app's Deployments page and wait for the deployment to succeed. In Versions, inspect the source revision, component results, and build logs. Select Deploying to open an in-progress deployment's steps and logs. On Overview, use Browse to open the app URL.

Already prepared a fork? Keep Use my repository selected so you deploy that source, not a second copy. To start with a new sample instead, follow Create from a Portal template. Use GitHub Actions is marked Coming soon; use the Builder-managed approach for this preview.

If group creation fails, app creation does not start. If the group was created before a later failure, it remains in Azure; cancelling does not delete it. Check the existing group and app before retrying, and inspect a group's contents before deleting it separately.

See GitHub authorization requirements for organization approvals and SSO. If app creation succeeds but deployment cannot start, read the error and retry deployment on the existing app rather than creating a duplicate. For “Source revision does not contain builder.yaml”, push the missing manifest before retrying.

For API automation, use the ARM API deployment guide with this same fork, branch, and source root ".". ARM and Bicep infrastructure templates provision the resource; separately authorize and connect this source, then deploy it through CLI or ARM.

Verify the hosted site​

After deployment succeeds, browse the returned app URL and check its expected page. Without a trailing slash on <app-runtime-url>, both samples support:

curl -i "<app-runtime-url>/"
curl -i "<app-runtime-url>/health"

Expect HTTP 200 at both paths and health body OK followed by a newline. HTML shows App Service Builder / static-html and its browser-ready greeting. Vite shows App Service Builder / vite-static and Hello from Vite. by default; verify that emitted JavaScript assets load successfully. The samples include /health as a static file; no server process handles it. In Overview, confirm the active version. In Versions, check that its source revision matches the commit you intended to deploy.

Push changes and explicitly deploy a new version to update the assets. Variables distinguishes build-time static values from runtime process configuration.

Clean up resources​

Delete only the test app you created when you no longer need it. App deletion does not remove your GitHub repository, resource group, or separately owned services and user-assigned identities.

Return to the app inventory and choose Delete from the test app's actions. Alternatively, open the app's Settings and select Delete under Danger zone. Confirm the selected app and follow deletion to completion. Deleting from Settings returns you to the home inventory after the deletion request is accepted.

Related content​

Use source control to change the branch or app root. Use the manifest guide to adapt the site's build and output.

Last updated on