Deploy a .NET app

In this tutorial, you deploy a small .NET 10 ASP.NET Core app from your GitHub fork with App Service Builder. Use Portal or Builder CLI, verify the running app, and delete the test app when finished.

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.
• Confirmed .NET 10 availability in your preview environment.
• For optional local changes and checks: Git and a stable .NET 10 SDK. The sample's global.json selects 10.0.100 or a later stable .NET 10 feature band. A local SDK is not required just to select a committed fork in Portal.

Prepare your source

Fork the .NET sample repository. For local changes, clone your fork:

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

Follow its README for local publish and checks. Keep the project, Program.cs, global.json, Directory.Build.props, NuGet.Config, and builder.yaml at the repository root. The sample has no NuGet package dependencies. Keep the checked-in SDK and package configuration so local and hosted builds use the intended settings. Commit and push any changes before deployment.

Review build and startup settings

Builder publishes the sample and uses builder.yaml to start the resulting app. You do not need to change these settings for your first deployment.

Setting	Sample value
Platform	dotnet, version "10"
Source folder	Repository root
Build	Standard .NET publish
Startup command	dotnet BuilderDotnetSample.dll, set by run.start
Listening address	http://0.0.0.0:8080
App path	/
Health check	/health, returning HTTP 200

The published assembly name must match the startup command. For custom build commands, see the manifest guide. This sample explicitly binds port 8080; changing an environment variable does not change its source-defined listener.

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.

Portal

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.

Builder CLI

Choose a browser or terminal download.

Download in your browser: download Builder CLI 0.0.2 (azure-builder-cli-0.0.2.tgz) from the Private Preview release. Choose the CLI archive, not GitHub's automatic Source code ZIP or tarball.

Download from your terminal: with GitHub CLI installed, run this command in the directory where you want to save the archive:

gh release download builder-cli-v0.0.2-preview.1 --repo microsoft/azure-app-service-builder --pattern "azure-builder-cli-0.0.2.tgz"

The command downloads the CLI archive into the current directory. It refuses to overwrite an existing file; choose another directory if the archive is already present. Release archives use the name azure-builder-cli-<version>.tgz. Use the same portable npm archive on Windows, Linux, and macOS; there is no separate OS/CPU-specific CLI download. Install Node.js 22 or later, including npm.

Install or upgrade using your downloaded archive directly:

npm install --global "<path-to-downloaded-file.tgz>"
builder --version

builder --version should report 0.0.2. Replace <path-to-downloaded-file.tgz> with the local path to your downloaded azure-builder-cli-0.0.2.tgz. For the terminal download above, use ./azure-builder-cli-0.0.2.tgz while in the same directory. Obtain preview access and confirm your approved subscription and location with your preview contact. Do not extract the archive. npm registry access is still required for JavaScript dependencies; access to Builder's private source repository is not required. Installing the CLI does not grant preview access or install the separately distributed agent skills plugin.

The .NET runtime is needed only for local builder manifest commands. You can install Builder and run builder login, builder init, and builder app deploy without .NET. The archive includes the local manifest analyzer and its dependencies, but not the .NET runtime. For optional local manifest validation, install a compatible .NET 10 runtime and keep dotnet on PATH. The analyzer requires Microsoft.NETCore.App 10.0.0 or a compatible runtime. A .NET SDK is not required to use Builder; an existing compatible SDK's included runtime is sufficient. Check installed runtimes with:

dotnet --list-runtimes

Use your installed Builder CLI and GitHub CLI (gh) to connect your source. The App Service Builder GitHub App must have access to your selected repository so Builder can read, build, and deploy its code. See GitHub authorization requirements if access has not been granted.

Reuse a resource group, or create one first with Azure CLI:

az login
az group create --subscription "<subscription-id>" \
  --name "<resource-group>" --location "eastus2"

Replace the subscription and resource-group placeholders with your values. You can use westus2 instead of eastus2. Only this optional resource-group creation step requires Azure CLI and permission to create resource groups. Builder CLI uses the group you select; it does not create it.

If you have not already cloned your prepared fork, copy its HTTPS clone URL from GitHub and run:

git clone "<your-fork-https-url>"
cd "<local-repository-directory>"

Run builder init from inside an initialized Git worktree. GitHub sign-in does not select a local repository. If your terminal is in your home directory, open your cloned app folder or change to it first. Do not initialize Git in your home directory to get past the worktree error.

Run these commands from your app's checkout:

builder --help
builder login
builder account show
builder source login github
builder init

Follow the prompts and confirm the app name, Azure subscription, resource group, approved location, and GitHub source. Select your prepared fork and its pushed branch. Keep the app name, subscription ID, and resource group for the deployment commands below. Initialization creates or reuses the app and connects source; it does not deploy or upload local changes. For explicit automation, see non-interactive setup. builder init does not automatically analyze or modify builder.yaml. Deployment requires builder.yaml at the selected source root. Review your manifest, then commit and push any changes you want to deploy.

Optionally validate the prepared manifest locally without changing files or running repository code. This step requires the separate .NET runtime described in the installation instructions; login, setup, and deployment do not:

builder manifest validate

Request deployment and read the app:

builder app deploy --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"
builder app show --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

Deployment waits by default. After success, use the runtime URL returned by app show for the checks below. For a failure, inspect build and deployment diagnostics. The CLI reference lists selectors, diagnostics, and flags.

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 app

After deployment succeeds, use the returned runtime URL without a trailing slash:

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

With the default greeting, both return HTTP 200. The root body is App Service Builder / dotnet-web: Hello and health is OK, each followed by a newline. Unknown paths return HTTP 404. 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 before verifying again. Variables explains version-captured SAMPLE_GREETING.

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.

Portal

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.

Builder CLI

builder app delete --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

The command asks for confirmation and waits for deletion unless --no-wait is supplied. If you choose not to wait, track the returned operation before treating cleanup as complete.

Related content

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