Hugo, GitHub, and Firebase

When I was looking at hosting options for my website recently, I settled on Google's Firebase Hosting, which I found to be well-documented and easy to set up. While the Firebase documentation is excellent, it doesn't cover the hugo build step; this short article plugs that gap.

I'm assuming you already have a Google account (needed to log in to Firebase) and that you have a hugo site with a GitHub remote. If you're completely new to Hugo you'll want go through the Quick Start Guide before reading any further.

For the Firebase setup, I started by logging in to the Firebase Console and creating a project for the site.

Then back at the shell, I installed the Firebase CLI.

Next I followed the Deploy to live and preview channels via GitHub pull requests guide, which just involved running firebase init hosting in the project directory and following some prompts. The key for the GitHub integration is to answer "yes" to the question Set up automatic builds and deploys with GitHub?.

The Firebase CLI creates a service account that will be used by the GitHub Action to deploy the site, and adds an authentication token as a GitHub Secret. It also added the following files to the repository which I then committed:

new file:   .firebaserc
new file:   .github/workflows/firebase-hosting-merge.yml
new file:   .github/workflows/firebase-hosting-pull-request.yml
new file:   firebase.json

The github/workflows/firebase-hosting-merge.yml looks like this:

# This file was auto-generated by the Firebase CLI
# https://github.com/firebase/firebase-tools

name: Deploy to Firebase Hosting on merge
'on':
  push:
    branches:
      - main
jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_HUGO_DEMO_15C1F }}'
          channelId: live
          projectId: hugo-demo-15c1f
        env:
          FIREBASE_CLI_PREVIEWS: hostingchannels

We can see that it is checking out the repository then using action-hosting-deploy to do the deployment. We need to insert the hugo build step between these two steps. We use actions-hugo to install hugo into the GitHub Actions virtual machine, then run hugo to build our site before it is deployed. If we have included the theme as a submodule, we also need to configure the checkout step to fetch submodules. Our updated action looks like this:

# This file was auto-generated by the Firebase CLI
# https://github.com/firebase/firebase-tools

name: Deploy to Firebase Hosting on merge
'on':
  push:
    branches:
      - main
jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          lfs: true
          fetch-depth: 1
      - run: git lfs checkout
      - uses: peaceiris/actions-hugo@v2
      - run: hugo --baseURL https://hugo-demo-15c1f.web.app
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_HUGO_DEMO_15C1F }}'
          channelId: live
          projectId: hugo-demo-15c1f
        env:
          FIREBASE_CLI_PREVIEWS: hostingchannels

The --baseURL is of the form https://${PROJECT_NAME}.web.app and is the URL where Firebase will serve our site. You can optionally configure a custom domain for Firebase Hosting; see Connect a custom domain for details.

We need to make the same changes to .github/workflows/firebase-hosting-pull-request.yml then we can commit these two files.

Note: The URL for the Firebase preview channel (where the site is deployed to preview a merge request) contains a random component, so the base URL we've hard-coded isn't quite right. This could cause problems as any absolute URLs that appear in the generated site will point to the live deployment. This hasn't been a problem for me in practice as in my setup hugo is generating very few absolute URLs.

Shortly after we push these changes the GitHub action will run and our site will appear at https://hugo-demo-15c1f.web.app.

This article was updated on 2021-03-09 to add the lfs: true option to the checkout step, and to add the git lfs checkout step to the actions. This was needed after enabling large file support on the repository and adding some JPEG files.