Skip to main content

Use the App Service Builder canvas

The App Service Builder canvas gives you a visual workspace alongside Copilot chat to prepare an app, inspect its configuration, and guide separately approved GitHub and Azure operations. This quickstart installs the canvas for one project and checks a local app before deployment. The canvas is part of App Service Builder Private Preview for development and test workloads.

Prerequisites​

  • A GitHub Copilot app host with native extension-canvas support on Windows, macOS, or Linux, and Node.js 22 or later. The download does not include the host, and a CLI-only host without a canvas renderer cannot display the panel.
  • A disposable local Git repository opened as a project in that host. Keep the test installation out of your application's commits.
  • Git for local repository operations. GitHub CLI is needed only when connecting GitHub; Azure CLI 2.61 or later is needed for Azure access. Required tools must be visible to the app process.
  • Before cloud operations: your own authorized Private Preview account, subscription, resource group, and confirmed location/runtime. Review feature availability before deploying.

Opening the panel, selecting a local folder, and inspecting source do not require GitHub or Azure sign-in. Native canvas operations do not require a source build, npm installation, or Builder CLI installation. The separate Builder agent plugin provides instructions for coding agents; installing it does not install this canvas.

Download the package​

  1. Open the canvas releases and choose the newest canvas preview. This filtered page separates canvas packages from Builder CLI releases.
  2. Download that release's attached canvas ZIP and canvas-testing-guide.md into the same directory. Use these assets, not GitHub's automatic source-code ZIP or tarball. Keep both assets from the same release.

Extract the ZIP using the command in that release's guide. Use the included guide for release-specific requirements, installation, and update instructions. The release also includes SHA256SUMS.txt for optional download-integrity troubleshooting.

Install for one test project​

The native extension and alternative plugin inside the archive are two installation options. Choose one, not both. The following project-scoped installation does not change your global Copilot configuration.

  1. Review the package's license notices. Stop if the project already has an App Service Builder extension or any of the packaged skills; do not overwrite them or delete recovery records.
  2. Follow the project installation instructions in the downloaded canvas-testing-guide.md. Set PACKAGE to the absolute path of that release's extracted package directory and PROJECT to the absolute path of your disposable Git repository. Run the guide's guarded copy block, which checks for existing files and symbolic links before copying the native extension to .github/extensions/ and the five skills to .github/skills/. Do not bypass a failed preflight check.
  3. Save your work, then fully quit and reopen the Copilot app to activate the package. Reopening the panel or restarting only the conversation can leave an older backend running. Verify the runtime/build information against the release notes before testing. If your host documents a complete provider-reload action, follow that host's instructions.

If your host supports complete local-plugin import, you can instead import the extracted plugin/app-service-builder directory. Do not also copy the native extension. Generic CLI plugin installation is not a substitute for a host that supports this canvas package.

Open the canvas​

In the test project's Copilot chat, ask:

Open the App Service Builder canvas in Azure mode. Do not connect accounts,
run my app, publish or deploy anything.

Confirm that the panel opens and its runtime/build information matches the distribution and runtime identity supplied with your downloaded release. If the canvas is missing, check extension discovery and the host's provider logs. Do not launch extension.mjs directly, build a replacement page, or reuse another tester's localhost URL.

Check a local app​

  1. Select From your computer and choose the disposable app folder you intend to inspect. Local selection should not require GitHub sign-in.
  2. Select Check configuration to inspect the app and its Builder configuration. Use the manifest guide to understand static/web components, build outputs, startup, and health checks.
  3. Select Review app to discuss findings with Copilot, or explicitly choose Skip agent review. Skipping records the app as not reviewed; it does not pass the review or remove concrete blockers.
  4. Review proposed file changes before approving them. Dependency installation and application execution need their own approval. If you run a local preview, check the actual app response before accepting it.

You can also choose Start from scratch to build a local app with your agent, or Start from template to select a sample. Selecting a template does not create a fork or deploy anything. Review the GitHub owner and repository before approving a fork; reuse an appropriate existing fork rather than creating duplicates or resetting customized source. The sample catalog explains app shapes and runtime choices.

Reopen the session to confirm that your workflow progress is retained. A successful local check or preview is not a cloud deployment.

Publish and deploy only when ready​

Before approving any cloud write, confirm the exact GitHub account, repository, branch, Azure account, subscription, resource group, app, and region. GitHub source access and Azure management have separate permissions. Copilot sign-in grants neither. Normal Azure charges for separately owned resources may apply.

Treat these as separate steps with separate effects:

  • Review local source and builder.yaml, preserving unrelated changes.
  • Commit and publish the intended source to GitHub.
  • Create or select the Azure app and authorize its source.
  • Request deployment, track completion, and verify the actual app URL.

Reuse an already-correct source connection rather than reconnecting unnecessarily. If a create, fork, or deployment request times out or has an unknown outcome, inspect the existing operation and retained progress before retrying. Do not assume an unknown result means the write failed. An accepted request, a built version, or a branch commit observed before deployment does not prove that the intended app is serving.

For a complete first-app cloud journey, follow the Portal or Builder CLI quickstart. Source control explains authorization; deployments explains completion and verification. Open the Portal to manage the same app outside the canvas.

Manage a deployed test app​

After you select an existing app, Manage app keeps Open app, Open in portal, and Edit locally together. Edit locally helps you find a registered checkout or gives you instructions for opening one; it does not clone a repository or create a coding session. Publish your intended changes to the app's connected branch before deploying.

Select Deploy updates to check the source and review the target, then confirm the deployment. If an earlier operation is unresolved, follow its saved progress instead of submitting another request. Check the app URL after deployment succeeds. The canvas cannot compare the deployed commit with your branch, so it does not tell you whether updates are available.

Clean up the test​

In Settings > Manage saved workflows, review any disposable inactive history before confirming cleanup. Ordinary selected histories are permanently deleted; unresolved cloud histories are retained for recovery and target protection. Do not delete recovery records to bypass an unresolved operation.

Disabling or uninstalling the provider does not delete app files, GitHub repositories, Azure resources, or saved recovery records. Delete only resources you intentionally created for the test after confirming their identity and dependencies. Use the Portal cleanup steps or CLI cleanup steps for a disposable Builder app; do not delete a shared resource group.

Report a problem​

Use the public Builder issue forms. Include App Service Builder canvas, your installed distribution and runtime identity, host version, OS, selected journey, expected behavior, and minimal reproduction steps. Distinguish simulated results from live-service observations.

Issues and attachments are public. Redact screenshots and logs; omit credentials, device codes, account/contact details, subscription/resource IDs, private repository details, source contents, saved workflows, and recovery records. Report vulnerabilities through the repository's private security-reporting guidance. For setup or usage help rather than a bug report, check support availability.

Last updated on