Hugo on Azure with Static Web Apps

I have few web sites based on Hugo framework currently running as Web Apps on Azure App Service Plan at the Shared tier: one of the least expensive options with the ability to use a custom domain names, you can learn more about the differences beteween hosting plans here.
At the time I renovated my sites with Hugo 3 years ago this was the easiest path to move to Azure. Now I want to improve my static web sites in few areas: #1 automate the deployment workflow and #2 use less resources. #3 I also want to leverage GitHub Actions.

GitHub Actions

As GitHub documentation describes it:

GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub.

GiHub Actions are a powerful way to define YAML based pipelines triggered by events. There is an excellent post describing how to use GitHub Actions to publish Hugo websites and from this source I discovered the GitHub Actions for Hugo, available from the Actions marketplace.

Azure Static Web Apps

Azure Static Web Apps is a service that automatically builds and deploys full stack web apps to Azure from a code repository: exactly what I needed for objectives #1, #2 and also #3 as GitHub Actions are supported.
These are the steps to reach my goal:

• Create an Azure Static Web Apps
• Integrate GitHub Actions with Azure Static Web Apps
• Trigger my GitHub Actions only when needed
• Publish my updates to a separate environment before moving into production

Let's start with the activities!

Hugo in Azure Static Web Apps

The value of Azure Static Web Apps sits in its close integration with the code repository and the CI/CD pipeline. You can find a Hugo focused walkthough here: for the sake of brevity let's say I have an existing GitHub repository containing my Hugo site.
As you can see from the picture above, I am connecting the newly created Static Web App to my GitHub Account and the main branch of my web site with Hugo repository.

Ready to use GitHub Actions

This integration does create a new GitHub Action workflow in my repository, well explained in the documentation. The main steps are the following:

on:
  push:
    branches: [main]
    paths-ignore: '.github/workflows/**'
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches: [main]
    paths-ignore: '.github/workflows/**'

With the controls on trigger paths-ignore: '.github/workflows/**' I prevent the workflow from running when I edit my Actions.
The workflow continues with the definition of build & deploy job triggered by push or PR:

build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v0.0.1-preview
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GRAY_DUNE_09D67E003 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "api" # Api source code path - optional
          output_location: "public" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

The job triggered once a PR close event is detected is similar:

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v0.0.1-preview
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GRAY_DUNE_09D67E003 }}
          action: "close"

Apart from the secrets defined while provisioning the Azure Static Web App and used to deploy the built Hugo site, the interesting part is the usage of the GitHub Action Azure/static-web-apps-deploy@v0.0.1-preview: what is it?

What is Oryx?

The GitHub Actions workflow, created in the project repository, does use the Azure Static Web Apps Deploy GitHub action from the marketplace. This reusable Action utilizes Oryx system to build both static applications and Azure Functions for API and then deploys it. You can find more information on Oryx repository at https://github.com/microsoft/Oryx and on how it does detect & build Hugo applications.

Verify changes before publishing

As the only author of my web sites, I am tempted to expedite the process to post something new: open VS Code, change the markdown files, git commit & push to the main branch, followed by build & deploy to the public site! It seems simpler only if you do not account for any error: forcing yourself to follow a more rigorous process, while automating it as much as possible, is the way to go.
With branch protection rules you can demand that a pull request on a branch must be reviewed before merging into the protected branch, main in my case, preventing the author from pushing directly into it. Even by requesting the minimum of approvers, I am 1 short on my team of one. For the time being I will force myself to start PRs and not leverage branch protection. In the previous screenshot I created a branch for my commit and started a PR. This is the pull request I am starting, the final goal is to merge that branch into the main one. What does happen when we start a PR?

PRs and Environments

Azure Static Web Apps is so well integrated with the GitHub Actions that it translate pull requests (PR) into staging environments, so you can review the changes before publishing it in front of your users.
We just created a branch and started a PR: the following screenshot show what the workflow, created for us by Azure Static Web Apps, does provide. The GitHub Action has been triggered and is going to build and publish to a staging environment. Once complete, we are presented with the url of the Azure Static Web Apps environment In the Azure Portal we see the staging environment listed for our Azure Static Web App.
We have the chance to verify our changes: Once we are ready to apply these to the public site, we go back to the PR and merge it into the main branch. The GitHub Action will then start two job runs to close the pull request, remove the staging environment, build and publish the Hugo site on the production environment.

At last!

In this article we explored the great CI/CD integration provided by Azure Static Web App with GitHub Actions, for Hugo static site and for many other frameworks as well.
With Azure Static Web App I will decommission the App Service that is currently supporting my static sites, while keeping the ability to have custom domain and free TLS certificate!.
As my sites are personal/hobby related, I will be able to use it for free!