# 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:

```bash
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:

```bash
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:

```bash
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):

```bash
ssh root@192.168.68.116
cd /opt/submatter
```

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

```bash
nano .env
```

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

```env
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):

```env
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
bash scripts/migrate-origin-to-forgejo.sh
bash scripts/ct116-post-migration.sh
```

Or one-liner from your laptop:

```bash
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:

```bash
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](https://github.com/adhocore/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`](deployment-production.md), [`proxmox/ct116/README.md`](../proxmox/ct116/README.md)