Deployment on GitHub Pages

If your source is hosted on GitHub, GitHub Pages can build and publish the site with a single Actions workflow. The consuming site needs Hugo Extended but does not need Node.js, npm, PostCSS, or a generated deployment branch.

Project sites use a URL such as https://<OWNER>.github.io/<REPOSITORY>/; user and organization sites use https://<OWNER>.github.io/. Custom domains are also supported.

Prepare the repository

Push the complete site source to GitHub and confirm that this command succeeds from the repository root:

hugo --gc --minify

Set the site’s baseURL to its production URL, or pass the Pages URL with Hugo’s --baseURL option in the workflow. A project site must include the repository path; otherwise CSS, JavaScript, and other resources will resolve from the wrong location.

Add the Pages workflow

Create .github/workflows/pages.yml with the following contents. Keep HUGO_VERSION aligned with a version validated by the theme.

 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
17env:
18  GO_VERSION: 1.25.5
19  HUGO_VERSION: 0.164.0
20
21jobs:
22  build:
23    runs-on: ubuntu-latest
24    steps:
25      - uses: actions/checkout@v7
26        with:
27          fetch-depth: 0
28          submodules: recursive
29      - uses: actions/setup-go@v6
30        with:
31          go-version: ${{ env.GO_VERSION }}
32      - name: Install Hugo Extended
33        run: |
34          curl -L -o hugo.deb \
35            "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
36          sudo dpkg -i hugo.deb
37      - uses: actions/configure-pages@v6
38        id: pages
39      - name: Build
40        run: >-
41          hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
42      - uses: actions/upload-pages-artifact@v5
43        with:
44          path: public
45
46  deploy:
47    environment:
48      name: github-pages
49      url: ${{ steps.deployment.outputs.page_url }}
50    runs-on: ubuntu-latest
51    needs: build
52    steps:
53      - name: Deploy
54        id: deployment
55        uses: actions/deploy-pages@v5

If the theme is installed as a Git submodule, submodules: recursive checks it out before Hugo runs. A complete offline archive can instead commit or restore the site-owned themes/oink/ directory as part of the repository or build input.

Enable GitHub Pages

In the repository settings, open Pages. Under Build and deployment, set Source to GitHub Actions. Push the workflow to main, then follow its first run in the repository’s Actions tab.

The workflow uploads only the generated public/ directory and publishes it through the Pages deployment API. It does not maintain a gh-pages branch.

For other authentication, domain, and permission options, see GitHub’s Pages documentation and Hugo’s GitHub hosting guide.