Local Git Deployment to Azure App Service

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

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

To follow the steps in this how-to guide:

  • Install Git.
  • Maintain a local Git repository with code you want to deploy.

To use a sample repository to follow along, run the following command in your local terminal window:

git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git

Prepare your repository

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 (Windows only) *.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, you can include a .deployment file in the repository root. For more information, see Customizing deployments and Custom deployment script.

Note

Be sure to git commit all the changes you want to deploy.

Open Azure Cloud Shell

Azure Cloud Shell is a free, interactive shell that you can use to run the steps in this article. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. Just select the Copy button to copy the code, paste it in Cloud Shell, and then press Enter to run it. There are a few ways to open Cloud Shell:

Select Try It in the upper-right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/bash
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell in the portal

Create a deployment user

In the Cloud Shell, create deployment credentials with the az webapp deployment user set command. This deployment user is required for FTP and local Git deployment to a web app. The user name and password are account level. They are different from your Azure subscription credentials.

In the following example, replace <username> and <password> (including brackets) with a new user name and password. The user name must be unique within Azure. The password must be at least eight characters long, with two of the following three elements: letters, numbers, symbols.

az webapp deployment user set --user-name <username> --password <password>

You should get a JSON output, with the password shown as null. If you get a 'Conflict'. Details: 409 error, change the username. If you get a 'Bad Request'. Details: 400 error, use a stronger password.

You create this deployment user only once; you can use it for all your Azure deployments.

Note

Record the user name and password. You need them to deploy the web app later.

Enable Git for your app

To enable Git deployment for an existing App Service app, run az webapp deployment source config-local-git in the Cloud Shell.

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

To create a Git-enabled app instead, run az webapp create in the Cloud Shell with the --deployment-local-git parameter.

az webapp create --name <app_name> --resource-group <group_name> --plan <plan_name> --deployment-local-git

The az webapp create command should give you something similar to the following output:

Local git is configured with url of 'https://<username>@<app_name>.scm.azurewebsites.net/<app_name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<app_name>.azurewebsites.net",
  "deploymentLocalGitUrl": "https://<username>@<app_name>.scm.azurewebsites.net/<app_name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

Deploy your project

Back in the local terminal window, add an Azure remote to your local Git repository. Replace <url> with the URL of the Git remote that you got from Enable Git for your app.

git remote add azure <url>

Push to the Azure remote to deploy your app with the following command. When prompted for a password, make sure that you enter the password you created in Configure a deployment user, not the password you use to log in to the Azure portal.

git push azure master

You may see runtime-specific automation in the output, such as MSBuild for ASP.NET, npm install for Node.js, and pip install for Python.

Once deployment is finished, your app in the Azure portal should now have a record of your git push in the Deployment options page.

Browse to your app to verify that the content is deployed.

Troubleshooting

The following are common errors or problems when using Git to publish to an App Service app in Azure:


Symptom: Unable to access '[siteURL]': Failed to connect to [scmAddress]

Cause: This error can happen if the app isn't up and running.

Resolution: Start the app in the Azure portal. Git deployment is unavailable when the Web App is stopped.


Symptom: Couldn't resolve host 'hostname'

Cause: This error can happen if the address information entered when creating the 'azure' remote was incorrect.

Resolution: 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.


Symptom: No refs in common and none specified; doing nothing. Perhaps you should specify a branch such as 'master'.

Cause: This error can happen if you don't specify a branch during git push, or if you haven't set the push.default value in .gitconfig.

Resolution: Run git push again, specifying the master branch. For example:

git push azure master

Symptom: src refspec [branchname] does not match any.

Cause: This error can happen if you try to push to a branch other than master on the 'azure' remote.

Resolution: Run git push again, specifying the master branch. For example:

git push azure master

Symptom: RPC failed; result=22, HTTP code = 5xx.

Cause: This error can happen if you try to push a large git repository over HTTPS.

Resolution: Change the git configuration on the local machine to make the postBuffer bigger

git config --global http.postBuffer 524288000

Symptom: Error - Changes committed to remote repository but your web app not updated.

Cause: This error can happen if you deploy a Node.js app with a package.json file that specifies additional required modules.

Resolution: Additional messages with 'npm ERR!' should be logged before this error, and can provide additional context on the failure. The following are known causes of this error and the corresponding 'npm ERR!' message:

  • Malformed package.json file: npm ERR! Couldn't read dependencies.
  • Native module that does not have a binary distribution for Windows:

    • npm ERR! \cmd "/c" "node-gyp rebuild"\ failed with 1

      OR

    • npm ERR! [modulename@version] preinstall: \make || gmake\

Additional Resources