Connect GitHub source

Connect your GitHub repository so App Service Builder can build and deploy the code you push. Each GitHub-backed version records the exact commit it uses.

The GitHub requirements on this page apply only to GitHub-backed deployments. Local-directory and ZIP deployments do not require GitHub sign-in or a GitHub App installation. Use the CLI ZIP walkthrough or the ZIP API walkthrough for those workflows.

Prerequisites

• An existing Builder app and permission to update its source. For a first app, use Portal or Builder CLI.
• A GitHub account with access to the repository and branch you intend to deploy.
• The GitHub App installed with access to that repository, including required organization approvals.
• A pushed builder.yaml at the selected app root.

GitHub authorization

For GitHub-backed deployments, Builder needs two kinds of GitHub access:

• Your GitHub sign-in lets you select repositories you can access.
• The App Service Builder GitHub App needs installation access to the selected repository so Builder can read your code, build it, and deploy your app.

Signing in to GitHub alone does not grant installation access. GitHub sign-in from the Portal requests profile (read:user), organization (read:org), and repository (repo) permissions. Review the consent: GitHub's repo scope grants read/write access to your accessible private repositories, not only the repository selected for deployment.

In the Portal picker, choose your personal account or one of the listed organizations. Repositories whose owners are not listed are unavailable there. Repository and branch discovery does not require the GitHub App to be installed first. After choosing a repository, install the GitHub App or grant its existing installation access if the picker requests it. The installation link suggests your selected account or organization and repository on GitHub's permissions page. Review the target, repository selection, and requested permissions before confirming. During creation, returning to Choose approach rechecks GitHub App access if access was missing. Confirmed access is reused for the current source-selection flow; Refresh access always checks again. Closing the installation window also checks access again. These checks use the selected repository without reloading accounts, repositories, or branches, and keep your current selections. Access-management links opened before selecting a repository use GitHub's general installation flow instead. Organization owners may need to approve both OAuth App access and GitHub App installation separately. Normal sign-in and installation can reuse your GitHub browser session; Change account explicitly requests account selection. OAuth authorization and installation are distinct consent steps; organization policies or SSO can require additional sign-in.

If an organization is missing, expand Organization missing? beneath the organization dropdown during creation or in Settings → Source Control. Select Review GitHub access to open the OAuth App's access settings in a new tab: App Service Builder. Sign in to GitHub with the connected account if prompted, then review organization access. An organization owner may need to approve the OAuth App, or you may need to complete your organization's SSO sign-in. Membership alone does not grant the app access. Local and unrecognized Portal hosts open GitHub Applications and omit the app name; select Authorized OAuth Apps, then the app used by your connection. Return to Builder and select Refresh accounts and repositories in this help section to reload discovery. This is separate from Refresh access, which checks only GitHub App coverage for the selected repository. Opening or closing this tab does not refresh access or confirm approval. Review GitHub access does not restart OAuth or force an organization approval screen. If an organization or repository is missing, follow GitHub access troubleshooting.

Create from a Portal template

To create a new app from a sample without forking it in a separate GitHub tab:

1. In the Portal, select Create and sign in to GitHub in Connect GitHub.
2. Select Start from a template. Search or filter the gallery, choose a sample for your app type, and select Next.
3. In Fork your chosen template, review Destination. Choose your personal account or an organization and enter the repository name. Check the destination even if the form has selected one for you.
4. Select Fork and continue. Wait for Builder to confirm that your fork is ready.
5. Continue through Choose approach and App details as described in the Portal quickstart.

If you already forked or customized a sample, choose Use my repository instead. The template path creates a GitHub fork; it does not replace an existing app's source or guarantee that its runtime is available in your preview location. Some samples need additional credentials or service configuration; review the sample README before deploying.

A fork remains in GitHub if you cancel app creation. If the result of a fork request is unclear, check GitHub or use Check again before creating another copy. For permissions or organization SSO errors, see fork troubleshooting.

Connect GitHub source

Portal

1. In the Portal, open your app's Settings → Source Control.
2. Sign in to GitHub and choose the repository and branch. Install the GitHub App or grant its existing installation access if prompted.
3. Close the installation window to refresh access, or select Refresh access after approval.
4. Use Save to update the desired connection, or Save and deploy to also request deployment.

Portal creation uses the repository root. Source Control preserves the existing app root rather than offering a root editor. Use the CLI --root-directory flag or ARM source.rootDirectory for a monorepo subdirectory. If saving succeeds but deployment cannot start, retry deployment without reconnecting the repository. If you lose the response, refresh and check the saved source before trying again.

Builder CLI

Install Builder CLI using the installation guide. Sign in to Azure with builder login and confirm the account with builder account show.

builder source login github
builder app source connect github --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>" \
  --repository-id "<numeric-repository-id>" \
  --repository "<owner>/<repository>" --branch "<branch>" \
  --root-directory "<app-directory>"

The CLI source flow currently supports github.com. Sign in with the GitHub account that has access to your fork. CLI 0.0.2 requires the numeric repository ID. Using the same GitHub account selected for Builder, look it up with:

gh api --hostname github.com "repos/<owner>/<repository>" --jq .id

In CLI builds with automatic repository lookup, --repository-id is optional: the CLI resolves it from --repository. Neither path requires a local Git worktree. If lookup fails, check the repository name and the selected GitHub account's access. Use builder init for guided create-or-connect setup.

ARM API

Use an authenticated ARM client to PATCH the app URL. For a first connection, supply the selected repository's numeric ID, canonical name, branch, root, and authorized GitHub user credential:

{
  "properties": {
    "source": {
      "provider": "GitHub",
      "id": "<numeric-repository-id>",
      "displayName": "<owner>/<repository>",
      "reference": "<branch>",
      "rootDirectory": ".",
      "repositoryToken": "<authorized-github-user-token>"
    }
  }
}

Use either repositoryToken or a target-bound authorizationToken, not both. Keep credentials out of checked-in request files and logs. Omit the credential only when the source is already authorized and its branch and app root stay unchanged. Changing the branch or rootDirectory requires a fresh authorized GitHub user credential or target-bound authorization token, even within the same repository. Read back the app and confirm that properties.sourceIntegrationState is Configured before deployment. The ARM API deployment guide shows authenticated requests and operation tracking.

Automatic deployment policy

Native push deployment is not ready for use

Use explicit deployment after pushing your commit in this Private Preview. Saving an automatic-deployment policy does not establish working GitHub delivery. Keep automatic deployments off in this preview.

Connecting source alone does not enable automatic deployments. Automatic-deployment policy selects the tracked branch and exact pushed commit; other branches do not match. An in-progress deployment continues while newer waiting pushes replace older ones. If A is deploying when B and C are pushed, only the newest eligible commit C is deployed next; B is skipped. Check deployment history to follow the work that has started. Use the controls below to keep that policy off while deploying explicitly.

Portal

Open Settings → Deployment Settings and leave Automatic deployments off for the explicit-deployment workflow.

Builder CLI

Set the policy off for an existing app:

builder app update --name "<app-name>" --auto-deploy-enabled false \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

ARM API

PATCH properties.source.autoDeploy to false to opt out:

{
  "properties": {
    "source": { "autoDeploy": false }
  }
}

On update, omission or null preserves the existing policy; neither opts the app out.

Source fields and roots

The manifest is read at <app-root>/builder.yaml from the pinned commit. Each component's rootDirectory is relative to that app root, not the original repository root. For example, app source root apps/store and component root web select apps/store/web. Source outside the selected app root is not available to component builds. Use safe relative paths and arrange shared files inside that root. Use . for an app at the repository root. You can change the branch or app root within the connected repository. To use a different repository, create another app. The ARM source reference lists exact fields and update rules. If deployment reports “Source revision does not contain builder.yaml”, follow the missing-manifest recovery steps before retrying.

Deploy changes

Push the intended commit, then deploy explicitly from Source Control or the Versions → Build and deploy menu. Saving another branch changes future source selection, not the already serving version.

After a push, check Deployments and the app URL rather than treating a successful Git push as a running app. Do not wait for native push automation to activate the change in this preview. Inspect any deployment error rather than treating the saved automatic-deployment setting as proof of a running workflow. See feature availability for preview limitations.

Related content

The manifest guide covers component paths within the selected source root. Deployments covers branch, commit, and retained-version selection.