Automate with GitHub Actions

Set up continuous integration and deployment (CI/CD) for your Bengal site. Automate builds, run tests, and deploy to production with GitHub Actions.

When to Use This Guide

You want automated builds on every commit
You need to run tests before deployment
You want to deploy to production automatically
You're setting up preview deployments for pull requests
You need to validate content and links before publishing

Prerequisites

Bengal installed
A Git repository on GitHub
A hosting provider account (GitHub Pages, Netlify, Vercel, etc.)
Basic knowledge of YAML

:::tip Performance Tip For faster CI builds, use Python 3.14t (free-threading build) instead of 3.14. This enables true parallel processing and can reduce build times by 1.5-2x on multi-core runners. Updatepython-version: '3.14t'in your workflows. :::

Steps

Basic Build Workflow

Create.github/workflows/build.yml:

name: Build Site

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install Bengal
        run: pip install bengal

      - name: Build site
        run: bengal build --environment production --strict

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: public/
          retention-days: 1

Deploy to GitHub Pages

Automatically deploys to GitHub Pages when you push tomain. Requires GitHub Pages enabled in repository settings.

Create.github/workflows/deploy.yml:

name: Deploy to Production

on:
  push:
    branches: [main]

# Required permissions for GitHub Pages deployment
permissions:
  contents: read
  pages: write
  id-token: write

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          cache: 'pip'

      - name: Install Bengal
        run: pip install bengal

      - name: Build site
        run: bengal build --environment production --strict --clean-output

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: './public'

  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

Note: Enable GitHub Pages in your repository settings: Settings > Pages > Source: GitHub Actions.

Preview Deployments

Builds preview versions for pull requests. Comments on PRs when build succeeds. Artifacts available in workflow run.

Create.github/workflows/preview.yml:

name: Preview Deployment

on:
  pull_request:
    branches: [main]

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          cache: 'pip'

      - name: Install Bengal
        run: pip install bengal

      - name: Build site
        run: bengal build --environment preview

      - name: Upload preview artifacts
        uses: actions/upload-artifact@v4
        with:
          name: preview-site
          path: public/
          retention-days: 7

      - name: Comment PR with preview
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '✅ Preview build successful! Download artifacts from workflow run.'
            })

Add Validation and Testing

Add health checks to your CI pipeline:

# .github/workflows/test.yml
name: Test and Validate

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install Bengal
        run: pip install bengal

      - name: Validate configuration
        run: bengal config doctor

      - name: Check for broken links
        run: bengal health linkcheck

      - name: Build with strict mode
        run: bengal build --strict --verbose

Caching for Faster Builds

Cache dependencies and build artifacts to reduce workflow time. Add these steps after Python setup:

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.14'
    cache: 'pip'  # Automatically caches pip packages

- name: Cache Bengal build cache
  uses: actions/cache@v4
  with:
    path: .bengal-cache
    key: ${{ runner.os }}-bengal-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-bengal-

Note: Python setup withcache: 'pip'automatically caches pip packages. Only add Bengal cache if you use incremental builds.

Environment-Specific Builds

Use different configurations for production and preview builds. Store secrets in GitHub repository settings.

1. Create environment configs:

config/environments/production.yaml:

site:
  baseurl: "https://example.com"

params:
  analytics_id: "{{ env.GA_ID }}"

config/environments/preview.yaml:

site:
  baseurl: "https://preview.example.com"

params:
  analytics_id: ""  # Disable analytics in preview

2. Add environment variables to workflow:

env:
  GA_ID: ${{ secrets.GA_ID }}
  API_KEY: ${{ secrets.API_KEY }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ... other steps ...
      - name: Build site
        run: bengal build --environment production

3. Set secrets in GitHub: Settings > Secrets and variables > Actions > New repository secret

Alternative Platforms

GitLab CI

Create.gitlab-ci.yml:

image: python:3.14

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - pip install bengal
    - bengal build --environment production --strict
  artifacts:
    paths:
      - public/

pages:
  stage: deploy
  script:
    - pip install bengal
    - bengal build --environment production --strict
  artifacts:
    paths:
      - public
  only:
    - main

Netlify

Createnetlify.toml:

[build]
  publish = "public"
  command = "pip install bengal && bengal build --environment production --strict"

[build.environment]
  PYTHON_VERSION = "3.14"

Vercel

Createvercel.json:

{
  "buildCommand": "pip install bengal && bengal build --environment production",
  "outputDirectory": "public",
  "installCommand": "pip install bengal"
}

Troubleshooting

Next Steps

Deployment Options — Explore other hosting platforms
Configuration — Environment-specific settings
Health Checks — Set up content validation
Graph Analysis — Add connectivity checks to CI