GitHub Pages provides an excellent free hosting solution for Hugo website. In this guide, We will walk through the process of setting up continuous deployment using GitHub Actions.

Prerequisites

• A Hugo website ready to deploy
• A GitHub account
• Git installed on local machine
• Basic familiarity with Git commands

Step 1: Prepare Repository

1. Create a new repository on GitHub named foo.github.io

2. Initialize Hugo project as a Git repository:

1cd my-hugo
2git init
3git add .
4git commit -m "Initial commit"

3. Add GitHub repository as the remote origin:

1git remote add origin https://github.com/foo/foo.github.io.git

Step 2: Configure Hugo

1. Update config.toml (or config.yaml) file. Make sure baseURL matches GitHub Pages URL:

1baseURL = "https://foo.github.io/"

2. Commit these changes:

1git add config.toml
2git commit -m "Update baseURL for GitHub Pages"

Step 3: Set Up GitHub Actions

1. Create a new directory structure in the repository:

1mkdir -p .github/workflows

2. Create a new file named .github/workflows/hugo.yaml with the following content:

 1name: Deploy Hugo site to Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13concurrency:
14  group: "pages"
15  cancel-in-progress: false
16
17defaults:
18  run:
19    shell: bash
20
21jobs:
22  build:
23    runs-on: ubuntu-latest
24    env:
25      HUGO_VERSION: 0.121.0
26    steps:
27      - name: Install Hugo CLI
28        run: |
29          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
30          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
31      - name: Install Dart Sass
32        run: sudo snap install dart-sass
33      - name: Checkout
34        uses: actions/checkout@v4
35        with:
36          submodules: recursive
37          fetch-depth: 0
38      - name: Setup Pages
39        id: pages
40        uses: actions/configure-pages@v4
41      - name: Build with Hugo
42        env:
43          HUGO_ENVIRONMENT: production
44          HUGO_ENV: production
45        run: |
46          hugo \
47            --gc \
48            --minify \
49            --baseURL "${{ steps.pages.outputs.base_url }}/"          
50      - name: Upload artifact
51        uses: actions/upload-pages-artifact@v2
52        with:
53          path: ./public
54
55  deploy:
56    environment:
57      name: github-pages
58      url: ${{ steps.deployment.outputs.page_url }}
59    runs-on: ubuntu-latest
60    needs: build
61    steps:
62      - name: Deploy to GitHub Pages
63        id: deployment
64        uses: actions/deploy-pages@v3

Step 4: Enable GitHub Pages

1. Go to the repository settings on GitHub
2. Navigate to “Pages” in the sidebar
3. Under “Build and deployment”:
   • Source: Select “GitHub Actions”
   • Branch: main

Step 5: Push the Changes

Push all the changes to GitHub:

1git add .
2git commit -m "Add GitHub Actions workflow"
3git push -u origin main

Step 6: Verify Deployment

1. Go to the repository’s “Actions” tab on GitHub
2. We should see our workflow running
3. Once completed, visit https://foo.github.io to see our site live

Troubleshooting

If our site isn’t displaying correctly:

1. Check the GitHub Actions logs for any errors
2. Verify our baseURL in the Hugo configuration
3. Make sure our repository name exactly matches foo.github.io
4. Confirm that GitHub Pages is enabled and using GitHub Actions

Maintaining Site

1. Make changes to the content locally
2. Commit the changes
3. Push to GitHub

The GitHub Action will automatically build and deploy the updates.

Best Practices

1. Always test changes locally using hugo server before pushing
2. Use branch-based workflow for major changes
3. Keep our Hugo version in the workflow file up to date
4. Remember to push the theme submodules if we’re using them

That’s It!

We now have a fully automated deployment pipeline for our Hugo site using GitHub Pages and GitHub Actions. Any changes we push to our main branch will automatically trigger a new build and deployment.

Please refer to the official Hugo documentation and GitHub Pages documentation for more detailed information.