Hugo GitOps Pipeline

A complete, reusable CI/CD pipeline for Hugo sites with GitOps deployment to Kubernetes. Designed for GDPR-compliant hosting entirely within the EU - no Cloudflare, no Google Fonts, no external CDNs.

New to this project? Check out the Getting Started Guide and the Reference Architecture.

Features

• 🇪🇺 GDPR-Compliant - Self-hosted on Hetzner Cloud (Germany), no data leaves the EU
• 🔄 GitOps Ready - Automated deployment via ArgoCD with gitops-image-replacer
• 🌍 Multi-Environment - Support for dev, staging, QA, production with branch-based deployment
• 📦 Reusable Workflow - Single workflow_call for all your Hugo sites
• 🛠️ Flexible Build Steps - Customize build/lint/test phases or add your own
• 🐳 Container Images - Builder (Node.js + Hugo), Runtime (hardened nginx), Cleanup (registry GC)
• 🔒 Security - Pinned image digests, non-root containers, security headers
• 🏷️ Semantic Versioning - Automated releases with semantic-release

Branch to Environment Mapping

Each branch automatically deploys to its corresponding environment:

flowchart LR
    subgraph Branches
        feature["feature/*"]
        develop["develop"]
        main["main"]
    end

    subgraph Environments
        dev["Dev"]
        staging["Staging"]
        prod["Production"]
    end

    feature -->|"PR"| develop
    develop -->|"merge"| main

    feature -.->|"optional"| dev
    develop -->|"auto deploy"| staging
    main -->|"auto deploy"| prod

    classDef devStyle fill:#1e88e5,stroke:#1565c0,color:#fff
    classDef stagingStyle fill:#fb8c00,stroke:#ef6c00,color:#fff
    classDef prodStyle fill:#43a047,stroke:#2e7d32,color:#fff

    class dev devStyle
    class staging stagingStyle
    class prod prodStyle

Loading

Quick Start

1. Add project.json to your Hugo repo:

{
  "environments": {
    "staging": {
      "when": "^refs/heads/develop$",
      "environment": "staging",
      "gitops": { "repository": "myorg/gitops", "file": "apps/mysite/values-staging.yaml" }
    },
    "production": {
      "when": "^refs/heads/main$",
      "environment": "production",
      "gitops": { "repository": "myorg/gitops", "file": "apps/mysite/values-prod.yaml" }
    }
  }
}

The environment field maps to Hugo's native Configuration Directory - use it to show environment banners, change colors, or adjust settings per environment.

2. Add workflow .github/workflows/ci-cd.yml:

name: CI/CD
on:
  push:
    branches: [main, develop]
  workflow_dispatch:

jobs:
  pipeline:
    uses: slauger/hugo-gitops-pipeline/.github/workflows/hugo-gitops.yml@v1
    with:
      registry: registry.example.com
      image_name: my-hugo-site
    secrets: inherit

3. Configure secrets and push.

Documentation

Guide	Description
Getting Started	Step-by-step setup guide
Configuration	All project.json options
Build Steps	Customize build phases
Environments	Multi-environment setup
Architecture	GDPR-compliant reference architecture

License

MIT