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.

Prerequisites

To follow the steps in this how-to guide:

  • If you don't have an Azure subscription, create a 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 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.azurewebsites.net/<app-name>.git. Use this URL to deploy your app in the next step.

Configure an existing app

If you haven't created 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.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.

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.

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

Troubleshoot deployment

You may 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.
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\

Additional resources