Local Git deployment to Azure App Service

Article
07/08/2024

This how-to guide shows you how to deploy your app to Azure App Service from a Git repository on your local computer.

Note

When SCM basic authentication is disabled, Local Git deployment doesn't work, and you can't configure Local Git deployment in the app's Deployment Center.

Prerequisites

To follow the steps in this how-to guide:

If you don't have an Azure subscription, create a trial account before you begin.
Install Git.
Have a local Git repository with code you want to deploy. To download a sample repository, run the following command in your local terminal window:
```
git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git
```

Prepare your repository

To get automated builds from Azure App Service build server, make sure that your repository root has the correct files in your project.

Runtime	Root directory files
ASP.NET (Windows only)	.sln, .csproj, or default.aspx
ASP.NET Core	.sln or .csproj
PHP	index.php
Ruby (Linux only)	Gemfile
Node.js	server.js, app.js, or package.json with a start script
Python	.py, requirements.txt, or runtime.txt*
HTML	default.htm, default.html, default.asp, index.htm, index.html, or iisstart.htm
WebJobs	<job_name>/run.<extension> under App_Data/jobs/continuous for continuous WebJobs, or App_Data/jobs/triggered for triggered WebJobs. For more information, see Kudu WebJobs documentation.

To customize your deployment, include a .deployment file in the repository root. For more information, see Customize deployments and Custom deployment script.

Note

If you develop in Visual Studio, let Visual Studio create a repository for you. The project is immediately ready to be deployed by using Git.

Configure a deployment user

See Configure deployment credentials for Azure App Service. You can use either user-scope credentials or application-scope credentials.

Create a Git enabled app

If you already have an App Service app and want to configure local Git deployment for it, see Configure an existing app instead.

Run az webapp create with the --deployment-local-git option. For example:

az webapp create --resource-group <group-name> --plan <plan-name> --name <app-name> --runtime "<runtime-flag>" --deployment-local-git

The output contains a URL like: https://<deployment-username>@<app-name>.scm.chinacloudsites.cn/<app-name>.git. Use this URL to deploy your app in the next step.

Run New-AzWebApp from the root of your Git repository. For example:

New-AzWebApp -Name <app-name>

When your run this cmdlet from a directory that's a Git repository, it automatically creates a Git remote to your App Service app for you, named azure.

Configure an existing app

If you don't have an app yet, see Create a Git enabled app instead.

Run az webapp deployment source config-local-git. For example:

az webapp deployment source config-local-git --name <app-name> --resource-group <group-name>

The output contains a URL like: https://<deployment-username>@<app-name>.scm.chinacloudsites.cn/<app-name>.git. Use this URL to deploy your app in the next step.

Tip

This URL contains the user-scope deployment username. If you like, you can use the application-scope credentials instead.

Set the scmType of your app by running the Set-AzResource cmdlet.

$PropertiesObject = @{
    scmType = "LocalGit";
}

Set-AzResource -PropertyObject $PropertiesObject -ResourceGroupName <group-name> `
-ResourceType Microsoft.Web/sites/config -ResourceName <app-name>/web `
-ApiVersion 2015-08-01 -Force

Deploy the web app

In a local terminal window, change the directory to the root of your Git repository, and add a Git remote using the URL you got from your app. If your chosen method doesn't give you a URL, use https://<app-name>.scm.chinacloudsites.cn/<app-name>.git with your app name in <app-name>.
```
git remote add azure <url>
```
Note

If you created a Git-enabled app in PowerShell using New-AzWebApp, the remote is already created for you.
Push to the Azure remote with git push azure master (see Change deployment branch).
In the Git Credential Manager window, enter your user-scope or application-scope credentials, not your Azure sign-in credentials.

If your Git remote URL already contains the username and password, you won't be prompted.
Review the output. You might see runtime-specific automation, such as MSBuild for ASP.NET, npm install for Node.js, and pip install for Python.
Browse to your app in the Azure portal to verify that the content is deployed.

Change deployment branch

When you push commits to your App Service repository, App Service deploys the files in the master branch by default. Because many Git repositories are moving away from master to main, you need to make sure that you push to the right branch in the App Service repository in one of two ways:

Deploy to master explicitly with a command like:
```
git push azure main:master
```
Change the deployment branch by setting the DEPLOYMENT_BRANCH app setting, then push commits to the custom branch. To do it with Azure CLI:
```
az webapp config appsettings set --name <app-name> --resource-group <group-name> --settings DEPLOYMENT_BRANCH='main'
git push azure main
```
You can also change the DEPLOYMENT_BRANCH app setting in the Azure portal, by selecting Configuration under Settings and adding a new Application Setting with a name of DEPLOYMENT_BRANCH and value of main.

Troubleshoot deployment

You might see the following common error messages when you use Git to publish to an App Service app in Azure:

Message	Cause	Resolution
`Unable to access '[siteURL]': Failed to connect to [scmAddress]`	The app isn't up and running.	Start the app in the Azure portal. Git deployment isn't available when the web app is stopped.
`Couldn't resolve host 'hostname'`	The address information for the `azure` remote is incorrect.	Use the `git remote -v` command to list all remotes, along with the associated URL. Verify that the URL for the `azure` remote is correct. If needed, remove and recreate this remote using the correct URL.
`No refs in common and none specified; doing nothing. Perhaps you should specify a branch such as 'main'.`	You didn't specify a branch during `git push`, or you haven't set the `push.default` value in `.gitconfig`.	Run `git push` again, specifying the main branch: `git push azure main`.
`Error - Changes committed to remote repository but deployment to website failed.`	You pushed a local branch that doesn't match the app deployment branch on `azure`.	Verify that current branch is `master`. To change the default branch, use `DEPLOYMENT_BRANCH` application setting (see Change deployment branch).
`src refspec [branchname] does not match any.`	You tried to push to a branch other than main on the `azure` remote.	Run `git push` again, specifying the main branch: `git push azure main`.
`RPC failed; result=22, HTTP code = 5xx.`	This error can happen if you try to push a large git repository over HTTPS.	Change the git configuration on the local machine to make the `postBuffer` bigger. For example: `git config --global http.postBuffer 524288000`.
`Error - Changes committed to remote repository but your web app not updated.`	You deployed a Node.js app with a package.json file that specifies additional required modules.	Review the `npm ERR!` error messages before this error for more context on the failure. The following are the known causes of this error, and the corresponding `npm ERR!` messages: Malformed package.json file: `npm ERR! Couldn't read dependencies.` Native module doesn't have a binary distribution for Windows: `npm ERR! \cmd "/c" "node-gyp rebuild"\ failed with 1` or `npm ERR! [modulename@version] preinstall: \make \\|\\| gmake\`