Local Git deployment to Azure App Service

• 06/18/2019
• 8 minutes to read
• • c
  • j
  • M
  • m
  • G
  • +2

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
  

• Use Azure Cloud Shell using the Bash environment.

  

• If you prefer, install the Azure CLI to run CLI reference commands.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.
  • When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with the Azure CLI.
  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

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.

To customize your deployment, include a .deployment file in the repository root. For more information, see Customize deployments and Custom deployment script.

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

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. In the Azure portal, search for and select App Services.

2. Select your Azure App Service app and select Deployment Center in the left menu.

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

   

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

   

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

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

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

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

   

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

10. Push to the Azure remote with git push azure main.

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

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

13. 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 used to run your app. Therefore, the deployment can fail because of locked files. The app may also behave unpredictably during deployment, because not all the files updated at the same time. This is undesirable for a customer-facing app. There are a few different ways to avoid these issues:

• Run your app from the ZIP package directly without unpacking it.
• Stop your app or enable offline mode for your app during deployment. For more information, see Deal with locked files during deployment.
• Deploy to a staging slot with auto swap enabled.

Troubleshoot deployment

You may see the following common error messages when you use Git to publish to an App Service app in Azure:

Additional resources

• 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)