Cara Deploy Hugo ke GitHub Pages

Hugo membangun situs statis dalam hitungan detik, dan GitHub Pages menyajikannya gratis. Yang menyatukan keduanya adalah GitHub Actions — dan di situlah semua kerumitannya berkumpul.

Panduan ini memakai jalur resmi: Actions membangun situs lalu men-deploy langsung ke GitHub Pages, tanpa branch gh-pages. Cara lama yang mendorong hasil build ke branch terpisah masih jalan, tapi tidak perlu lagi, dan menyisakan repositori yang lebih berantakan.

Yang perlu disiapkan

• Situs Hugo yang jalan dengan hugo server.
• Repositori GitHub, publik (atau privat kalau akunmu berbayar).

Belum punya situsnya?

hugo new site situs-saya
cd situs-saya
git init

Langkah 1: Atur baseURL

Ini yang paling sering salah, dan gejalanya khas: situs terbuka tapi tanpa CSS sama sekali.

GitHub Pages menempatkan situsmu di https://namauser.github.io/nama-repo/ — perhatikan subfoldernya. Hugo perlu tahu itu supaya semua tautan dan aset dibuat dengan awalan yang benar.

Di hugo.toml:

baseURL = 'https://namauser.github.io/nama-repo/'
languageCode = 'id'
title = 'Situs Saya'

Garis miring di akhir itu wajib. Tanpa itu, sebagian tautan akan terbentuk salah.

Langkah 2: Aktifkan GitHub Pages lewat Actions

Buka repositorimu → Settings → Pages. Di bagian Source, pilih GitHub Actions.

Ini penting. Kalau pilihannya masih Deploy from a branch, workflow di bawah tidak akan berpengaruh apa-apa dan kamu akan bingung kenapa tidak ada yang terjadi.

Langkah 3: Buat workflow

Bikin berkas .github/workflows/hugo.yml:

name: Deploy Hugo ke GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.148.0
    steps:
      - name: Pasang Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb \
            https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i ${{ runner.temp }}/hugo.deb

      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Build
        env:
          HUGO_ENVIRONMENT: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Unggah artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

Beberapa baris yang menentukan:

• hugo_extended — pakai versi extended, bukan yang biasa. Hampir semua tema modern memakai SCSS, dan hanya versi extended yang bisa mengompilasinya.
• submodules: recursive — wajib kalau temamu dipasang sebagai submodule Git. Tanpa ini, folder tema akan kosong dan build gagal.
• fetch-depth: 0 — mengambil seluruh riwayat Git supaya Hugo bisa membaca tanggal commit terakhir tiap berkas untuk variabel .Lastmod.
• --baseURL dari steps.pages.outputs.base_url — menimpa nilai di hugo.toml dengan URL yang benar-benar dipakai GitHub. Ini membuat workflow tetap benar meski nama repositorimu berubah.
• permissions — ketiga baris itu wajib. Tanpa id-token: write, langkah deploy ditolak.

Langkah 4: Push dan lihat hasilnya

git add .
git commit -m "tambah workflow deploy"
git push origin main

Buka tab Actions di repositorimu. Workflow akan jalan dalam beberapa detik. Kalau hijau, situsmu sudah live di https://namauser.github.io/nama-repo/.

Langkah 5: Pasang domain sendiri

Tambahkan record DNS berikut di penyedia domainmu:

# untuk domain root
A   @   185.199.108.153
A   @   185.199.109.153
A   @   185.199.110.153
A   @   185.199.111.153

# untuk subdomain www
CNAME   www   namauser.github.io

Lalu isi kolom Custom domain di Settings → Pages.

Setelah domain aktif, jangan lupa ubah baseURL di hugo.toml. Detail DNS dan SSL ada di panduan custom domain dan SSL.

Masalah yang sering muncul

Situs tampil tanpa CSS

baseURL salah. Cek tiga hal: apakah sudah memuat nama repositori, apakah diakhiri garis miring, dan — kalau sudah pakai custom domain — apakah subfoldernya sudah dihapus.

Error "module not found" untuk tema

Temamu dipasang sebagai submodule tapi workflow tidak mengambilnya. Pastikan submodules: recursive ada di langkah checkout. Cek juga berkas .gitmodules ikut ter-commit.

Error "TOCSS: failed to transform"

error: TOCSS: failed to transform "main.scss":
this feature is not available in your current Hugo version

Kamu memakai Hugo biasa, bukan extended. Pastikan URL unduhan di workflow memuat kata hugo_extended.

Workflow jalan tapi situs tidak berubah

Source di Settings → Pages masih diset Deploy from a branch. Ubah ke GitHub Actions.

Error permission saat deploy

Error: Resource not accessible by integration

Blok permissions hilang atau tidak lengkap. Ketiganya — contents: read, pages: write, id-token: write — harus ada.

Halaman draft ikut terbit

Jangan tambahkan --buildDrafts di perintah build. Kalau artikel yang seharusnya terbit malah hilang, cek draft: true di frontmatter-nya, atau tanggal date yang masih di masa depan.

Mempercepat build

Hugo sudah cepat, tapi pemrosesan gambar bisa membuat build memanjang dari detik jadi menit. Simpan cache-nya antar-build dengan menambahkan langkah ini sebelum langkah Build:

      - name: Cache resources Hugo
        uses: actions/cache@v4
        with:
          path: |
            resources
            /tmp/hugo_cache
          key: hugo-${{ runner.os }}-${{ hashFiles('**/*.md') }}
          restore-keys: hugo-${{ runner.os }}-

Folder resources/ menyimpan hasil pemrosesan gambar dan SCSS. Dengan cache ini, berkas yang tidak berubah tidak diproses ulang tiap deploy.

Sitemap dan RSS

Hugo membuat keduanya otomatis — /sitemap.xml dan /index.xml — tanpa plugin apa pun. Yang perlu kamu lakukan hanya memastikan baseURL benar, karena URL di dalam sitemap dibentuk dari nilai itu. Ini alasan lain kenapa baseURL yang salah berdampak lebih jauh daripada sekadar CSS yang hilang.

Kalau ada halaman yang tidak ingin masuk sitemap, tambahkan di frontmatter-nya:

---
title: "Halaman Internal"
sitemap:
  disable: true
---

Setelah situsmu live, kirimkan alamat sitemap-nya ke Google Search Console supaya halaman-halamanmu ditemukan lebih cepat.

Batas GitHub Pages yang perlu diketahui

Untuk blog Hugo, batas-batas ini praktis tidak akan tersentuh — situs berisi ratusan artikel pun jarang lewat dari beberapa puluh megabyte. Yang biasanya membuat orang akhirnya pindah adalah kebutuhan akan form kontak atau pencarian sisi server, yang memang tidak bisa dilayani GitHub Pages.

Ringkasan

Untuk project berbasis Vite, workflow-nya mirip tapi konfigurasi base path-nya berbeda — lihat cara deploy Vite ke GitHub Pages.

Menimbang pindah dari GitHub Pages? Lihat GitHub Pages vs Netlify. Gambaran menyeluruhnya ada di panduan lengkap deploy website.