2 · Server sync — capture server changes

TL;DR

Objective — capture changes made on the server (admin-panel uploads, installer output, config) back into git before the next deploy silently wipes them — and do it without ever committing secrets.

User part + done-when

👤 User part — the judgement calls a person must own: deciding the change is worth capturing, and reviewing the captured file list before it merges (never auto-merge a sync). The git/SSH commands themselves are agent-runnable.

Done when the server’s new files are committed to production and merged back to develop, with no .env, keys, or credentials in the commit.  ·  ⏱ ~5–15 min  ·  🔀 mixed (🤖 git/SSH, 👤 review + approval).

Background

A deployed app has two sources of truth that can drift apart: git (your code) and the server (files written after deploy — a logo uploaded through the admin panel, files the web installer generated, an admin config change). Your deploy pipeline clears and replaces server directories on every release — so anything the server wrote that git doesn’t know about gets erased on the next deploy.

Server sync closes that gap: it pulls those server-side changes back into git first, so the next deploy preserves them instead of destroying them.

flowchart LR
  A["Server writes file<br/>upload · installer · config"] --> B["Capture into git<br/>commit on production"]
  B --> C["Review file list<br/>no secrets"]
  C --> D["Merge to develop<br/>safe to deploy"]

The risk runs the other way too: server files can include .env, private keys, or logs with personal data. Capturing those into git would leak secrets — so every sync is review-first, never auto-merge.

For the command-only card, see the Server sync capture runbook.

Steps

1. Confirm the change is worth capturing

Not every server change needs syncing. Match what changed against the table so you only capture real, durable files — and never sweep secrets in by accident.

Who does this

👤 User decides whether the server change is worth capturing — only a person knows what was uploaded or configured and whether it should live in git.

1. Match the change against the capture table.

   Change type	Example	Capture?
   Admin-panel uploads	Logo, favicon, images	✅ Yes
   Web installer output	Generated files, storage/installed	✅ Yes
   Composer install on server	Package installed on the server	✅ Yes
   Admin-panel config	SMTP, payment keys	⚠️ Maybe — .env.example updates only

   • ✅ You’ve confirmed the change is a real, durable file worth keeping in git.

2. Capture the changes into git

Two ways to capture: the GitHub Action does it for you (preferred), or you do it by hand over SSH. Either way, the server’s new files land as a commit on the production branch.

Who does this

🤖 Agent can trigger the workflow or run the SSH commands. 👤 User must run the GitHub Action from the Actions tab if that method is used (a browser-only action) and is the one who knows which environment and sync type to pick.

1. Preferred — trigger the ServerSync GitHub Action. From the repository’s Actions tab, run the capture workflow (e.g. capture-production.yml) for the right environment. It SSHes in, captures the shared directories, and commits to production for you.

   • ✅ The workflow run finishes and a capture commit appears on production.

2. Manual fallback — capture over SSH, screening for secrets first. Use this only if the Action isn’t available.

   ssh [SSH_PRODUCTION_ALIAS]
   cd [DEPLOY_PATH]
   git status
   # Expected: a list of changed files. If .env, *.key, *.pem, or credentials appear, DO NOT stage them.
   git add .
   git commit -m "🔄 ⬛ T5 ServerSync-Upload: Capture [description]"
   git push origin production
   # Expected: the server-side files are committed and pushed on production

   • ✅ The captured files are committed on production and no secret file is staged.

Stop if a secret was staged

If .env, a *.key, a *.pem, or any credential appears in the staged files — stop. Remove it before committing. If one already got pushed: don’t merge onward, revert the commit immediately, and rotate the exposed credential.

3. Review what was captured

This is the human gate. A sync commit can include deletions caused by config drift, not just safe additions — so a person reads the file list before it merges anywhere.

Who does this

👤 User reviews the captured file list and approves. Never auto-merge a ServerSync result — ADDED files are usually safe, MODIFIED files need a look, and DELETED files signal drift and are dangerous.

1. Pull the capture locally and inspect the file list.

   git checkout production && git pull origin production
   git log --oneline -3
   git show --stat HEAD
   # Expected: the capture commit, and a file list of exactly what changed

   • ✅ Every captured file is an intentional ADDED/MODIFIED asset — no surprise DELETED files, no secrets.

If you see DELETED files you didn’t expect, that’s drift between the deploy config’s clear_paths and the sync workflow’s GIT_ONLY_PATHS — fix the symmetry before trusting another sync, rather than committing the deletions.

4. Merge back to develop

Once reviewed, fold the capture into develop so your everyday branch carries the server’s truth and the next ship doesn’t reintroduce the drift.

1. Merge production into develop and push.

   git checkout develop && git merge production && git push origin develop
   # Expected: develop now contains the captured server files

   • ✅ develop carries the captured changes; you can resume normal development and ship when ready.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Worth capturing — the change is a durable server file (upload / installer output / config), not noise.
• 🤖 No secrets staged — no .env, *.key, *.pem, logs, or credentials in the commit.
• 🤖 Committed on production — captured via the GitHub Action or manual SSH, with a T5 ServerSync message.
• 👤 File list reviewed — inspected git show --stat; no unexpected DELETED files; not auto-merged.
• 🤖 Merged to develop — production folded back into develop and pushed.

→Next step

WF5 · Emergency hotfix