Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs(ci): how the editor submodule is fetched, and how to rotate its key

esengine781b97046af2
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
index 49df354fe..96045f545 100644
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -5,6 +5,42 @@ Shared toolchain setup (pnpm + Node + a frozen install) lives in the
exactly one place; every job just `uses: ./.github/actions/setup` after its
checkout.
+## The editor submodule (`desktop/`)
+
+The editor is a **private** repository mounted at `desktop/`, so the workflow
+token cannot read it. Three jobs need it — **Editor authoring checks**,
+**Packages (golden + released)** and the release workflow's **electron-builder**
+job — and they fetch it through `./.github/actions/editor-checkout`, which uses a
+**read-only deploy key**:
+
+- public half: a deploy key on `esengine/estella-editor` titled `estella CI (read-only)`
+- private half: the `EDITOR_SSH_KEY` secret on `esengine/estella`
+
+A deploy key rather than a PAT because it is scoped to that one repository and
+cannot write: if it leaks, it reads one private repo and nothing else. It is also
+the only option `gh` can issue end to end — GitHub has no API for minting a PAT.
+
+Without the secret those three jobs **fail at checkout**, deliberately. They
+drive an editor; reporting green with no editor present would be a lie about what
+was checked. Every other job runs fine without it — see `--host engine` in
+`tools/verify-render.mjs` and `needs: 'editor'` in `tools/gates.mjs`.
+
+### Rotating the key
+
+```bash
+ssh-keygen -t ed25519 -N "" -C "estella CI" -f /tmp/k
+gh repo deploy-key add /tmp/k.pub -R esengine/estella-editor -t "estella CI (read-only)"
+gh secret set EDITOR_SSH_KEY -R esengine/estella < /tmp/k
+gh repo deploy-key list -R esengine/estella-editor # delete the old id
+gh repo deploy-key delete <old-id> -R esengine/estella-editor
+shred -u /tmp/k && rm -f /tmp/k.pub
+```
+
+`./.github/actions/engine-submodules` is the counterpart: it initialises every
+submodule **except** the editor, for the jobs that only want `third_party`'s
+vendored sources. `submodules: recursive` on checkout cannot be used any more —
+it tries to clone the private one too and fails the whole job.
+
## Emscripten Version
**Current pinned version**: 5.0.0