Problem with deploying Hugo site to GitHub Pages, 404 after deployment

support
1

Hello everyone,

I am working on a Hugo site that runs perfectly locally with a the theme ananke (no complex configurations). I’m trying to deploy this site to GitHub Pages using a GitHub Actions workflow, but I am encountering an issue: the action runs successfully without errors, but when I visit my site’s URL on GitHub Pages, I get a 404 error.

Problem Details:

What I have tried:

  • I have verified that GitHub Pages is configured correctly in the repository settings.
  • My .yml workflow file looks correct, but here is the content for reference:
''' 
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # ou 'main' si ta branche principale s'appelle 'main'

permissions:
  contents: write  # Autorise à pousser dans le repo

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.145.0'
          extended: true

      - name: Build the site
        run: hugo --minify

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.MY_GITHUB_TOKEN }}  # Utilise le Personal Access Token que tu as ajouté comme secret
          publish_dir: ./public
          publish_branch: gh-pages  # Cette ligne est ajoutée pour spécifier la branche de déploiement
          force_orphan: true
'''

Question:

  • Do you have any idea what could be causing this 404?
  • Is there something missing in the GitHub Pages configuration or the GitHub Actions workflow?

Thank you in advance for your help!

2

Use the recommended workflow… works great.

https://gohugo.io/host-and-deploy/host-on-github-pages/

3

Thanks,

I tried the method.
Locally, my page displays correctly, but on GitHub Pages, it looks like there’s no CSS.

I can’t figure out where the issue is coming from. The only log I found in the DevTools is:

lockdown-install.js:1 Removing unpermitted intrinsics
papermod-ongp/:2 Failed to find a valid digest in the 'integrity' attribute for resource 'https://wilonweb.github.io/papermod-ongp/assets/css/stylesheet.6da9a63….css' with computed SHA-256 integrity '9J1myq6eoP1D8h8p5xqNPihFF+13Dyqob6ASlTrTye8='. The resource has been blocked.
favicon.ico:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon.ico 404 (Not Found)
favicon-16x16.png:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon-16x16.png 404 (Not Found)
favicon-32x32.png:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon-32x32.png 404 (Not Found)
favicon.ico:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon.ico 404 (Not Found)
favicon-32x32.png:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon-32x32.png 404 (Not Found)
favicon-16x16.png:1 
 GET https://wilonweb.github.io/papermod-ongp/favicon-16x16.png 404 (Not Found)
4

mmh, GitHub action log may reveal something

[details=“Build with Hugo”]

Start building sites … 
hugo v0.147.1-95666fc5a4fd2d87528a1a69d562e0538a97062a+extended linux/amd64 BuildDate=2025-05-01T13:50:04Z VendorInfo=gohugoio

WARN  found no layout file for "html" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.[/details]

you have added the theme as a submodule, but there’s no .gitmodules file in the root of your repo

if you have one locally:

  • add it
  • commit it
  • push it, push it real good
  • check the site

if you don’t have one (i doubt that) ask google how to repair a missing .gitmodules

p.s. when using a build workflow I would not commit the public folder

5 
git rm -rf public/
git rm -rf themes/*
git rm .hugo_build.lock
git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod
touch .gitignore

Then paste this into the .gitignore file you just created:

.hugo_build.lock
node_modules/
public/
resources/

Then:

git add -A
git commit -m "Fix theme and repo"
git push
6

Thanks a lot! :folded_hands:
In the end, the problem came from my workflow: it didn’t fetch the submodule, so the theme wasn’t deployed. Everything’s working now!