Journey · Step 05

GitHub and publishing

GitHub became the external boundary for the setup. The memory layer is useful, but it does not replace versioned code, inspectable history, reproducible publishing, or a clean place to push changes from the local machine and the VPS-backed environment.

Previous: Hooks and ingestion Back to Journey

Goal

Use GitHub as the external system of record for repositories, commits, publishing, and collaboration. Keep the local and remote work synchronized without blurring the boundary between memory and source control.

1. Normalize git identity

Use a consistent assistant-side commit identity

If the setup is going to commit from multiple places, git identity has to be consistent. That means setting a clear user name and email so the commit history is readable and does not fluctuate across repos.

git config --global user.name "dev"
git config --global user.email "assistant@example.invalid"

In some repos, local repo-level identity can still override the global value. That is useful when the machine-wide default is right most of the time but a single project needs something more specific.

2. Initialize or verify the local repo

Make sure the project is actually versioned before automation starts

Before a remote can matter, the local repository has to exist and be clean enough to use.

cd ~/projects/example-agent-stack
git status
git branch
git log --oneline -5

If the repo does not exist yet, initialize it before anything else:

git init
git add .
git commit -m "Initial commit"

3. Create or connect the GitHub repository

Attach the local repo to a remote that can actually be pushed

At this stage, GitHub becomes the external boundary. The exact method can vary, but the practical routes are the GitHub web UI or the GitHub CLI.

# route A: create repo in the GitHub web UI, then connect it locally
git remote add origin https://github.com/example/example-agent-stack.git

# route B: if gh is installed and authenticated
gh repo create example-agent-stack --private --source . --remote origin

The important part is not the creation method. It is making sure the repo points to a remote the user actually controls and can push to.

4. Push the local branch

Turn local state into inspectable remote history

Once the remote exists, push the main branch and establish upstream tracking.

git push -u origin main

This step is easy to underestimate. It is where the work stops being trapped on one machine.

5. Decide what belongs in memory and what belongs in git

Keep the boundary clean

This setup uses two different persistence layers on purpose. Git holds code, static site content, scripts, and versioned documentation. OpenClaw memory holds decisions, rationale, session context, and the things that are hard to reconstruct from git alone.

# Git is for
# - source files
# - docs
# - scripts
# - reproducible site content

# OpenClaw memory is for
# - decisions
# - rationale
# - session context
# - cross-session continuity

6. Use GitHub Pages for the site

Keep the public layer simple and low-maintenance

For a static documentation site, GitHub Pages is a clean fit. It keeps deployment straightforward and avoids turning the VPS into a web stack that also has to host the public site.

The usual route is to add a Pages workflow under .github/workflows/ and let GitHub publish the static files from the repository.

.github/workflows/deploy-pages.yml

7. Point the custom domain at GitHub Pages

Move the website edge away from parking records and onto the Pages target

Once the Pages workflow exists, the domain needs to resolve to GitHub Pages. That means updating DNS at the registrar, keeping any required verification TXT records intact, and setting the custom domain in the GitHub Pages settings.

# apex domain A records
# 185.199.108.153
# 185.199.109.153
# 185.199.110.153
# 185.199.111.153

# www CNAME
# example.github.io.

The exact hostname is placeholder text here on purpose. The design pattern is what matters.

8. Verify the live site and HTTPS

Check content, DNS, and certificate state together

Once the repo, workflow, and DNS are aligned, check the live site.

curl -I https://example-agent-stack.dev
curl -s https://example-agent-stack.dev | sed -n '1,60p'

The important checks are simple: the live HTML is current, HTTPS is valid, and the certificate covers both apex and www if both are used.

9. Keep GitHub in the wider workflow

Use it as the external record, not as a substitute for memory

After this point, GitHub is part of the larger agentic workflow. Local agents change files, hooks feed OpenClaw, OpenClaw preserves context, and GitHub keeps the actual repo history and publishing path stable.

Why this stage matters

Problem solved

Without an external version boundary, work stays trapped in local state and memory. That makes publishing and collaboration brittle.

Result

GitHub becomes the durable outer edge of the system: versioned, inspectable, publishable, and separate from the private memory layer.