Deployment

GitHub Pages

Deploy your Lithos site to GitHub Pages with automated CI/CD.
Properties5
Aliases #GitHub Pages Deployment
Is BaseNo
Iconi-lucide-github
Order2
Tags #deployment #github #ci-cd

GitHub Pages provides free static hosting directly from your repository. Ideal for open-source projects, personal documentation, and small to medium sites.

Repository Setup

  1. Create a GitHub repository for your Lithos project
  2. Push your project (excluding node_modules and .output)
  3. Enable GitHub Pages in Settings > Pages
  4. Choose GitHub Actions as the source
Subdirectory Hosting

For hosting at username.github.io/project, configure the base URL:

NUXT_APP_BASE_URL=/project/

GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Generate static site
        run: npm run generate
        env:
          NUXT_APP_BASE_URL: /your-repo-name/

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

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

Customization

Branch Name

Replace main with your default branch if different:

on:
  push:
    branches: [master]  # or your branch name

Environment Variables

Add secrets in Settings > Secrets and variables > Actions:

- name: Generate static site
  run: npm run generate
  env:
    NUXT_APP_BASE_URL: ${{ vars.BASE_URL }}
    NUXT_PUBLIC_SITE_URL: ${{ vars.SITE_URL }}

Custom Domain

  1. Add your domain in Settings > Pages > Custom domain
  2. Create a CNAME file in public/ with your domain:
docs.example.com
  1. Configure DNS:
    • For apex domain: A records pointing to GitHub's IPs
    • For subdomain: CNAME record pointing to username.github.io

Troubleshooting

Blank Pages or Missing Assets

Check the base URL configuration. Open browser console and look for 404 errors. The fix is ensuring NUXT_APP_BASE_URL matches your GitHub Pages URL structure.

Build Failures

Check the Actions tab for detailed logs. Common issues:

  • Node version mismatches (use Node 20+)
  • Missing environment variables
  • Content errors not caught locally

Size Limits

GitHub Pages has a 1GB total size limit and 100MB per file limit. For larger sites, consider Netlify or Vercel.