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.
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.
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.
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>
Note
If you are using a linux app-service-plan, you need to add this parameter: --runtime python|3.7
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
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>
Push to the Azure remote with
git push azure main
.In the Git Credential Manager window, enter your deployment user password, not your Azure sign-in password.
Review the output. You may see runtime-specific automation, such as MSBuild for ASP.NET,
npm install
for Node.js, andpip install
for Python.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):
In the Azure portal, search for and select App Services.
Select your Azure App Service app and select Deployment Center in the left menu.
On the Deployment Center page, select Local Git, and then select Continue.
On the Build provider page, select Azure Pipelines (Preview), and then select Continue.
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.
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.
On the Summary page, review the settings, and then select Finish.
When the Azure Pipeline is ready, copy the Git repository URL from the Deployment Center page to use in the next step.
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>
Push to the Azure remote with
git push azure main
.On the Git Credential Manager page, sign in with your visualstudio.com username. For other authentication methods, see Azure DevOps Services authentication overview.
Once deployment is finished, view the build progress at
https://<azure_devops_account>.visualstudio.com/<project_name>/_build
, and the deployment progress athttps://<azure_devops_account>.visualstudio.com/<project_name>/_release
.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:
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\ |