draft

Author: v-thepet

articles/app-service/deploy-local-git.md

@@ -1,182 +1,160 @@
 ---
-title: Deploy from a Local Git Repository
-description: Learn how to enable local Git deployment to Azure App Service. One of the simplest ways to deploy code is from your local computer.
+title: Deploy From a Local Git Repository
+description: Learn how to configure and carry out local Git deployment to Azure App Service.
 ms.topic: how-to
-ms.date: 02/29/2024
+ms.date: 06/24/2025
 ms.reviewer: dariac
 ms.custom: devx-track-azurecli, devx-track-azurepowershell
 author: cephalin
 ms.author: cephalin
 ---
-# Deploy to Azure App Service by using Git locally
+# Deploy to Azure App Service by using local Git
 
-This article shows you how to deploy your app to [Azure App Service](overview.md) from a Git repository on your local computer.
+One of the simplest ways to deploy code is from your local computer. This article shows you how to deploy your app to [Azure App Service](overview.md) from a Git repository on your local computer.
 
 > [!NOTE]
-> This deployment method requires [Source Control Manager (SCM) basic authentication](configure-basic-auth-disable.md), which is less secure than [other deployment methods](deploy-authentication-types.md). If local Git deployment doesn't work, you can't configure local Git deployment in the app Deployment Center.
+> Local Git deployment requires [Source Control Manager (SCM) basic authentication](deploy-configure-credentials.md), which is less secure than [other deployment methods](deploy-authentication-types.md). If [basic authentication is disabled]((configure-basic-auth-disable.md)), you can't configure local Git deployment in the app Deployment Center.
 
 ## Prerequisites
 
-To complete the steps that are described in this article:
+To complete the steps in this article:
 
 - [!INCLUDE [quickstarts-free-trial-note](~/reusable-content/ce-skilling/azure/includes/quickstarts-free-trial-note.md)]
 
-- [Install Git](https://www.git-scm.com/downloads).
+- [Install Git](https://www.git-scm.com/downloads), and have a local Git repository with code to deploy.
 
-- Have a local Git repository with code to deploy. To download a sample repository, run the following command in your local terminal window:
+   To clone a sample repository, run the following command in your local terminal window:
 
   ```bash
   git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git
   ```
 
-[!INCLUDE [Prepare repository](../../includes/app-service-deploy-prepare-repo.md)]
+- Configure a deployment user. You can use either [user-scope](deploy-configure-credentials.md#userscope) or [application-scope](deploy-configure-credentials.md#appscope) credentials to deploy your app.
 
-## Configure a deployment user
+  - To configure a *user-scope deployment user* by using the Azure portal or Azure CLI, follow the instructions at [Configure user-scope credentials](#deploy-configure-credentials.md#userscope). You only need a user name, not a password, to create a local Git deployment user. The deployment user name is different from your Azure account user name. You can use the same App Service deployment user for all the apps in your Azure subscription.
+  - An *application-scope user* is app-specific and is created automatically when you create an app. You can get the application-scope user credentials from the **Local Git/FTPS credentials** tab in the **Deployment Center** for your app.
 
-Learn how to [configure deployment credentials for Azure App Service](deploy-configure-credentials.md). You can use either user-scope sign-in information or application-scope sign-in information.
+[!INCLUDE [Prepare repository](../../includes/app-service-deploy-prepare-repo.md)]
 
-## Create a Git-enabled app
+## Create and configure a Git-enabled app
 
-If you already have an App Service app and you want to configure a local Git deployment for the app, see [Configure an existing app](#configure-an-existing-app) instead.
+You can create and configure a Git-enabled app by using Azure CLI, Azure PowerShell, or the Azure portal.
 
 # [Azure CLI](#tab/cli)
 
-Run [az webapp create](/cli/azure/webapp#az-webapp-create) with the `--deployment-local-git` option.
-
-For example:
-
-```azurecli
-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 the example `https://<deployment-username>@<app-name>.scm.azurewebsites.net/<app-name>.git`. Use this URL to deploy your app in the next step.
-
-# [Azure PowerShell](#tab/powershell)
-
-Run [New-AzWebApp](/powershell/module/az.websites/new-azwebapp) from the root of your Git repository.
-
-For example:
-
-```azurepowershell
-New-AzWebApp -Name <app-name>
-```
-
-When your run this cmdlet from a directory that's a Git repository, a Git remote named `azure` for your App Service app is automatically created.
-
-# [Azure portal](#tab/portal)
-
-In the portal, create an app first. Then, set up deployment for the app. For more information, see [Configure an existing app](#configure-an-existing-app).
-
------
-
-## Configure an existing app
+- To create a new web app configured for local Git deployment, run [az webapp create](/cli/azure/webapp#az-webapp-create) with the `--deployment-local-git` option. For example:
 
-If you don't have an app yet, get started with [Create a Git enabled app](#create-a-git-enabled-app).
+  ```azurecli
+  az webapp create --resource-group myResourceGroup --plan myAppServicePlan --name myApp --runtime "NODE:20-lts" --deployment-local-git
+  ```
 
-# [Azure CLI](#tab/cli)
+- To configure local Git deployment for an already-existing app, run [az webapp deployment source config-local-git](/cli/azure/webapp/deployment/source#az-webapp-deployment-source-config-local-git). For example:
 
-Run [az webapp deployment source config-local-git](/cli/azure/webapp/deployment/source#az-webapp-deployment-source-config-local-git).
+  ```azurecli
+  az webapp deployment source config-local-git --name myApp --resource-group myResourceGroup
+  ```
 
-For example:
+Either command produces output that includes a URL, such as:
 
-```azurecli
-az webapp deployment source config-local-git --name <app-name> --resource-group <group-name>
+```output
+Local git is configured with url of 'https://[email protected]/myApp.git'
 ```
+The URL contains the user-scope deployment user name. If there's no user-scope deployment user name, the URL for the app uses the [application-scope user name](deploy-configure-credentials.md#appscope), for example `https://[email protected]/myApp.git`. Use this URL to deploy your app in the next step.
 
-The output contains a URL like the example `https://<deployment-username>@<app-name>.scm.azurewebsites.net/<app-name>.git`. Use this URL to deploy your app in the next step.
+# [Azure PowerShell](#tab/powershell)
 
-> [!TIP]
-> This URL contains the user-scope deployment username. You can [use application-scope sign-in information](deploy-configure-credentials.md#appscope) instead.
+1. Run [New-AzWebApp](/powershell/module/az.websites/new-azwebapp) from the root of your cloned Git repository. For example:
 
-# [Azure PowerShell](#tab/powershell)
+   ```azurepowershell
+   New-AzWebApp -Name myApp
+   ```
 
-Set the `scmType` of your app by running the [Set-AzResource](/powershell/module/az.resources/set-azresource) cmdlet.
+   When you run this cmdlet from a directory that's a Git repository, it automatically creates a Git remote repository named `azure` for your App Service app.
 
-```azurepowershell
-$PropertiesObject = @{
-    scmType = "LocalGit";
-}
+1. Set the `scmType` of your app by running the [Set-AzResource](/powershell/module/az.resources/set-azresource) cmdlet.
 
-Set-AzResource -PropertyObject $PropertiesObject -ResourceGroupName <group-name> `
--ResourceType Microsoft.Web/sites/config -ResourceName <app-name>/web `
--ApiVersion 2015-08-01 -Force
-```
+   ```azurepowershell
+   $PropertiesObject = @{
+       scmType = "LocalGit";
+   }
+   
+   Set-AzResource -PropertyObject $PropertiesObject -ResourceGroupName <group-name> `
+   -ResourceType Microsoft.Web/sites/config -ResourceName <app-name>/web `
+   -ApiVersion 2015-08-01 -Force
+   ```
 
 # [Azure portal](#tab/portal)
 
-1. In the [Azure portal](https://portal.azure.com), go to your app.
-
-1. On the resource menu, select **Deployment Center** > **Settings**.
-1. For **Source**, select **Local Git**, and then select **Save**.
+1. In the [Azure portal](https://portal.azure.com), create an App Service app by following any of the portal-based instructions under **Create your first app** at [Getting started with Azure App Service](getting-started.md). On the **Deployment** tab of the app creation screen, make sure to set **Basic Authentication** to **Enabled**.
+1. When the app is created, select **Go to resource**.
+1. Select **Deployment Center** under **Deployment** in the left navigation menu for the app.
+1. On the **Settings** tab, select **Local Git** from the dropdown list next to **Source**, and then select **Save**.
 
    :::image type="content" source="media/deploy-local-git/enable-portal.png" alt-text="Screenshot that shows how to enable local Git deployment for App Service in the Azure portal.":::
 
-1. In the **Local Git** section, copy the value for **Git Clone Uri** to use later. This URI doesn't contain any sign-in information.
+1. The **Git clone URI** appears under **Local Git** on the **Settings** screen. This URI doesn't contain any sign-in information. Copy the value to use in the next step.
+
+If you already have an app to use, you can configure local Git deployment from the **Settings** tab of the app's **Deployment Center**. Copy the deployment URI.
 
 -----
 
 ## Deploy the web app
 
-1. In a local terminal window, change the directory to the root of your Git repository. Add a Git remote by using the URL from your app. If the method you use doesn't provide a URL, use `https://<app-name>.scm.azurewebsites.net/<app-name>.git` with your app name.
+1. In a local Bash terminal window, change directory to the root of your cloned Git repository. 
+1. Add a Git remote by using the URL returned from configuring your app.
+   - If you used Azure PowerShell`New-AzWebApp` to create the app, the remote is already created.
+   - If the method you used didn't provide a URL, use `https://<app-name>.scm.azurewebsites.net/<app-name>.git` for the URL.
 
    ```bash
    git remote add azure <url>
    ```
 
-    > [!NOTE]
-    > If you [created a Git-enabled app in PowerShell by using New-AzWebApp](#create-a-git-enabled-app), the remote is already created.
-
-1. Push to the Azure remote branch by running `git push azure master`.
-
-   For more information, see [Change the deployment branch](#change-the-deployment-branch).
-
-1. In the **Git Credential Manager** dialog, enter your [user-scope or application-scope sign-in information](#configure-a-deployment-user), not your Azure sign-in information.
-
-   If your Git remote URL already contains your username and password, you aren't prompted to enter them.
-
-1. Review the output. You might see runtime-specific automation, such as MSBuild for ASP.NET, npm install for Node.js, or pip install for Python.
-
-1. In the Azure portal, go to your app to verify that the content is deployed.
+1. Push to the Azure remote branch by running `git push azure main`.
+1. If the **Git Credential Manager** dialog appears, enter your user-scope deployment user name or application-scope sign-in information. If your Git remote URL already contains the sign-in information, you aren't prompted to enter it.
+1. Review the output. You might see runtime-specific automation, such as `MSBuild` for ASP.NET, `npm install` for Node.js, or `pip install` for Python.
+1. If you get errors, see [Troubleshoot deployment](#troubleshoot-deployment) or [Change the deployment branch](#change-the-deployment-branch).
+1. In the Azure portal, verify that the app deployed successfully by selecting the **Default domain** link on the app's **Overview** page. The app should open in a browser tab and display **Hello World!**.
 
 <a name="change-deployment-branch"></a>
-
 ## Change the deployment branch
 
-When you push commits to your App Service repository, App Service deploys the files in the `master` branch by default. Because many Git repositories are moving from `master` to `main`, ensure that you push to the correct branch in the App Service repository in one of two ways:
+When you push commits to your `azure` App Service repository, App Service deploys the files in the `master` branch by default. Many Git repositories, including the sample code repository for this article, use `main` as the default branch. You must ensure that you push to the correct branch in the App Service repository by taking one of the following steps:
 
-- Explicitly deploy to `master` by running a command like in this example:
+- Explicitly deploy to `master` instead of `main` by using the following `push` command:
 
   ```bash
   git push azure main:master
   ```
 
-- Change the deployment branch by setting the `DEPLOYMENT_BRANCH` app setting, and then push commits to the custom branch.
+- Change the `DEPLOYMENT_BRANCH` app setting to `main`, and then push the commit to `main`.
 
-  To do it by using the Azure CLI:
+  - Azure CLI:
 
   ```azurecli
   az webapp config appsettings set --name <app-name> --resource-group <group-name> --settings DEPLOYMENT_BRANCH='main'
   git push azure main
   ```
 
-   You can also change the `DEPLOYMENT_BRANCH` app setting in the Azure portal:
+  Azure portal:
 
-   1. Under **Settings**, select **Environment variables**.
-   1. Add an app setting that has the name `DEPLOYMENT_BRANCH` and the value `main`.
+  1. On the portal page for your app, select **Environment variables** under **Settings** in the left navigation menu.
+  1. On the **Environmental variables** page, select **Add**.
+  1. On the **Add/edit application setting** screen, enter *DEPLOYMENT_BRANCH* for **Name** and *main* for **Value**, and then select **Apply**.
+  1. In the Bash terminal, run `git push azure main`.
 
 ## Troubleshoot deployment
 
-You might see the following common error messages when you use Git to publish to an App Service app in Azure:
+The following common errors might occur when you use local 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 running.|In the Azure portal, start the app. 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 and their associated URLs. Verify that the URL for the `azure` remote is correct. If needed, remove and and then re-create this remote by 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 when you ran `git push` or you haven't set the `push.default` value in `.gitconfig`.|Run `git push` again, and specify the main branch: `git push azure main`.|
-|`Error - Changes committed to remote repository but deployment to website failed.`|You pushed a local branch that doesn't match the app deployment branch on `azure`.|Verify that the current branch is `master`. To change the default branch, use the `DEPLOYMENT_BRANCH` application setting. For more information, see [Change deployment branch](#change-the-deployment-branch). |
-|`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, and specify the main branch: `git push azure main`.|
-|`RPC failed; result=22, HTTP code = 5xx.`|This error might occur if you try to push a large git repository over HTTPS.|Change the git configuration on the local computer to set a higher value for `postBuffer`. 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 that appear before this error for more context. The following causes are known causes of this error and the corresponding `npm ERR!` messages:<br /><br />**Malformed package.json file**: `npm ERR! Couldn't read dependencies.`<br /><br />**Native module doesn't have a binary distribution for Windows**:<br />`npm ERR! \cmd "/c" "node-gyp rebuild"\ failed with 1` <br />or <br />`npm ERR! [modulename@version] preinstall: \make \|\| gmake\` |
+|`Couldn't resolve host 'hostname'`|The address information for the `azure` remote is incorrect.|Use the `git remote -v` command to list all remotes and their associated URLs. Verify that the URL for the `azure` remote is correct. If necessary, remove the incorrect URL by using `git remote remove` and then recreate the remote with 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 when you ran `git push` or you didn't set the `push.default` value in `.gitconfig`.|Run `git push` again and specify the main branch with `git push azure main`.|
+|`Error - Changes committed to remote repository but deployment to website failed.`|You pushed a local branch that doesn't match the app deployment branch on `azure`.|Verify that the current branch is `master`, or change the deployment branch by following the instructions at [Change the deployment branch](#change-the-deployment-branch). |
+|`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, and specify the main branch with `git push azure main`.|
+|`RPC failed; result=22, HTTP code = 5xx.`|You might have tried to push a large Git repository over HTTPS.|Change the git configuration on the local computer to set a higher value for `postBuffer`. 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 added required modules.|Review the `npm ERR!` error messages that appear before this error for more context. The following causes are known causes of this error and the corresponding `npm ERR!` messages:<br />**Malformed package.json file**: `npm ERR! Couldn't read dependencies.`<br />**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\` |
 
 ## Related content