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

To get automatic builds from the Azure App Service Kudu 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 develop in Visual Studio, let Visual Studio create a repository for you. The project is immediately ready to be deployed by using Git.

Open Azure Cloud Shell

Azure Cloud Shell is an interactive shell environment hosted in Azure and used through your browse. Azure Cloud Shell allows you to use either bash or PowerShell shells to run a variety of tools to work with Azure services. Azure Cloud Shell comes pre-installed with the commands to allow you to run the content of this article without having to install anything on your local environment.

To run any code contained in this article on Azure Cloud Shell, open a Cloud Shell session, use the Copy button on a code block to copy the code, and paste it into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. Pasted text is not automatically executed, so press Enter to run code.

You can launch Azure Cloud Shell with:

Option Example/Link
Select Try It in the upper-right corner of a code block. This doesn't automatically copy text to Cloud Shell. Example of Try It for Azure Cloud Shell
Open Azure Cloud Shell in your browser.
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell button in the Azure portal

Deploy with Kudu builds

The easiest way to enable local Git deployment for your app with the Kudu build server is to use the Cloud Shell.

Configure a deployment user

In the Azure Cloud Shell, configure deployment credentials with the az webapp deployment user set command. You use this deployment user for FTP and local Git deployment to a web app. The username and password are account level. They're different from your Azure subscription credentials.

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

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

You 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. The deployment username must not contain ‘@’ symbol for local Git pushes.

You configure this deployment user only once. You can use it for all your Azure deployments.

Note

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

Note

Instead of account-level credentials, you can also deploy with app-level credentials, which are automatically generated for each app.

Enable local Git with Kudu

To enable local Git deployment for your app with the Kudu build server, 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

Deploy your project

Back in the local terminal window, add an Azure remote to your local Git repository. Replace <username> with the deployment user from Configure a deployment user and <app-name> with the app name from Enable Git for your app.

git remote add azure https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git

Note

To deploy with app-level credentials instead, get the credentials specific to your app by running the following command in the Cloud Shell:

az webapp deployment list-publishing-credentials -n <app-name> -g <group-name> --query scmUri --output tsv

Then use the command output to run git remote add azure <url> like above.

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

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

Deploy with Azure DevOps builds

Note

For App Service to create the necessary Azure Pipelines in your Azure DevOps Services organization, your Azure account must have the role of Owner in your Azure subscription.

To enable local Git deployment for your app with the Kudu build server, navigate to your app in the Azure portal.

In the left navigation of your app page, click Deployment Center > Local Git > Continue.

Click Azure Pipelines (Preview) > Continue.

In the Configure page, configure a new Azure DevOps organization, or specify an existing organization. When finished, click Continue.

Note

If you want to use an existing Azure DevOps organization that is not listed, you need to link the Azure DevOps Services organization to your Azure subscription.

Depending on the pricing tier of your App Service plan, you may also see a Deploy to staging page. Choose whether to enable deployment slots, then click Continue.

In the Summary page, verify your options and click Finish.

It takes a few minutes for the Azure DevOps Services organization to be ready. When it's ready, copy the Git repository URL in the deployment center.

Back in the local terminal window, add an Azure remote to your local Git repository. Replace <url> with the URL you got from the last step.

git remote add vsts <url>

Push to the Azure remote to deploy your app with the following command. When prompted by Git Credential Manager, sign in with your visualstudio.com user. For additional authentication methods, see Azure DevOps Services authentication overview.

git push vsts master

Once deployment is finished, you can find the build progress at https://<vsts_account>.visualstudio.com/<project_name>/_build and the deployment progress at https://<vsts_account>.visualstudio.com/<project_name>/_release.

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

What happens to my app during deployment?

All the officially supported deployment methods have one thing in common: they make changes to the files in the /home/site/wwwroot folder of your app. These are the same files that are run in production. Therefore, the deployment can fail due to locked files, or the app in production may have unpredictable behavior during deployment because not all the files are updated simultaneously. There are a few different ways to avoid these issues:

Troubleshooting Kudu deployment

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 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\

Additional resources