windy-git/docs/CUTOVER.md

# Migration plan — GitHub first, Windy Git second, flip per repo

**Superseded the 2026-08-13 "daily driver" cutover, which was premature.**

## What went wrong, recorded so it is not repeated

Nine repos were migrated writable with **push-mirrors pointed at GitHub**. At
the same time a dozen agent sessions on the Mac mini were pushing to GitHub
continuously — so GitHub, not Windy Git, was where the live work actually was.

A push-mirror force-updates refs. On its 8-hour timer it would have pushed Windy
Git's stale copy **over live work, silently, with no conflict to notice.**

All nine mirrors were removed before the first timer fired, and every GitHub
repo was verified untouched (latest push predated the mirrors). **No work was
lost.** The mistake was direction, and the lesson is: *the source of truth is
wherever people are actually typing, not wherever the plan says it should be.*

## Phase 1 — now. Nothing changes for anyone.

    Mac mini agents ──push──▶ GitHub ──sync every 15 min──▶ Windy Git ──▶ CI on Veron

- **You do not have to tell your agents anything.** No remote changes, no
  coordination, no "everyone stop pushing." They keep working exactly as they
  are.
- `windygit-sync.timer` runs `scripts/sync_from_github.sh` every 15 minutes.
- Windy Git is **force-updated** on purpose: it holds nothing anyone depends on,
  so GitHub always wins and there is **no merge to reconcile**. That is the
  whole point of not flipping until a repo is quiet.
- CI runs on Veron 1 against current code, on the 36 workflows that already say
  `runs-on: [self-hosted, linux, x64]`.

Tracked repos live in `REPOS` in the script (currently 9 of 141).

## Phase 2 — later, one repo at a time, only when that repo is idle

For a single repo, when nobody is mid-work on it:

1. Remove it from `REPOS` in `sync_from_github.sh` — **first**, or the sync will
   fight its authors and win.
2. Point that repo's sessions at Windy Git:
   `git remote set-url origin https://app.windygit.com/windyadmin/<repo>.git`
3. Add a push-mirror back to GitHub with `sync_on_commit: true`, so GitHub stays
   a current second copy.

**Never flip more than one repo at a time, and never while an agent is working
in it.** A dozen parallel sessions is exactly the situation where a big-bang
cutover produces the dirty-branch mess this plan exists to avoid.

## The whole account is on Windy Git — in two tiers

    143 repos · 1.58 GB · 967 GB free      (matches the GitHub archive exactly)

| tier | count | writable | runs CI | deploy risk |
|---|---|---|---|---|
| **read-only mirrors** | 131 | no | **no** | **none** |
| **writable + CI** | 12 | yes | yes | deploys disabled |

**Why the bulk is mirrors, and why that is the safety decision:** sampling 40
repos found **18 carrying deploy / release / publish workflows that trigger on
`push:`** — roughly 63 across the account. Importing those writable with Actions
enabled would have armed sixty-odd production deploy triggers on Veron 1, each
needing disarming by hand. **A pull mirror cannot run Actions at all**, so the
bulk import carries zero execution risk and Gitea syncs it with no script and no
timer.

That splits the two things cleanly: **having a copy** (safe, do it for
everything, now) and **running code** (needs judgement, do it per repo,
deliberately).

Seven repos are empty here because they are empty on GitHub — 0 KB upstream,
verified. Not failed imports.

`windy-pro` **is** present, as a mirror. That is safe: the G11.5 caution is
about making it *writable* while six checkouts and a three-way-forked build
counter disagree on HEAD. A read-only copy of whatever GitHub currently has
carries none of that risk — and it means the DR copy is complete.

## Promoting a mirror to writable + CI

Per repo, deliberately, when that repo is quiet:

1. delete the mirror, re-import with `mirror=false`
2. **review its workflows and disable every deploying one** (see the section
   above — this is the step that matters)
3. add it to `REPOS` in `sync_from_github.sh` so it tracks GitHub
4. later, when it flips to Windy-Git-first: remove it from `REPOS` *first*,
   repoint its sessions, add a push-mirror back to GitHub

## Private repos: Windy Git IS their CI (permanent, 2026-09-23)

The platform repos stay **private** on GitHub (Grant, 2026-09-23), and private
repos cannot run GitHub Actions on this account at all. Windy Git is therefore
their CI permanently, not a stopgap:

    GitHub push ──sync (15 min)──▶ Windy Git ──runner──▶ Veron 1
         ▲                                                   │
         └──── commit status  windy-git/<workflow>/<job> ◀───┘   scripts/pr_status_bridge.py

- `pr_status_bridge.py` runs at the end of every sync. It opens a `[GH#N]`
  mirror PR in Windy Git for every open **same-repo** GitHub PR (so
  `pull_request` workflows fire), closes it when the GitHub PR closes, and posts
  each job's result back to GitHub on PR heads and the default-branch head.
  **Never merge a `[GH#N]` PR here** — merge on GitHub.
- Fork PRs are never run: their branch is never synced, and untrusted code
  beside the privileged dind is the open audit finding.
- Covered repos: `BRIDGE_REPOS` in the script. Public repos are left out on
  purpose; they run real GitHub Actions and two verdicts per commit is noise.
- `skipped` jobs post nothing — no green for a job nobody ran.
- **Image-build jobs** (name matches `docker`) post nothing: job containers
  have no Docker daemon by design (I-5), so they are red on every commit. A
  rootless builder (BuildKit rootless / buildx in the capped dind) is the open
  decision that would bring them back. Jobs that need Docker but are named otherwise go in
  `BRIDGE_NO_DAEMON` (empty since eternitas converted to ci/smoke, #179). DECIDED 09-23 (orchestrator,
  option A): lanes convert these jobs to no-Docker smoke tests (job `services:` +
  start the app + curl /health); the real image build is the deploy step on the
  target host. ci-hygiene flags docker build/compose/run in workflows ("needs docker").
  No host Docker socket for CI without a separate decision.

**Onboarding another private repo** — the promotion steps below, then:

    # on Veron 1, as root
    set -a; . /srv/windygit/src/.env; set +a
    python3 scripts/import_from_github.py <repo>          # writable; aborts if the repo exists
    # disable EVERY deploying workflow before anything is pushed:
    curl -X PUT -H "Authorization: token $GITEA_ADMIN_TOKEN" \
      http://localhost:3080/api/v1/repos/windyadmin/<repo>/actions/workflows/deploy.yml/disable
    # add <repo> to REPOS in sync_from_github.sh AND BRIDGE_REPOS in pr_status_bridge.py

An import fires no push event, so `main` has no verdict until its next commit.
To get one now: force Windy Git's `main` back one commit, then
`systemctl start windygit-sync` — the sync pushes it forward and CI fires.

⚠️ **`/actions/tasks` lists only jobs a runner has PICKED UP.** Queued runs are
invisible there, so a repo can read "0 runs" while work is waiting. The truth is
`action_run` in the `gitea` database (status 1 success, 2 failure, 5 waiting,
6 running).

## ⚠️ Deploy workflows are DISABLED on Windy Git, deliberately

Six workflows fire on `push:` and deploy to production:
`windy-registry`, `Windy-Clone`, `WindyCloud`, `windy-mind`, `eternitas`
(`deploy.yml`) and `windy-agent` (`release.yml`).

Windy Git now has a working runner, so the next synced commit to `main` would
have attempted a **production deploy from Veron 1**. Their secrets
(`DEPLOY_HOST` / `DEPLOY_KEY` / `VPS_SSH_KEY`) are unset here, so they would
have failed — but they would have failed *loudly on every push*, and any step
before the SSH step would still have run.

All six are now `disabled_manually`. Tests, lints and migration checks stay
**active** — those need no secrets at all, which is why Phase 1 delivers real CI
value immediately.

**Before re-enabling any deploy workflow here, decide deliberately whether
production should be deployable from Windy Git at all.** Kit 0 deploys are
currently manual runbooks; that is a feature, not a gap.

## Backups

`windygit-backup.timer`, nightly 04:17, `git bundle --all` + verify + `windgit`
schema dump to R2, 30-day retention. **Restore rehearsed:** a bundle was pulled
from R2, cloned, and its HEAD matched live `origin/main` exactly.