Published on

GitHub Actions for Hugo

How to crate a custom GitHub Actions workflow to publish your Hugo site on GitHub Pages.

This tutorial should help you setup and deploy an Hugo site to GitHub Pages by using GitHub Actions to automatically build and deploy your site.

Create a deploy workflow for your Hugo site

  1. Set baseURL in config.toml with the value https://<USERNAME> for your user repository or https://<USERNAME><REPOSITORY_NAME> for a project repository.

    Unless this is present in your config.toml, your site won’t work.

  2. Create a new file in your project at .github/workflows/deploy.yml and paste in the YAML below.

    name: Deploy
          - main
        runs-on: macos-latest
          - uses: actions/checkout@v3
          - name: Install Hugo
            run: brew install hugo
          - name: Build the Hugo site
            run: hugo --minify
          - name: Upload artifact
            uses: actions/upload-pages-artifact@v1
              path: "public/"
        needs: build
        runs-on: macos-latest
          pages: write
          id-token: write
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v1
  3. On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.

  4. Choose GitHub Actions as the Source of your site and press Save.

  5. Commit the new workflow file and push it to GitHub.

Your site should now be published! When you push changes to your repository, the GitHub Action will automatically deploy them for you.

Refer to the official Hugo documentation for further information.

Use a custom domains

If you’d like to use a custom domain for your GitHub Pages site, you need to:

  1. Set baseURL in config.toml to your custom domain name.

  2. Create a file static/CNAME. Your custom domain name should be the only contents inside CNAME. Since it’s inside static, the published site will contain the CNAME file at the root of the published site, which is a requirement of GitHub Pages.

Refer to the official GitHub documentation for further information.