Skip to main content

Deploy your first app with Builder CLI

In this quickstart, you deploy a small HTTP app from your GitHub fork with App Service Builder. Start with the recommended sample or keep another sample you have already chosen. Use Builder CLI to connect source, deploy, verify the running app, and delete the test app.

Prerequisites​

  • Private Preview access supplied by your preview contact. Use development/test workloads only; do not deploy production workloads.
  • The portable CLI archive linked under Install the CLI.
  • An authorized Azure subscription and an available region. Reuse a resource group or create one with the optional Azure CLI step below.
  • Node.js 22 or later, Git, and GitHub CLI (gh) on your computer.
  • For optional local manifest validation, a compatible .NET 10 runtime; a .NET SDK is not required.
  • A GitHub account that can fork the sample and authorize source access.
  • Confirmed Node.js 24 availability for the recommended sample, or confirmed support for your selected alternative.

The CLI's local Node.js requirement is separate from the app's hosted runtime. See access and sign-in if your accounts or preview access are not set up.

Install the 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

Prepare your source​

The recommended starting point is the minimal Node.js HTTP sample. It includes application code and a root builder.yaml for Node.js 24, a listener on port 8080, and a /health deployment check.

Confirm your selected runtime and version are available for your preview location before starting. Local manifest validation and a successful build do not establish runtime availability; see target runtime availability.

Open the repository and choose Fork to create your own copy. Keep the sample files and root builder.yaml together. Use your fork's account, repository name, and branch in the steps below. Commit and push any changes; Builder deploys GitHub commits, not uncommitted local files.

Want a different sample? Choose another published sample or follow a language tutorial. Bringing your own code? Add a builder.yaml at your app's source root before deploying. It tells Builder how to build and start your app. The published samples already include this file. Use the manifest guide to create it yourself or with the Builder agent skill. Commit and push builder.yaml with your code. Keep your existing repository rather than replacing it with a sample; source roots explains apps in subdirectories.

Create and deploy the app​

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.

Verify the hosted app​

After deployment succeeds, open the app's returned runtime URL. For the recommended Node.js sample with its default greeting, the page shows App Service Builder / nodejs-web: Hello. Its /health endpoint returns HTTP 200 with body OK followed by a newline.

You can also check both endpoints from a terminal, using the returned URL without a trailing slash:

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

Both requests should return HTTP 200 for the recommended sample. If you chose another sample or changed its behavior, use its README for the expected response and health path; PHP uses /health.php, for example. Check the active version and source revision as well as the response. A saved source connection, ready build, or accepted request is not a completed deployment.

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.

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 language tutorials to understand runtime-specific build and startup settings. Use the CLI reference to look up commands and options. Use the Portal quickstart if you prefer the same journey without local CLI tools. For setup or deployment help, check support availability.

Last updated on