intotheeast-com/docs/working/git-sync-notes.md

Git Sync Plugin — Setup Notes

⚠️ Config lives in the ENVIRONMENT tree, not user/config/ (IMPORTANT)

Prod has a per-environment override directory user/env/<hostname>/config/ (created for Twig prod-mode — see CLAUDE.md §1). A crucial Grav side effect: once that env dir exists, the Admin panel saves ALL config changes — system and plugin — into the active environment's config tree, not user/config/.

So on prod, git-sync.yaml (configured via Admin) lives at:

user/env/intotheeast.com/config/plugins/git-sync.yaml   ← here (env tree)
user/config/plugins/git-sync.yaml                       ← NOT here

Why this matters:

• Server-only, not synced, not committed. user/env/ is outside the content repo's tracked folders (pages/config/accounts/themes) and is not one of git-sync's synced folders (pages/config/themes). So config saved via Admin on the server never reaches Gitea or local. This is ideal for the git-sync token (it stays server-only) but means prod Admin config edits silently diverge — author durable config in the repo, not prod Admin.
• Look in both places. When inspecting/toggling server config, check user/config/plugins/<name>.yaml and user/env/<host>/config/plugins/<name>.yaml (env wins).
• Tooling is env-path-aware. scripts/git-sync-toggle.sh takes a WEBROOT and searches user/env/*/config/plugins/git-sync.yaml first, then user/config/plugins/git-sync.yaml. make remote-git-sync-disable/enable-<env> and make remote-diag-<env> use it.

Folders format

Older plugin versions' UI saved the folders field as a single comma-string (- 'pages,config,themes'), which the plugin iterated as one path, so sync silently did nothing. git-sync v3.4.4 (installed on prod 2026-07-04) saves it correctly as separate list items:

folders:
  - pages
  - config
  - themes

If you see the comma-string form on an older version, fix it by editing git-sync.yaml directly (at whichever path it lives — see above); do not re-save folders via the Admin UI on the buggy version.

Per-install / secret files — must be gitignored (never synced)

git-sync syncs the config/ folder, so any per-install or secret file tracked there would get pushed to Gitea and pollute every environment. Keep these out of the content repo (all in user/.gitignore):

File	Why
config/plugins/git-sync.yaml	encrypted token; server-specific (also lives at env path on prod)
config/plugins/api-private.php	API JWT secret
config/security.yaml	Grav nonces/salts (legacy location)
config/versions.yaml	per-install Grav schema-migration state — differs per env (dev 2.0.4, prod 2.0.7); Grav regenerates it. Untracked 2026-07-04.
config/security-private.php	TODO: committed salt secret; should be gitignored like api-private.php (deferred — untracking resets server sessions)

git-sync config summary (prod, 2026-07-04)

• repository: https://git.gorinskat.nl/m038/intotheeast-com-content.git, branch: main, HTTPS + token auth (SSH is Tailscale-only).
• sync.direction: both, on_save/on_delete/on_media: true → prod Admin edits and /post push to Gitea; content-repo pushes pull to prod via webhook (/_git-sync). The webhook is configured in Gitea repo settings (same secret as the test instance).
• Before enabling on a fresh server, reset the synced folders clean (make remote-fetch-content-<env>) so no install-time drift (e.g. a stale versions.yaml) gets pushed on the first sync. Toggle with make remote-git-sync-disable/enable-<env>.