Continuous deployment to Azure App Service

Article
12/12/2023

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.
(Preview) Under Authentication type, select User-assigned identity for better security. For more information, see frequently asked questions.
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 continues 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.

Frequently asked questions

How does the GitHub Actions build provider work?
How do I configure continuous deployment without basic authentication?
What does the user-assigned identity option do for GitHub Actions?
I see "You do not have sufficient permissions on this app to assign role-based access to a managed identity and configure federated credentials." when I select the user-assigned identity option with GitHub Actions.
How do I deploy from other repositories

How does the GitHub Actions build provider work?

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 user-assigned managed identity or the publishing profile, you can also deploy by using a service principal in Microsoft Entra ID.

How do I configure continuous deployment without basic authentication?

To configure continuous deployment without basic authentication, try using GitHub Actions with the user-assigned identity option.

What does the user-assigned identity option do for GitHub Actions?

When you select user-assigned identity under the GitHub Actions source, Azure creates a user-managed identity for you and federates it with GitHub as an authorized client. This user-managed identity isn't shown in the Identities page for your app.

This automatically created user-managed identity should be used only for the GitHub Actions deployment. Using it for other configurations isn't supported.

I see "You do not have sufficient permissions on this app to assign role-based access to a managed identity and configure federated credentials." when I select the user-assigned identity option with GitHub Actions.

To use the user-assigned identity option for your GitHub Actions deployment, you need the Microsoft.Authorization/roleAssignments/write permission on your app. By default, the User Access Administrator role and Owner role have this permission already, but the Contributor role doesn't.

How do I 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.