encore-deploy — 8syncdev backend (Encore Cloud) + frontend (Vercel) deploy runbook

All facts below are session-verified (2026-06-12). Follow them literally; do not improvise commands.

1. Topology

• backend/ is a git submodule → GitHub 8-Sync-Dev/backend-encore-8sync.
• TWO Encore Go apps live in that one repo:
  • gate/ → Encore app 8syncdev-gate-e852 (auth + billing)
  • 8sync-core/ → Encore app 8syncdev-core-cm62 (health + coding)
  • shared/ is a shared Go module wired via go.work.
• Encore git remotes are already configured inside backend/: encore-gate and encore-core. Verify:

git -C backend remote -v

2. Deploy model (there is NO encore deploy command)

Deploy = git push to the app's Encore remote. The push output prints the rollout URL.

git -C backend push encore-gate main    # deploys gate → 8syncdev-gate-e852
git -C backend push encore-core main    # deploys core → 8syncdev-core-cm62

Also push origin main, then bump the submodule pointer in the monorepo:

git -C backend push origin main
git add backend && git commit -m "chore: bump backend submodule"

3. CRITICAL gotcha — secrets do NOT hot-reload (proven 2026-06-12)

encore secret set does NOT reach running instances. Encore Go resolves secrets at boot. After rotating ANY secret you MUST trigger a rollout. An empty commit + push is acceptable:

git -C backend commit --allow-empty -m 'chore: roll secrets'
git -C backend push encore-gate main   # and/or encore-core

4. Secrets

Set from the app dir (e.g. cd backend/gate):

printf %s '<value>' | encore secret set --type prod,dev,pr <Name>

NEVER use --type local — it shadows the env-var fallbacks used by local dev and tests.

App	Secret	Notes
gate	AuthJWTSecret
gate	PayOSClientID
gate	PayOSAPIKey
gate	PayOSChecksumKey
gate	PayOSMode	live | sandbox
gate	AppURLCoding	e.g. https://coding.8syncdev.com
core	AuthJWTSecret	MUST equal gate's
core	JudgeSecret	MUST equal the Vercel coding project's JUDGE_SECRET env
core	JudgeURL	https://coding.8syncdev.com/api/judge

5. Logs

encore logs --env=staging is live-tail only — no backfill. Pattern:

(cd backend/gate && encore logs --env=staging > /tmp/gate.log 2>&1 &)
# trigger traffic (curl the endpoint under test)
# then read /tmp/gate.log

6. Health probes (verify EVERY deploy)

• Core: https://staging-8syncdev-core-cm62.encr.app/health/ping → JSON includes gitSha — MUST match the pushed HEAD.
• Gate: https://staging-8syncdev-gate-e852.encr.app/billing/plans (returns plan list).

7. Platform API (rollout debugging)

Bearer token = access_token field of ~/.config/encore/.auth_token (refreshed by any CLI call).

• Rollout status: GET https://api.encore.cloud/apps/<slug>/envs/<env>/rollouts/<roll_id>
• Retrigger failed rollout: POST https://api.encore.cloud/apps/<slug>/envs/<env>/rollouts/<roll_id>/retrigger
• App root dir: PATCH https://api.encore.cloud/apps/<slug>/settings body {"app_root_relpath":"..."} — already configured: gate=gate, core=8sync-core. Don't touch unless the repo layout changes.

8. Vercel FE deploy runbook (same ops family)

Three projects, team team_nl2xMkM0Uz0QaXTukIHKZPim:

App	Project ID	Domain
web	prj_qkUFCls4FBR6ryciob0L8nkyXm33	8syncdev.com
coding	prj_g4Z1tIXlwmNIE3b3xxXsOFoTfamz	coding.8syncdev.com
app	prj_WXalOR38x8MzijwUbWLGIiILzK9m	app.8syncdev.com

Two proven gotchas:

1. Plain vercel deploy upload SILENTLY DROPS [...slug] directories. ALWAYS deploy prebuilt, from the repo root with VERCEL_ORG_ID/VERCEL_PROJECT_ID exported:

   export VERCEL_ORG_ID=team_nl2xMkM0Uz0QaXTukIHKZPim VERCEL_PROJECT_ID=<prj_…>
   rm -rf .vercel && vercel pull --yes --environment=production && vercel build --prod
   vercel deploy --prebuilt --prod --yes

2. Deployments get BLOCKED (seatBlock TEAM_ACCESS_REQUIRED) when the git commit-author email is not a verified email on the Vercel account. Fix: verify atus@8syncdev.com on the account, or temporarily hide git around the deploy call (restore immediately):

   mv .git .git-hidden && vercel deploy --prebuilt --prod --yes; mv .git-hidden .git

9. Rules

• ALWAYS verify after a deploy: health probe gitSha matches HEAD and one authed E2E call succeeds — only then claim the deploy works.
• NEVER push the monorepo to encore remotes. Only backend/ is pushed to encore-gate/encore-core.
• After rotating secrets → redeploy (section 3). No exceptions.
• Never --type local for secrets (section 4).