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 automatic builds from 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.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Cloud Shell lets you use either bash or PowerShell to work with Azure services. You can use the Cloud Shell pre-installed commands to run the code in this article without having to install anything on your local environment.

To launch Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Launch Cloud Shell.
  2. Select the Copy button on a code block to copy the code.
  3. Paste the code into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS.
  4. Press Enter to run the code.

Deploy with Kudu build server

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

Configure a deployment user

FTP and local Git can deploy to an Azure web app by using a deployment user. Once you configure your deployment user, you can use it for all your Azure deployments. Your account-level deployment username and password are different from your Azure subscription credentials.

To configure the deployment user, run the az webapp deployment user set command in Azure Cloud Shell. Replace <username> and <password> with a deployment user username and password.

  • The username must be unique within Azure, and for local Git pushes, must not contain the ‘@’ symbol.
  • 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>

The JSON output shows the password 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.

Record your username and password to use to deploy your web apps.

Get the deployment URL

To get the URL to enable local Git deployment for an existing app, run az webapp deployment source config-local-git in the Cloud Shell. Replace <app-name> and <group-name> with the names of your app and its Azure resource group.

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

Or, to create a new Git-enabled app, run az webapp create in the Cloud Shell with the --deployment-local-git parameter. Replace <app-name>, <group-name>, and <plan-name> with the names for your new Git app, its Azure resource group, and its Azure App Service plan.

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

Either command returns 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.

Instead of using this account-level URL, you can also enable local Git by using app-level credentials. Azure App Service automatically generates these credentials for every app.

Get the app credentials by running the following command in the Cloud Shell. Replace <app-name> and <group-name> with your app's name and Azure resource group name.

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

Use the URL that returns to deploy your app in the next step.

Deploy the web app

  1. Open a local terminal window to your local Git repository, and add an Azure remote. In the following command, replace <url> with the deployment user-specific URL or app-specific URL you got from the previous step.

    git remote add azure <url>
    
  2. Push to the Azure remote with git push azure master.

  3. In the Git Credential Manager window, enter your deployment user password, not your Azure sign-in password.

  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.

Deploy with Azure Pipelines builds

If your account has the necessary permissions, you can set up Azure Pipelines (Preview) to enable local Git deployment for your app.

  • Your Azure account must have permissions to write to Azure Active Directory and create a service.

  • Your Azure account must have the Owner role in your Azure subscription.

  • You must be an administrator in the Azure DevOps project you want to use.

To enable local Git deployment for your app with Azure Pipelines (Preview):

  1. Navigate to your Azure App Service app page in the Azure portal, and select Deployment Center in the left menu.

  2. On the Deployment Center page, select Local Git, and then select Continue.

    Select Local Git, and then select Continue

  3. On the Build provider page, select Azure Pipelines (Preview), and then select Continue.

    Select Azure Pipelines (Preview), and then select Continue.

  4. On the Configure page, configure a new Azure DevOps organization, or specify an existing organization, and then select Continue.

    Note

    If your existing Azure DevOps organization isn't listed, you may need to link it to your Azure subscription. For more information, see Define your CD release pipeline.

  5. Depending on your App Service plan pricing tier, you may see a Deploy to staging page. Choose whether to enable deployment slots, and then select Continue.

  6. On the Summary page, review the settings, and then select Finish.

  7. When the Azure Pipeline is ready, copy the Git repository URL from the Deployment Center page to use in the next step.

    Copy the Git repository URL

  8. In your local terminal window, add an Azure remote to your local Git repository. In the command, replace <url> with the URL of the Git repository that you got from the previous step.

    git remote add azure <url>
    
  9. Push to the Azure remote with git push azure master.

  10. On the Git Credential Manager page, sign in with your visualstudio.com username. For other authentication methods, see Azure DevOps Services authentication overview.

  11. Once deployment is finished, view the build progress at https://<azure_devops_account>.visualstudio.com/<project_name>/_build, and the deployment progress at https://<azure_devops_account>.visualstudio.com/<project_name>/_release.

  12. Browse to your app in the Azure portal to verify that the content is deployed.

What happens to my app during deployment?

All the officially supported deployment methods make changes to the files in the /home/site/wwwroot folder of your app. These files are the same ones that are run in production. Therefore, the deployment can fail because of locked files. The app in production may also behave unpredictably during deployment, because not all the files updated at the same time. There are a few different ways to avoid these issues:

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 'master'. 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 master branch: git push azure master.
src refspec [branchname] does not match any. You tried to push to a branch other than master on the 'azure' remote. Run git push again, specifying the master branch: git push azure master.
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