static-site-deploy/README.md

Static Site Deploy

A small, dependency-free Forgejo Action that synchronizes a completed static website build to a dedicated Bunny Storage Zone.

The runner needs Bash and Python 3.11 or newer. The action itself installs no packages and executes no code from the Gandalf repository.

The deployer requires index.html, rejects symbolic links, compares files with a checksum manifest, uploads changed assets before HTML, deletes stale files only after successful uploads, and publishes the new manifest last.

Forgejo Actions

Store the website-specific Storage Zone password as the repository secret BUNNY_STORAGE_PASSWORD, then pin the action to an immutable commit from the public action repository:

---
name: Deploy website

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: docker
    steps:
      - uses: https://data.forgejo.org/actions/checkout@v6
      - run: npm ci
      - run: npm run build
      - name: Deploy to Bunny
        uses: https://forge.tionis.dev/actions/static-site-deploy@<commit-sha>
        with:
          directory: dist
          storage-zone: example-org
          purge-endpoint: https://tionis-static-site-purge.bunny.run
        env:
          BUNNY_STORAGE_PASSWORD: ${{ secrets.BUNNY_STORAGE_PASSWORD }}

Only run deployments for trusted branches. A contributor able to change a workflow that receives production secrets can attempt to expose those secrets.

purge-endpoint is optional. The Gandalf-managed gateway reuses the dedicated Storage Zone password to authorize purging only Pull Zones linked to that allowlisted zone. It avoids exposing the account-wide Bunny API key to project repositories. A configured purge is attempted after every non-dry-run sync, including a retry where Storage already matches the local build.

Command line

The script can also be used directly with Python 3.11 or newer:

export BUNNY_STORAGE_ZONE=example-org
export BUNNY_STORAGE_PASSWORD='zone-specific password'
python3 static_site.py bunny dist --dry-run
python3 static_site.py bunny dist

Changed files are transferred with 16 workers by default while preserving the asset-before-HTML and manifest-last publication order. Set BUNNY_TRANSFER_WORKERS or pass --workers to tune the limit.

Set BUNNY_STORAGE_ENDPOINT when the Storage Zone is outside Frankfurt.

Development

python3 -m unittest discover -s tests

The canonical source lives in the private Gandalf infrastructure repository and is published to this repository as a Git subtree.