Submatter/docs/forgejo-migration.md

Git remote migration — GitHub → Forgejo

Canonical repo: https://forgejo.stillwell.cloud/rstillwell/Submatter.git

Production host (CT 116) clones from Forgejo main. CI/CD runs via Forgejo Actions (.forgejo/workflows/) on the axiom self-hosted runner.

---

1. Local machine — point origin at Forgejo

From your dev checkout:

cd /path/to/submatter
bash scripts/migrate-origin-to-forgejo.sh

This renames the old GitHub remote to github and sets origin → Forgejo.

Push all branches you care about:

git push -u origin main
git push origin --tags
# feature branches:
git push origin feat/brief-3-harness-worker-dispatch

Use a Forgejo personal access token when prompted (Settings → Applications → Generate token, repo scope).

---

2. Merge deploy fixes to main

The CT 116 collab URL fix, Forgejo wiring, and prod compose live on your current branch. Before CT 116 can pull them:

git checkout main
git merge feat/brief-3-harness-worker-dispatch   # or your branch name
git push origin main

Or open a PR on Forgejo and merge there.

---

3. CT 116 — switch remote + redeploy

SSH to the production host (from a machine on your LAN):

ssh root@192.168.68.116
cd /opt/submatter

3a. Update .env (critical for doc/whiteboard fix)

nano .env

Ensure these lines exist and use wss:// (not ws://):

NEXT_PUBLIC_COLLAB_SERVER_URL=wss://collab.echodo.stillwell.cloud
COLLAB_SERVER_URL=wss://collab.echodo.stillwell.cloud

Add OmniRoute + Forgejo token (for Connected repos + worker):

OMNIROUTE_BASE_URL=https://omniroute.stillwell.cloud/v1
OMNIROUTE_API_KEY=<your-key>
FORGEJO_TOKEN=<forgejo-pat-with-repo-scope>

NEXT_PUBLIC_* changes require a full rebuild, not just restart.

3b. Migrate git remote + deploy

After main on Forgejo contains the deploy fixes:

bash scripts/migrate-origin-to-forgejo.sh
bash scripts/ct116-post-migration.sh

Or one-liner from your laptop:

ssh root@192.168.68.116 'cd /opt/submatter && bash scripts/migrate-origin-to-forgejo.sh && bash scripts/ct116-post-migration.sh'

Build takes 15–30 minutes on the 8 GB CT (serialized image build).

---

4. Forgejo Actions secrets

In Forgejo → Submatter → Settings → Actions → Secrets, add:

Secret	Value
HOMELAB_DEPLOY_HOST	192.168.68.116
HOMELAB_DEPLOY_USER	root
HOMELAB_DEPLOY_SSH_KEY	private key allowed to SSH to CT 116
HOMELAB_DEPLOY_PATH	/opt/submatter

Generate deploy key on CT 116:

ssh-keygen -t ed25519 -f /root/.ssh/forgejo_deploy -N ""
cat /root/.ssh/forgejo_deploy.pub >> /root/.ssh/authorized_keys
# paste private key into Forgejo secret HOMELAB_DEPLOY_SSH_KEY

Enable Actions on the repo. Workflows:

• .forgejo/workflows/ci.yml — lint, type-check, test on PR/push
• .forgejo/workflows/deploy-homelab.yml — deploy to CT 116 on push to main

Register the axiom runner in Forgejo (same CT 111 runner pool as GitHub, if configured for Forgejo).

---

5. Optional — Forgejo push webhook (instant deploy)

Alternative to Actions deploy:

1. Install webhook on CT 116
2. Configure proxmox/ct116/webhook.hooks.json.example
3. Forgejo repo → Webhooks → POST push to main

Set DEPLOY_WEBHOOK_SECRET in webhook config and Forgejo webhook secret.

---

6. Connected repos (in-app)

Settings → Connected repos:

Field	Value
Remote URL	https://forgejo.stillwell.cloud/rstillwell/Submatter.git
Token env var	FORGEJO_TOKEN

Token value lives in CT 116 .env only — not in the database.

---

7. Decommission GitHub (when ready)

• Archive or delete stwl-labs/ubiquitous-invention on GitHub
• Remove GitHub deploy secrets if unused
• Update any external links to point at Forgejo

Keep github remote locally for reference: git fetch github

---

Verify after deploy

1. Create a document and whiteboard — no client-side exception
2. Browser devtools → Network → WS connects to wss://collab.echodo.stillwell.cloud
3. Settings → AI → Providers → Test on OmniRoute alias
4. Settings → Connected repos → Test connection on Forgejo repo

See also: docs/deployment-production.md, proxmox/ct116/README.md