Skip to content

t1k:unity:mobile:remote-config-deploy

FieldValue
Modulemobile
Version3.65.6
Effortmedium
Tools—

Keywords: default_config.json, deploy, firebase, firebase-deploy, gdk-3rd, merge-remote-config, parameter-groups, publish, remote-config, remoteconfig, remoteconfig.template.json

/t1k:unity:mobile:remote-config-deploy

Generate the game’s remote-config JSON from the Unity generator, merge it into the live Firebase template (preserving conditions / top-level parameters / untouched groups), confirm the diff, then publish and verify. This skill is a driver, not a builder — the generator ships in Packages/com.gdk.3rd/ and is read-only; this skill NEVER edits it.

  • In scope: generating, merging (backup-first), orchestrating publish, post-publish verification.
  • Out of scope: editing anything in com.gdk.3rd (submodule — a generator bug is a PR to that repo, rules/reproducible-on-every-machine-unity.md); authoring Firebase conditions / A-B tests (this skill preserves them, never creates them; A/B setup: t1k-unity-mobile-ab-test); authoring new remote-config keys (ships what RemoteConfigSetting already holds).
  • Project note: a repo’s git name and its Firebase project id can differ (an internal codename vs. a published brand, say). That is drift, not a wrong target — always trust the resolver’s answer (scripts/resolve-firebase-project.cjs), never the repo name, and never “correct” the id to match it.
  • “publish / deploy remote config”
  • “push default_config.json to Firebase”
  • “sync the game’s RemoteConfigSetting to Firebase Remote Config”
  • “update live remote config from the generator”
ItemPath / value
Firebase projectresolved at runtime by scripts/resolve-firebase-project.cjs — SSOT: <UnityDir>/Assets/google-services.json → project_info.project_id; cross-check GoogleService-Info.plist → PROJECT_ID. <UnityDir> is auto-discovered (any immediate repo-root subdirectory holding Assets/google-services.json); pass --unity-dir <name> if the repo hosts more than one Unity project.
GeneratorRemoteConfigSetting.GenerateJsonFile() — private Odin [Button], UniTask.Void, in Packages/com.gdk.3rd/Configs/RemoteConfig/RemoteConfigSetting.cs
Generator output<UnityDir>/Assets/Resources/GameConfigs/default_config.json (parameterGroups only; no conditions, no top-level parameters)
Config asset<UnityDir>/Assets/Resources/GameConfigs/RemoteConfigSetting.asset
Repo configfirebase.json (remoteconfig.template = remoteconfig.template.json) + .firebaserc (default project = the resolved id), both committed at repo root
Merged template<repo-root>/remoteconfig.template.json
Backups.claude/remote-config-backups/<project>-<UTC-ISO>.json

Scripts (fixed contract — owned by a parallel agent)

Section titled “Scripts (fixed contract — owned by a parallel agent)”
bun .claude/skills/t1k-unity-mobile-remote-config-deploy/scripts/resolve-firebase-project.cjs [--repo-root <p>] [--unity-dir <name>] [--json]
exit 0 → {"projectId":"...","unityDir":"...","crossChecked":bool,"sources":{...}}
exit 2 → id mismatch (HARD STOP) | exit 1 → google-services.json missing/unreadable or no project_id, or ambiguous/absent Unity dir
`crossChecked:false` = no GoogleService-Info.plist was found (Android-only project) — the id came from
google-services.json ALONE. Not a failure; corroborate it against `firebase_get_environment`'s active
project before publishing. The plist is optional; google-services.json is the only required file.
bun .claude/skills/t1k-unity-mobile-remote-config-deploy/scripts/merge-remote-config.cjs --generated <p> --live <p> --out <p> [--json]
exit 0 ok | 1 IO/usage | 2 needs human decision
--json stdout: {added[],changed[],groupsChanged[],orphaned[],destroyed[],droppedGeneratedInput[],
collisions[],preserved:{conditions,topLevelParameters,untouchedGroups,conditionalValueParams},
counts:{added,changed,orphaned,groupsChanged,destroyed,totalOut}}
orphaned = present live, KEPT. destroyed = live value DISCARDED. Opposite meanings, never one bucket.
exit 2 = the self-check found the diff does not describe the written template, OR `collisions[]` is
non-empty (a key lives BOTH at top level and inside a group — Firebase requires one location per key).
Nothing written either way; DO NOT publish.
  1. Resolve the Firebase project — run the resolver. Exit 2 → hard stop, never guess. On crossChecked:false (Android-only project, no plist) the id is still valid — corroborate it with firebase_get_environment’s active project before publishing (see Hard rules).

  2. Generate — Editor open (t1k unity status is ok) → confirm it is bound to THIS project (binding is by working directory: projectRoot in t1k unity status / t1k unity instance current must be this checkout; unity-forbidden-operations.md § instance trust), expose and invoke the private [Button] by reflection, then poll default_config.json’s mtime for an advance — UniTask.Void is fire-and-forget, so the call returns BEFORE the file is written. NOT reachable → use the on-disk default_config.json. If that file does not exist, STOP — the generator has never run in this checkout and there is nothing to publish; do not proceed on an empty or stale read. If it exists but its mtime is older than RemoteConfigSetting.asset, warn before continuing.

  3. Ensure repo config — firebase.json + .firebaserc exist at repo root and the project matches step 1. Recreate only if missing, then commit them.

  4. Point the MCP — firebase_update_environment to this project’s dir + the resolved project id.

  5. Fetch the live template — prefer the MCP read tool mcp__firebase__remoteconfig_get_template (it returns the template AND its version metadata, versionNumber included — which step 11 otherwise needs a separate command for). The bunx firebase-tools@latest remoteconfig:get --project <id> -o "${TMPDIR:-/tmp}/rc-<id>-live.json" path is equally valid and remains the fallback when the MCP is unavailable (headless/multi-project auth via a per-project service-account key: references/service-account-auth.md); its output carries no version field. Both are real reads — the split that is hard is the PUBLISH direction, not the read. Whichever you use, the path must carry the project id and a TMPDIR base — never a bare /tmp/rc-live.json, which two projects share and which Windows resolves differently for shell and node steps. Delete the target before fetching so a failed fetch cannot leave the previous run’s file readable, then assert the fetched template belongs to the resolved project (corroborate via .firebaserc projects.default; the REST payload itself carries no project id field).

  6. Back up — copy the live template to .claude/remote-config-backups/<project>-<UTC-ISO>.json BEFORE anything else.

  7. Merge — run merge-remote-config.cjs. Publish is a FULL REPLACE (absent conditions/parameters are deleted server-side), so the merge is what protects them: generated groups upsert into same-named live groups; live conditions, top-level parameters, and untouched groups are preserved; orphans are kept and reported, never silently dropped.

    The generated set routinely exceeds 10 keys (it tracks the config asset, so the exact count varies per game) → this trips `rules/preview-first-batch.md`'s >10-item trigger. The publish gate in step 8 is mandatory and has no override.
  8. Diff + confirm — render the merge’s added[] / changed[] / orphaned[] and AskUserQuestion the user before publishing. Echo the project id in the confirmation so a wrong target is visible at the moment of decision. First diff the config asset against HEAD (git show HEAD:<config-asset>) and surface any flipped kill-switch in the same question — see the silent-divergence Gotcha.

  9. Dry-run — ?validate_only=true on the REST endpoint is a REAL server-side dry run (not a local diff alone), and remoteconfig:get mirrors it with ETag — use one of these pre-publish.

  10. Publish — mcp__firebase__firebase_deploy(only: "remoteconfig"), after firebase_update_environment

    • firebase.json/.firebaserc are in place (step 4 + step 3). The deploy returns a jobId — poll firebase_deploy_status until status: success (its result is {}). Publishing the template directly instead of deploying is the other route: mcp__firebase__remoteconfig_update_template (full template object; it is a FULL REPLACE) — pass force:true to bypass the ETag; without it this call can fail with a generic “Failed to publish” even though nothing changed server-side. A success job is NOT a publish. Record the live versionNumber BEFORE publishing (step 5’s MCP read, else versions:list), then poll it for up to ~2 min: it MUST be greater than the recorded value. Not advanced → the publish did not land (seen with a running A/B experiment; the MCP error text hides the reason). Do NOT report success. Fall back to the CLI publish, which the step-8 confirmation already covers: from the repo root, bunx firebase-tools@latest deploy --only remoteconfig --project <id> --non-interactive, then re-check.
  11. Verify — re-fetch via step 5 (or read step 5’s own versionNumber if you used the MCP read tool, whose metadata replaces the separate versions:list call below), then assert the count using the same definition the merge used: counts.totalOut counts parameters inside parameterGroups ONLY and excludes top-level parameters. So the expected re-fetched total is counts.totalOut + preserved.topLevelParameters. Comparing a re-fetched grand total against totalOut alone will report a false failure the moment a top-level parameter exists — and a gate that cries wolf gets switched off. Also spot-check keys, confirm preserved.conditionalValueParams did not drop, and assert the version advanced past the number recorded in step 10, then report it. remoteconfig:get does NOT return version metadata — it comes back as {}, so this step cannot be satisfied from the CLI fetch. Get it from its own command:

    bunx firebase-tools@latest remoteconfig:versions:list --project <id> --limit 1

    (The MCP read tool mcp__firebase__remoteconfig_get_template returns versionNumber in the same response — use it and this extra call is unnecessary.) Report that number as the rollback target. Rolling back is bunx firebase-tools@latest remoteconfig:rollback --project <id> --version-number <n>.

bash .claude/skills/t1k-unity-mobile-remote-config-deploy/scripts/firebase-sa-run.sh <map|list|env|<project-or-package> <firebase args>>
runs firebase-tools with the matching service-account key; a dotted arg is an Android package name
resolved via google-services.json. Auth + gotchas: references/service-account-auth.md

The two scripts are mechanical: t1k-fact-fetcher may run them and t1k-metrics-reporter summarise the diff. The live Firebase publish stays reasoning-tier, operator-confirmed.

  • The MCP DOES have Remote Config tools (an earlier version of this file said it had none; that was wrong). mcp__firebase__remoteconfig_get_template reads (and returns version metadata); mcp__firebase__remoteconfig_update_template publishes a full template object (force:true bypasses the ETag — without it the call failed with a generic “Failed to publish” even though nothing had changed server-side). bunx firebase-tools remoteconfig:get stays a valid read path. The MCP publish (firebase_deploy(only:"remoteconfig") after firebase_update_environment) can report a successful job without advancing the version — always verify the version advanced (step 10) and fall back to the CLI deploy when it did not.
  • A parameter key must be UNIQUE across the whole template. A key present BOTH at top level (live) and inside a generated group is not a merge — the merge now reports it in collisions[] and exits 2 before writing. A live template can carry top-level keys the generator also emits in a group; the old behaviour wrote the key in both places with exit 0, which Firebase rejects or deduplicates arbitrarily. The fix is a human call, not an auto-merge: move the top-level entry into the group, overlay the generated description/defaultValue/valueType, KEEP its conditionalValues (e.g. a develop-test condition on enable_aoa_resume_loading), then delete the top-level copy. Always eyeball set(parameters) ∩ keys(parameterGroups) before publishing.
  • Moving a top-level param into a group is also how a missing description gets filled — the generator supplies it from RemoteConfigKeyDescriptions. A key read straight from game code and deliberately ABSENT from the config asset (e.g. no_ads_auto_show_per_session, whose default lives in a C# const by design) shows up as orphaned with no description: fill it from the code constant’s doc comment, and do NOT add the key to the asset — the asset is not that key’s SSOT.
  • The config asset can silently diverge from HEAD. An Editor Inspector edit flipped enable_aoa_ad true→false in RemoteConfigSetting.asset; the merge reported it as a plain changed[] entry — publishing it would have disabled all AOA, including first open. Before the publish gate, diff the asset against git show HEAD:<config-asset> and name any flipped kill-switch (enable_*_ad, enable_ads) explicitly in the step-8 AskUserQuestion. Also: editing the .asset on disk while the Editor has it loaded lets the Editor re-save its in-memory value over your edit — tell the user to check the Inspector.
  • The resolver treats the plist as OPTIONAL. An Android-only project legitimately ships only google-services.json; it used to exit 1 there. You now get crossChecked:false plus a stderr warning — the id is valid but one-sided, so corroborate it against firebase_get_environment’s active project before publishing. crossChecked:false is not a failure; silently ignoring it is.
  • firebase_deploy returns a jobId, not a result. Poll firebase_deploy_status until status: success (its result is {}) and then re-fetch to verify — the job status is not verification. Requires firebase.json ({"remoteconfig":{"template":"remoteconfig.template.json"}})
    • .firebaserc default project at repo root AND firebase_update_environment(project_dir, active_project) first.
  • Generation via t1k unity eval --file gen.cs (the facade now reaches the Pipeline eval_file command — the “unknown command ‘eval’” refusals in #1143/#1150 are fixed; not re-verified live since): AssetDatabase.LoadMainAssetAtPath(".../RemoteConfigSetting.asset") → GetMethod("GenerateJsonFile", BindingFlags.Instance|NonPublic|Public).Invoke (type ServiceImplementation.FireBaseRemoteConfig.RemoteConfigSetting). A multi-statement body ending in ; is passed through verbatim (a bare expression would be wrapped in return …;). Confirm Application.dataPath is THIS project and isPlaying/isCompiling are false first; the file appears within ~1s.
  • UniTask.Void is fire-and-forget. The generator call returns BEFORE default_config.json is written. Poll the file’s mtime for an advance; never assume the write happened because the call returned.
  • Publish is a FULL REPLACE. Absent conditions and parameters are DELETED server-side. The empty live template makes today’s first publish safe, but it will NOT stay empty — backup + merge + confirm every time, exactly as prescribed.
  • description is truncated at 256 chars by the generator with a warning. Expected, not a bug.
  • A new key needs 4 touchpoints in com.gdk.3rd, and only #4 feeds the generator. RemoteConfigKey const, RemoteConfigKeyDescriptions entry, the read site (e.g. AdServicesConfig.FetchRemoteConfig), AND the default in RemoteConfigSetting.OnEnable() (TryAddAdsConfig/TryAddMiscConfig). Skip the last and it still compiles, but every project whose asset predates the key logs Cannot find remote config with key: <key> on Play and the key never reaches the generated template (#156 → fixed #161).
  • The Unity Editor is a mutex. One session drives it at a time: the facade’s project lock (exit 10) queues a second t1k unity mutating call. Confirm no sibling session holds the Editor before driving any Editor-touching call, and timeouts may be contention, not failure (t1k-unity-editor-cli SKILL.md § “Editor mutex: obligations that stay”).
  • Repo-name drift is not a mismatch. A repo’s git name and its Firebase project id can differ. Target the resolver’s answer, never the repo name — CLAUDE.md or a README can go stale about which brand a repo actually ships.
  • com.gdk.3rd is read-only. The generator lives there. A generator bug is a PR to that repo, never a local edit.
  • AskUserQuestion gate (step 8) is mandatory, not cosmetic — this is the firewall between the merge and a destructive full-replace publish.
  • firebase_deploy reports success with an EMPTY result payload. {"status":"success", "progress":100,"result":{}} proves the job ran, not that the right template landed. Always re-fetch and assert the count + spot-check keys; never treat the job status as verification.
  • An empty parameterGroup publishes fine. A group with 0 parameters (e.g. no gameplay configs exist yet, only ad configs) is accepted by Firebase — no need to strip empty groups before publishing.
  • Do not treat any generated-parameter count as a fixed expectation. It tracks the config asset and varies per game and per run; a stale hardcoded number in a doc or a skill comment is a bug, not a spec — verify against the live merge output instead.
  • A phase apply is overwritten by this skill’s merge. For every key this skill’s generator emits, the asset default replaces a value set by t1k-unity-mobile-release-phase-config; keys it does not emit (top-level parameters) are preserved. Run that skill’s detect first.
  • references/incident-history.md — dated incident records behind the gotchas above (non-normative).
  • references/publish-flow.md — the 11-step runbook in detail: t1k unity eval reflection driving the private [Button], mtime polling, npx fetch + backup + merge + confirm + publish + verify, and the failure matrix (resolver, merge exit-2, Unity eval invocation, publish)
  • references/service-account-auth.md — CLI auth without the MCP: per-project service-account keys, package-name -> project -> key resolution (scripts/firebase-sa-run.sh), why never to export one fixed GOOGLE_APPLICATION_CREDENTIALS, key hygiene
  • references/key-semantics.md — the ad keys whose name does not match their effect (resume-AOA has no on/off switch; aoa_loading_threshold is double-duty; is_inters_instead_aoa_first_open reads once in the Editor). Read before setting any AOA/interstitial value.