Semi-automatic: you only push

Publish with git push

The semi-automatic way. After a one-time setup, every update is the same: you edit a page, commit and push. GitHub Actions builds the site, checks that it opens and publishes it. You open the site and check the change.

Git is the best place to store the content of a site: every change is kept, any version can be brought back, and you and an AI agent work in one history. GitHub adds the rest: the image build is built in (GitHub Actions), and the image is stored right there (GitHub's own registry), so no other accounts are needed. Push a change, and a fresh image is built by itself; with HERON Agent (paid) it is also updated on your server. The setup takes about half an hour once. The site can live on your own server with Docker or for free on GitHub Pages.

How an update goes

1
Edit a page

Open a page file in the folder of your language inside content/, for example services.md, and change the text. To add a page, copy an existing file under a new name and fill it in. Look at the result with heron serve . on localhost:8000.
2
Save the change in git

A commit is one saved step of history with a short note. You can always look at it or roll it back.
3
Push

git push sends the commit to GitHub. Steps 2 and 3 are one line: git add . && git commit -m "New prices" && git push.
4
GitHub builds

GitHub Actions runs the strict build with the stable HERON image. A broken link or an empty description stops the build, and the log names the file and the line.
5
GitHub checks

The finished site is started and asked: home 200, a missing page 404, every redirect 301 or 410. A broken site never goes further.
6
GitHub publishes

The image goes to the registry, or the files go to GitHub Pages.
7
The site updates

On GitHub Pages at once. On your server with one command, or by itself with HERON Agent.
8
You check

Open the page you changed.

Set up once

Five steps, in order. The configurator does steps 2 and 3 for you when you choose GitHub with the automatic build on.

1. Create a repository on GitHub

Sign up at github.com and create an empty repository, for example my-site. A repository is a folder on GitHub that keeps your site and the history of every change.

Private or public: Private keeps drafts hidden. Public suits open projects: the texts of the site are visible, tokens never are.
GitHub Pages on the free plan: Works only with public repositories. A private repository needs GitHub Pro, or a server with Docker.
Name: The image is called after it: ghcr.io/you/my-site.
Empty means empty: Do not tick «Add a README» or a licence: the first push brings everything from your folder.; First time on GitHub? Account, repository and token step by step: git and GitHub.

2. Send the site folder

Run in the site folder, with your GitHub name instead of you. These commands start the history of the folder, save the first version and send it to GitHub.

git init && git add . && git commit -m "First version" && git branch -M main && git remote add origin https://github.com/you/my-site.git && git push -u origin main

What goes in: Texts, images, settings and the theme.
What stays out: dist/ and caches, through .gitignore. Tokens are never in the site folder.
Sign in: The first push asks for your GitHub login; the GitHub app or gh auth login remembers it.
Password does not work: GitHub no longer accepts the account password on the command line: use a token or sign in with gh auth login.
Check: Refresh the repository page: the folders content, media and theme and the file site.yaml are there.

3. Check the workflow file

The file .github/workflows/image.yml tells GitHub what to do on every push. heron new and the configurator put it into the site.

name: image
on:
  push:
    branches: [main]
jobs:
  image:
    uses: FMSTM/HERON/.github/workflows/site-image.yml@prod
    permissions:
      contents: read
      packages: write
    with:
      env: prod
      engine: prod

on push to main: Every push to the main branch starts a build.
env: prod opens the site to search engines; dev builds a closed preview.
engine: The HERON version that builds the site: prod is the stable one.
Token: Not needed: GitHub gives the build its own short-lived token to publish the image.
Where it lies: The dot in .github hides the folder in Finder and Explorer. In VS Code it is visible in the file list.

4. Watch the first build

Open the Actions tab of the repository. The run takes a few minutes and has three parts. A green tick means the image is ready, a red cross means the build stopped and says why.

Build: The strict build with the stable HERON image.
Pack: dist/ goes into a small nginx image made by the recipe of the same HERON version.
Check and publish: GitHub starts the image and checks the answers. Only a working image appears in Packages: ghcr.io/you/my-site:prod.
Red cross: Click the run, open the step with the cross: the line names the file, the line number and what to fix. Fix it, commit and push again. Common errors
Public or private package: A new package is private. To let any server download it without a password, open it in Packages → Package settings → Change visibility.

5. Start the site on your server

Any server with Docker. Inside the image the site listens on port 8080; the command below makes it answer on the usual port 80 and restart after a reboot.

docker run -d --name my-site -p 80:8080 --restart unless-stopped ghcr.io/you/my-site:prod

Public image: Any server downloads it without a password.
Private image: Create a token on GitHub: Settings → Developer settings → Personal access tokens, with read access to packages only. Sign in on the server once: docker login ghcr.io -u you, the token is the password.
Domain and HTTPS: Point the A record of the domain to the server and put HTTPS in front with your usual tool: nginx with certbot, Caddy or Traefik.; No server? Publish to GitHub Pages instead, below.
Every next update: Pull the new image and restart the container with one line: docker pull ghcr.io/you/my-site:prod && docker rm -f my-site && docker run -d --name my-site -p 80:8080 --restart unless-stopped ghcr.io/you/my-site:prod.

Update the server

After each push, a new image waits in the registry. Take it on the server with one command: download, replace the container, start.

docker pull ghcr.io/you/my-site:prod && docker rm -f my-site && docker run -d --name my-site -p 80:8080 --restart unless-stopped ghcr.io/you/my-site:prod

Downtime

A second or two while the container restarts.

Roll back

Every image keeps its own tag in the registry; start the previous one with the same command.

Without a server: git push to GitHub Pages

GitHub can publish the built files straight to GitHub Pages. Put this workflow in .github/workflows/pages.yml, then in the repository Settings → Pages choose «GitHub Actions» as the source.

name: pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: docker run --rm -v "$PWD":/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod build . --env prod --strict
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

fetch-depth: 0

Gives the build the full history, so every page gets its real date of change.

Domain

GitHub Pages with your own domain

Limits

A site up to 1 GB, a soft limit of 100 GB of traffic a month, public repositories on the free plan. Free hosting in detail

Free hosting in detail

Redirects

GitHub Pages has no server-side 301. If you move an old site with many addresses, prefer a server.

A preview before the live site

Add a second workflow for a dev branch with env: dev. The preview is built closed to search engines; you merge into main when it looks right.

name: preview
on:
  push:
    branches: [dev]
jobs:
  image:
    uses: FMSTM/HERON/.github/workflows/site-image.yml@prod
    permissions:
      contents: read
      packages: write
    with:
      env: dev
      engine: prod

Add-on: HERON Agent

Paid

HERON Agent

Takes over the server update step, so a push is the whole release. Without it everything above works; the Agent only saves the last command on the server.

What it does: Sees the new image in the registry, swaps the container, checks that the site opens and rolls back if it does not.
How it connects: Install the Agent on the server, generate a bot key, add your GitHub key: Telegram becomes the control panel for your sites.
Your bot or ours: Set up your own Telegram bot, or use ours by subscription.
Keys stay with you: The bot key and the registry key live on your server, not with us.
Several sites: One Agent serves every site on the server, each with its own HERON version.
More: HERON Agent

Questions

Do I need a GitHub token for the build?

No. GitHub gives the build its own short-lived token to publish the image. A personal token is needed only on a server that pulls a private image.

What if the build fails?

The run turns red, and the log names the file, the line and what to do. Nothing changes on the site: the previous version keeps working.

Can an AI agent push for me?

Yes. Codex or Claude Code can edit the content in a branch and open a pull request; GitHub builds and checks it before you merge. A website with Codex

Do I need HERON Agent?

No. Without it you update the server with one command, or use GitHub Pages, which updates by itself. The Agent is a paid add-on for those who do not want to touch the server at all.