Configuring Your Repository & CI/CD

Connect a static site repository (Hugo, Astro, Jekyll, SvelteKit) to LightCMS and automate deployments with CI/CD.

Connecting your static site to LightCMS requires only two ingredients: a GitHub repository containing your content files and an automated CI/CD workflow that builds and deploys your website whenever changes are committed.

Follow this guide to structure your repository, install the LightCMS GitHub App, and set up automated deployments.

1. Structure Your Content Repository

LightCMS works natively with any static site generator (SSG) that stores content as Markdown (.md or .mdx) files with YAML front matter.

A typical repository layout looks like this:

my-blog-repo/
├── content/               # or src/content/blog/ in Astro
│   ├── hello-world.md
│   └── my-second-post.md
├── .github/
│   └── workflows/
│       └── deploy.yml     # Automated build & deploy pipeline
├── package.json
└── astro.config.mjs       # or config.toml for Hugo

Standard Front Matter Header

LightCMS reads and writes YAML front matter metadata at the top of your Markdown files. A standard header includes:

---
title: My First Article
description: A short overview of the article for SEO and cards.
date: 2026-10-14T10:00:00Z
draft: false
tags:
  - technology
  - blogging
---

Your article content begins here...

2. Install the LightCMS GitHub App

To allow LightCMS to read your files and commit newly written articles:

  1. Sign in to your LightCMS instance using your GitHub account.
  2. Navigate to your dashboard and click Connect Repository (or Install GitHub App).
  3. GitHub will prompt you to select which account or organization to install the app on.
  4. You can grant access to All repositories or select Only select repositories to limit access strictly to your blog repo.
  5. Once authorized, your repository will appear in your LightCMS dashboard.

3. Configure Automated CI/CD Deployments

Every time you hit Publish or Save in LightCMS, the app commits your updated Markdown file directly to your specified Git branch. To turn those commits into live website updates, configure a GitHub Actions workflow.

Example A: Astro Deployment (GitHub Pages / Static Host)

Create .github/workflows/deploy.yml in your repository:

name: Deploy Website

on:
  push:
    branches:
      - main

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

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

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build static site
        run: npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

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

Example B: Hugo Deployment (Cloudflare Pages or Vercel)

If you are using Hugo, platforms like Cloudflare Pages, Netlify, or Vercel can build your repository automatically when they receive a GitHub push event:

  1. Connect your GitHub repository directly to Cloudflare Pages or Vercel.
  2. Set the build command to hugo --minify.
  3. Set the build output directory to public.
  4. Whenever LightCMS pushes a new post to main, the hosting platform automatically re-generates and deploys your site globally in seconds.

4. Hosting Platform Recommendations

Several reliable platforms offer generous free tiers for hosting static sites:

5. Verify the Publishing Loop

Once your repository is configured and CI/CD is in place:

  1. Open your LightCMS editor and create a new post.
  2. Add your content and click Publish.
  3. Check the Actions tab on your GitHub repository — you will see your CI/CD workflow triggered by the LightCMS commit.
  4. Within a minute or two, your new post is live on your website.

#configuration#github#cicd#lightcms

Keep reading