Continuous deployment to Azure App Service

Article
03/24/2022

Azure App Service enables continuous deployment from GitHub, Bitbucket, and Azure Repos repositories by pulling in the latest updates.

Note

The Development Center (Classic) page in the Azure portal, an earlier version of the deployment functionality, was deprecated in March 2021. This change doesn't affect existing deployment settings in your app, and you can continue to manage app deployment from the Deployment Center page in the portal.

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 use Visual Studio, let Visual Studio create a repository for you. Your project will immediately be ready for deployment via Git.

Configure the deployment source

In the Azure portal, go to the management page for your App Service app.
In the left pane, select Deployment Center. Then select Settings.
In the Source box, select one of the CI/CD options:

Select the tab that corresponds to your build provider to continue.

GitHub Actions is the default build provider. To change the provider, select Change provider > App Service Build Service (Kudu) > OK.

Note

To use Azure Pipelines as the build provider for your App Service app, configure CI/CD directly from Azure Pipelines. Don't configure it in App Service. The Azure Pipelines option just points you in the right direction.
If you're deploying from GitHub for the first time, select Authorize and follow the authorization prompts. If you want to deploy from a different user's repository, select Change Account.
After you authorize your Azure account with GitHub, select the Organization, Repository, and Branch to configure CI/CD for. If you can’t find an organization or repository, you might need to enable more permissions on GitHub. For more information, see Managing access to your organization's repositories.
When GitHub Actions is selected as the build provider, you can select the workflow file you want by using the Runtime stack and Version dropdown lists. Azure commits this workflow file into your selected GitHub repository to handle build and deploy tasks. To see the file before saving your changes, select Preview file.

Note

App Service detects the language stack setting of your app and selects the most appropriate workflow template. If you choose a different template, it might deploy an app that doesn't run properly. For more information, see How the GitHub Actions build provider works.
Select Save.

New commits in the selected repository and branch now deploy continuously into your App Service app. You can track the commits and deployments on the Logs tab.

Disable continuous deployment

In the Azure portal, go to the management page for your App Service app.
In the left pane, select Deployment Center. Then select Settings > Disconnect:
By default, the GitHub Actions workflow file is preserved in your repository, but it will continue to trigger deployment to your app. To delete the file from your repository, select Delete workflow file.
Select OK.

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. So the deployment can fail because of locked files. The app might also behave unpredictably during deployment because the files aren't all updated at the same time. This behavior is undesirable for a customer-facing app. There are a few ways to avoid these issues:

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

How the GitHub Actions build provider works

The GitHub Actions build provider is an option for CI/CD from GitHub. It completes these actions to set up CI/CD:

Deposits a GitHub Actions workflow file into your GitHub repository to handle build and deploy tasks to App Service.
Adds the publishing profile for your app as a GitHub secret. The workflow file uses this secret to authenticate with App Service.
Captures information from the workflow run logs and displays it on the Logs tab in your app's Deployment Center.

You can customize the GitHub Actions build provider in these ways:

Customize the workflow file after it's generated in your GitHub repository. For more information, see Workflow syntax for GitHub Actions. Just make sure that the workflow deploys to App Service with the azure/webapps-deploy action.
If the selected branch is protected, you can still preview the workflow file without saving the configuration and then manually add it into your repository. This method doesn't give you log integration with the Azure portal.
Instead of using a publishing profile, deploy by using a service principal in Azure Active Directory.

Authenticate by using a service principal

This optional configuration replaces the default authentication with publishing profiles in the generated workflow file.

Generate a service principal by using the az ad sp create-for-rbac command in the Azure CLI. In the following example, replace <subscription-id>, <group-name>, and <app-name> with your own values:
```
az ad sp create-for-rbac --name "myAppDeployAuth" --role contributor \
                            --scopes /subscriptions/<subscription-id>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name> \
                            --sdk-auth
```
Important

For security, grant the minimum required access to the service principal. The scope in the previous example is limited to the specific App Service app and not the entire resource group.
Save the entire JSON output for the next step, including the top-level {}.
In GitHub, in your repository, select Settings > Secrets > Add a new secret.
Paste the entire JSON output from the Azure CLI command into the secret's value field. Give the secret a name like AZURE_CREDENTIALS.

In the workflow file generated by the Deployment Center, revise the azure/webapps-deploy step to look like the following example (which is modified from a Node.js workflow file):

- name: Sign in to Azure 
  # Use the GitHub secret you added.
  uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}
- name: Deploy to Azure Web App
  # Remove publish-profile.
  uses: azure/webapps-deploy@v2
  with:
    app-name: '<app-name>'
    slot-name: 'production'
    package: .
- name: Sign out of Azure.
  run: |
    az logout

Deploy from other repositories

For Windows apps, you can manually configure continuous deployment from a cloud Git or Mercurial repository that the portal doesn't directly support, like GitLab. You do that by selecting External Git in the Source dropdown list. For more information, see Set up continuous deployment using manual steps.