docs: add gitea migration design

2026-07-08 00:56:06 +07:00
parent af3c852a5b
commit 74b05ee667
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Gitea Migration and CI/CD Design
+
+## Goal
+
+Migrate this project to the self-hosted Gitea instance at `https://git.imrnes.team` under `MythEclipse/GMW`, then add a Gitea Actions deployment workflow that behaves like the existing CI/CD setup while using Gitea user-level secrets.
+
+## Repository Target
+
+- Owner: `MythEclipse`
+- Repository: `GMW`
+- SSH remote: `ssh://git@git.imrnes.team:22222/MythEclipse/GMW.git`
+- Deployment branch: `main`
+
+The local repository currently uses `master`, so the migration will publish the current HEAD as `main` for Gitea Actions.
+
+## Existing Project Constraints
+
+- Package manager: `pnpm@11.1.3`
+- Root lint command: `pnpm run lint`
+- Build commands:
+  - `pnpm run build:backend`
+  - `pnpm run build:discord-gateway`
+  - `pnpm run build:web`
+- Frontend build uses Trunk/Rust from `services/frontend/frontend`.
+- Deployment script already exists at `./deploy.sh` and performs bind-mounted hot deployment to `/opt/imphenbot` on the VPS.
+- `.env` must not be committed.
+
+## Chosen Approach
+
+Use `deploy.sh` as the provider-neutral deploy entrypoint.
+
+The Gitea workflow will perform CI locally in the runner, write required runtime files from user-level secrets, then call `./deploy.sh --no-build` so the deploy script only transfers already-built artifacts and restarts containers.
+
+Rejected alternatives:
+
+1. Building and pushing Docker images to Gitea packages. This is more invasive, requires registry/auth changes, and is unnecessary because the existing deploy script already supports bind-mounted artifact deployment.
+2. CI-only without deployment. This is safer but does not satisfy the requested CI/CD migration.
+
+## Workflow Design
+
+Create `.gitea/workflows/deploy.yml` with:
+
+- Trigger: push to `main`.
+- Checkout with submodules.
+- Setup Node and pnpm.
+- Install dependencies with `pnpm install --frozen-lockfile`.
+- Run `pnpm run lint`.
+- Build backend, discord-gateway, and frontend.
+- Write `${{ secrets.PRODUCTION_ENV }}` to `.env` with mode `600`.
+- Write `${{ secrets.VPS_SSH_KEY }}` to a temporary private-key file with mode `600`.
+- Export:
+  - `VPS_HOST=${{ secrets.VPS_HOST }}`
+  - `VPS_USER=${{ secrets.VPS_USER }}`
+  - `VPS_SSH_KEY=<temp key path>`
+- Run `./deploy.sh --no-build`.
+
+The workflow must not create repo-level secrets and must not print secret contents.
+
+## `deploy.sh` Design
+
+Update `deploy.sh` to remove GitLab-specific fallback behavior.
+
+The script will:
+
+- Read deployment inputs from environment variables.
+- Require `VPS_HOST`, `VPS_USER`, and `VPS_SSH_KEY`.
+- Accept `VPS_SSH_KEY` as either a path to an existing key file or raw private-key contents; if raw contents are supplied, write them to a temporary file and clean it up.
+- Preserve existing local usage and service flags:
+  - `--frontend`
+  - `--backend`
+  - `--gateway`
+  - `--all`
+  - `--no-build`
+- Keep the current bind-mount artifact deployment flow.
+
+## Error Handling and Safety
+
+- Missing required secrets/env vars should fail fast before deployment starts.
+- Secret values must not be echoed.
+- `.env` is generated only inside the workflow workspace and remains uncommitted.
+- Deployment continues to use atomic remote directory swaps for artifacts.
+- The script should not depend on GitHub, GitLab, or Gitea CLIs for deployment.
+
+## Verification Plan
+
+After implementation:
+
+1. Verify lint passes with `pnpm run lint`.
+2. Verify builds pass:
+   - `pnpm run build:backend`
+   - `pnpm run build:discord-gateway`
+   - `pnpm run build:web`
+3. Verify `deploy.sh` help/syntax still works without requiring secrets.
+4. Create `MythEclipse/GMW` in Gitea if it does not exist.
+5. Set `origin` to `ssh://git@git.imrnes.team:22222/MythEclipse/GMW.git`.
+6. Push `main` to Gitea.
+7. Verify `git remote -v` uses the SSH Gitea URL with port `22222`.
+8. Check Gitea Actions runs. If `tea actions runs list` is unsupported, use `tea api /repos/MythEclipse/GMW/actions/runs`.
+
+## Out of Scope
+
+- Creating duplicate repo-level secrets.
+- Replacing the bind-mounted deploy model with a Docker registry deploy.
+- Committing `.env` or exposing secret values in logs.