Continuous deployment to Azure App Service

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, which is the old deployment experience, will be deprecated in March, 2021. This change will not affect any existing deployment settings in your app, and you can continue to manage app deployment in the Deployment Center page.

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 develop in Visual Studio, let Visual Studio create a repository for you. The project is immediately ready to be deployed by using Git.

Configure deployment source

  1. In the Azure portal, navigate to the management page for your App Service app.

  2. From the left menu, click Deployment Center > Settings.

  3. In Source, select one of the CI/CD options.

    Shows how to choose deployment source in Deployment Center for Azure App Service

Choose the tab that corresponds to your selection for the steps.

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

    Note

    To use Azure Pipelines as the build provider for your App Service app, don't configure it in App Service. Instead, configure CI/CD directly from Azure Pipelines. The Azure Pipelines option just points you in the right direction.

  2. If you're deploying from GitHub for the first time, click Authorize and follow the authorization prompts. If you want to deploy from a different user's repository, click Change Account.

  3. Once you authorize your Azure account with GitHub, select the Organization, Repository, and Branch to configure CI/CD for.

  4. When GitHub Actions is the chosen build provider, you can select the workflow file you want with the Runtime stack and Version dropdowns. Azure commits this workflow file into your selected GitHub repository to handle build and deploy tasks. To see the file before saving your changes, click 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 may deploy an app that doesn't run properly. For more information, see How the GitHub Actions build provider works.

  5. Click Save.

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

Disable continuous deployment

  1. In the Azure portal, navigate to the management page for your App Service app.

  2. From the left menu, click Deployment Center > Settings > Disconnect.

    Shows how to disconnect your cloud folder sync with your App Service app in the Azure portal.

  3. By default, the GitHub Actions workflow file is preserved in your repository, but it will continue to trigger deployment to your app. To delete it from your repository, select Delete workflow file.

  4. Click 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. 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:

How the GitHub Actions build provider works

The GitHub Actions build provider is an option for CI/CD from GitHub, and does the following 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 in the Logs tab in your app's Deployment Center.

You can customize the GitHub Actions build provider in the following 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, then manually add it into your repository. This method doesn't give you the log integration with the Azure portal.
  • Instead of a publishing profile, deploy using a service principal in Azure Active Directory.

Authenticate with a service principal

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

  1. Generate a service principal with 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.

  2. Save the entire JSON output for the next step, including the top-level {}.

  3. In GitHub, browse your repository, select Settings > Secrets > Add a new secret.

  4. Paste the entire JSON output from the Azure CLI command into the secret's value field. Give the secret a name like AZURE_CREDENTIALS.

  5. In the workflow file generated by the Deployment Center, revise the azure/webapps-deploy step with code 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, such as GitLab. You do it by choosing External Git in the Source dropdown. For more information, see Set up continuous deployment using manual steps.

More resources