Local Git deployment to Azure App Service

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 an Azure free 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.
Functions	See Continuous deployment for Azure Functions.

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 use Visual Studio, let Visual Studio create a repository for you. Your project will immediately be ready for deployment via 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.

Azure CLI

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.azurewebsites.net/<app-name>.git. Use this URL to deploy your app in the next step.

Azure PowerShell

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.

Azure portal

In the portal, you need to create an app first, then configure deployment for it. See Configure an existing app.

Configure an existing app

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

Azure CLI

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.azurewebsites.net/<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.

Azure PowerShell

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

Azure portal

1. In the Azure portal, navigate to your app's management page.

2. From the left menu, select Deployment Center > Settings. Select Local Git in Source, then select Save.

   

3. In the Local Git section, copy the Git Clone Uri for later. This Uri doesn't contain any credentials.

Deploy the web app

1. 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.azurewebsites.net/<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.

2. Push to the Azure remote with git push azure master (see Change deployment branch).

3. 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.

4. 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.

5. 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 Environment variables under Settings and adding a new App 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\

More resources

• App Service build server (Project Kudu documentation)
• Continuous deployment to Azure App Service
• Sample: Create a web app and deploy code from a local Git repository (Azure CLI)
• Sample: Create a web app and deploy code from a local Git repository (PowerShell)