GitHub Canonical Developer Workflow

Purpose

This workflow defines how Earthbond should be changed from now on.

GitHub is the canonical source of truth for Earthbond source code.

The local server is the runtime target.

That means:

1. code and deployment files live in GitHub,
2. changes are made in a local clone,
3. validated changes are pushed back to GitHub,
4. the local server updates from the GitHub repository,
5. runtime data remains local and is not stored in GitHub.

Canonical Repositories

Earthbond

1. repository:

• git@github.com:robby1312/earthbond.git

1. canonical branch:

• main

WIICCO Site

1. repository:

• git@github.com:robby1312/Wiicco-site.git

1. canonical branch:

• main

These are separate projects and should remain separate.

Canonical Rule

For Earthbond:

1. GitHub main is the canonical source.
2. The local server should run from a clone of that repository.
3. Local server edits should not live only on the server.
4. Any durable change to:

• Docker
• Python
• JavaScript
• SQL
• docs
• workflows

must be committed and pushed to GitHub.

What Codex Can Do

Yes. Codex can work with GitHub as the canonical source, but the practical operating path is:

1. Codex works against the local clone on disk.
2. Codex edits files in that clone.
3. Codex runs validation, rebuilds, and health checks locally.
4. Codex commits and pushes the validated result to GitHub.
5. The local server then updates from the GitHub repository.

This is the correct model.

Codex should not treat an untracked local server state as canonical.

Why Local Clone First

The app contains:

1. Docker Compose
2. multiple Dockerfiles
3. nginx and Caddy config
4. Python APIs
5. workers
6. generated manuals
7. database migrations

Those changes often need:

1. rebuilds
2. health checks
3. manual inspection
4. git commit history

That is why the working clone is the right editing surface.

Source And Runtime Split

Stored in GitHub

1. source code
2. Docker config
3. DB migrations
4. docs and manuals
5. deployment scripts
6. generated schema/config manifests

Not stored in GitHub

1. .env
2. MinIO object payloads
3. PostgreSQL row data
4. runtime secrets
5. local runtime outboxes
6. uploaded field-package data

Day-To-Day Earthbond Workflow

1. Start from the canonical branch

Use:

cd "/Users/robertwilhelm/Documents/New project"
git checkout main
git pull --ff-only origin main

2. Make changes in the local clone

Allowed change surface includes:

1. apps/
2. libs/
3. db/
4. docker/
5. scripts/
6. docs/
7. contracts/
8. docker-compose.yml

3. Validate locally

Typical validation:

cd "/Users/robertwilhelm/Documents/New project"
python3 scripts/dev/build_ui_manuals.py
./scripts/ops/check_stack_health.sh
docker compose up -d --build

Use additional checks when relevant:

make validate-docs
make validate-migrations
make test

4. Commit the change

Example:

git add -A
git commit -m "describe the change clearly"

5. Push to GitHub canonical source

git push origin main

6. Update the server from GitHub

If the local machine is the deployment host:

./scripts/ops/deploy_earthbond_from_github.sh

If GitHub Actions is active and secrets are configured:

1. push to main
2. GitHub Actions connects to the server
3. the server fetches origin/main
4. the stack rebuilds

Server Workflow

The server should be a deployment checkout, not an ad hoc development tree.

Use:

1. bootstrap_earthbond_server_clone.sh
2. deploy_earthbond_from_github.sh

Expected server model:

1. local clone tracks origin/main
2. server deploy script fetches origin/main
3. server resets to that state
4. Docker rebuilds from that state

Docker Change Workflow

When Docker-related files change:

1. edit:

• docker-compose.yml
• docker/*.Dockerfile
• docker/nginx/*
• docker/caddy/*

1. rebuild locally:

• docker compose up -d --build

1. run:

• ./scripts/ops/check_stack_health.sh

1. commit and push to GitHub
2. deploy from GitHub main

This is important because Docker changes affect:

1. reproducibility
2. runtime health
3. proxy behavior
4. service startup order

App Change Workflow

When app code changes:

1. edit Python or JavaScript files in the local clone
2. regenerate manuals if docs changed
3. run relevant validation
4. rebuild affected services
5. verify the WAN endpoints if needed
6. commit and push to GitHub main

Backup Workflow

The scheduled backup job now assumes the canonical branch is:

1. main

It exports:

1. Docker config manifests
2. PostgreSQL schema-only backup
3. MinIO manifest
4. repo state manifests

Then it commits and pushes the result to GitHub.

Run manually:

cd "/Users/robertwilhelm/Documents/New project"
./scripts/ops/backup_to_github.sh

Codex Working Rules

If Codex is changing Earthbond:

1. work from the local Earthbond clone
2. treat GitHub main as the durable source of truth
3. keep the running server healthy while editing
4. rebuild and validate before push
5. push the resulting source back to GitHub
6. never treat secret or runtime data as git content

What Not To Do

Do not:

1. keep important changes only on the server
2. treat MinIO or PostgreSQL runtime data as source code
3. mix WIICCO Site changes into the Earthbond repo long-term
4. deploy from random local untracked edits
5. use GitHub branches as long-term project boundaries for separate products

WIICCO Site Workflow

WIICCO Site should follow the same model in its own repository:

1. clone git@github.com:robby1312/Wiicco-site.git
2. work from main
3. commit and push to main
4. deploy from that repo's local clone

Decision Summary

The correct operating model is:

1. GitHub is canonical for source
2. Codex edits the local clone
3. changes are validated locally
4. changes are pushed to GitHub
5. the computer/server updates from GitHub

That is the defendable workflow for a Docker-heavy application where code, infrastructure, and generated manuals all change together.