KiCad → git submodule + Gitea mirror — migration record & runbook

Date: 2026-08-27 · Status: local side DONE, pushes pending (need network + credentials)

1. What was done

03-Architecture-Hardware/kicad is no longer tracked file-by-file in project-drogheda. It is now a standalone git repository, referenced from the parent as a submodule.

Item	Value
Submodule path	`03-Architecture-Hardware/kicad`
Submodule name	`kicad`
Canonical remote (`origin`)	`git@github.com:lrodriguez15/hbox-kicad.git`
Mirror remote (`helgen`)	`ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git`
Submodule branch	`main`, 72 commits, HEAD `4bf41c6`
Parent commit	`5bb2e12` — "kicad → submodule (hbox-kicad)"
Rollback tag (parent)	`pre-kicad-submodule-2026-08-26` → `daafd5c`

History was preserved. The 71 board commits were extracted with git subtree split --prefix=03-Architecture-Hardware/kicad, so blame and bisect still work on the schematic and PCB. Commit hashes differ from the parent's (subtree split rewrites them); messages, authors and dates are identical.

Verified: every file that existed under kicad/ at daafd5c is byte-identical in the submodule (blob-hash comparison, 309/309 files). git fsck --connectivity-only on the new repo is clean.

Deliberate content changes (1 commit on top of the split)

added .gitignore — KiCad .kicad_prl, *.lck, *.T*bak agent scratch backups, .history/, .mcp-backups/, _to_delete/, *_drc_violations.json, *.log, snapshots/, Office lock files
added README.md — layout, remotes, history note
untracked hbox-watchdog-v3.kicad_prl (per-user KiCad UI state)
untracked ~hbox-watchdog-v5.kicad_pro.lck (KiCad session lock, already deleted on disk)

Not done, on purpose

Parent history was not rewritten. Its .git stays ~239 MB because the old kicad blobs are still in it. Nothing force-pushed, no clone broken. The parent simply stops growing from here on. If you ever want it slim, that is a separate git filter-repo + force-push job.
Branch kicad-split still exists in the parent as the split's output. Delete it once the push succeeds: git branch -D kicad-split.

2. What you still have to do

Step 1 — create the GitHub repo and push the submodule

cd ~/Documents/Claude/Projects/Drogheda/03-Architecture-Hardware/kicad

# create it (private) — or make it in the web UI as lrodriguez15/hbox-kicad
gh repo create lrodriguez15/hbox-kicad --private

git push -u origin main

~240 MB on the first push, mostly the STL/STEP mechanical exports. Expect a few minutes.

Step 2 — push the parent

cd ~/Documents/Claude/Projects/Drogheda
git push origin main
git push origin pre-kicad-submodule-2026-08-26   # rollback tag
git branch -D kicad-split                        # split scaffolding, no longer needed

Push the submodule first. A parent commit whose gitlink points at a commit nobody can fetch will break every clone.

Step 3 — set up the Gitea pull mirror

Gitea can only make a repo a pull mirror at migration time — it cannot be switched on for a repo that already exists. Helgen-Services/HBox_PCB is currently empty, so:

Gitea → Helgen-Services/HBox_PCB → Settings → Danger Zone → Delete.
+ → New Migration → GitHub.
- Clone URL: https://github.com/lrodriguez15/hbox-kicad.git
- Auth: your GitHub username + a classic PAT with repo scope (required — the GitHub repo is private)
- Owner: Helgen-Services · Repository name: HBox_PCB
- ✅ This repository will be a mirror
After migration: Settings → Mirror Settings → set the interval (default is 8h; 1h is reasonable) and use Synchronize Now to test.

You push only to GitHub; Gitea follows on its own. This needs no SSH key — the mirror pulls over HTTPS with the PAT, which is why it is the low-friction option while your SSH credentials are still pending.

If you would rather keep the existing HBox_PCB repo as-is, the fallback is a local dual push instead of a server-side mirror:

cd .../kicad
git remote set-url --add --push origin git@github.com:lrodriguez15/hbox-kicad.git
git remote set-url --add --push origin ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
# now `git push origin main` hits both — but both must be reachable, every time

Step 4 — SSH to Gitea (only if you want to push there directly)

ssh-keygen -t ed25519 -C "leo@helgen.tech" -f ~/.ssh/id_ed25519_helgen
pbcopy < ~/.ssh/id_ed25519_helgen.pub    # paste into Gitea → Settings → SSH/GPG Keys

cat >> ~/.ssh/config <<'EOF'
Host git.helgen.online
  HostName git.helgen.online
  Port 222
  User git
  IdentityFile ~/.ssh/id_ed25519_helgen
EOF

ssh -T git@git.helgen.online -p 222     # expect a Gitea greeting

The helgen remote is already configured in the submodule, so after this git push helgen main works. Do not push to Gitea if you set it up as a pull mirror in Step 3 — a mirror is read-only and force-overwrites local pushes on the next sync.

3. Day-to-day workflow from now on

Board work is committed inside the submodule, then the parent is told which commit to point at:

cd .../Drogheda/03-Architecture-Hardware/kicad
git add hbox-watchdog-v6.kicad_sch hbox-watchdog-v6.kicad_pcb
git commit -m "v6 T5: LTC4040 errata + U7 delete"
git push                                   # → GitHub, Gitea follows

cd ../..                                   # parent repo
git add 03-Architecture-Hardware/kicad     # stages the new gitlink
git commit -m "kicad: v6 T5"
git push

Forgetting the second half is the classic submodule trap: the board work is safe on GitHub, but the parent still points at the old commit.

Cloning fresh

git clone --recurse-submodules git@github.com:lrodriguez15/project-drogheda.git
# already cloned without it:
git submodule update --init --recursive

Anyone who only has Gitea access can redirect the submodule locally without editing .gitmodules:

git config --global url."ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git".insteadOf \
  "git@github.com:lrodriguez15/hbox-kicad.git"

For a fast, board-files-only checkout: git clone --filter=blob:none skips the historical STL/STEP blobs until something actually needs them.

4. Open items / observations

~hbox-watchdog-v6.kicad_pro was modified while this ran — KiCad is (or was) open on the v6 project. hbox-watchdog-v6.kicad_pro shows as modified in the submodule; commit or discard it as you see fit.
Your other three submodules point at ssh://git.helgen.dev:6611/… (hbox-firmware, htracker, hbox-log-tools) and are currently uninitialised. If .dev:6611 has been superseded by git.helgen.online:222, those URLs need updating too — say the word and I'll do it in one pass.
This VM has no network access, which is why every push above is left for you to run. Everything that could be done offline is done.
_to_delete/ folders under 03-Architecture-Hardware/ and kicad/ hold git lock/temp files that the sandbox was not permitted to unlink. Safe to delete.

7.2 KiB Raw Blame History