t1k:unity:mobile:remote-config-deploy
| Field | Value |
|---|---|
| Module | mobile |
| Version | 3.65.6 |
| Effort | medium |
| Tools | — |
Keywords: default_config.json, deploy, firebase, firebase-deploy, gdk-3rd, merge-remote-config, parameter-groups, publish, remote-config, remoteconfig, remoteconfig.template.json
How to invoke
Section titled “How to invoke”/t1k:unity:mobile:remote-config-deployT1K — Remote Config Deploy (Firebase)
Section titled “T1K — Remote Config Deploy (Firebase)”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 whatRemoteConfigSettingalready 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.
When to Use
Section titled “When to Use”- “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”
Project Constants
Section titled “Project Constants”| Item | Path / value |
|---|---|
| Firebase project | resolved 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. |
| Generator | RemoteConfigSetting.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 config | firebase.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.Workflow
Section titled “Workflow”-
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 withfirebase_get_environment’s active project before publishing (see Hard rules). -
Generate — Editor open (
t1k unity statusis ok) → confirm it is bound to THIS project (binding is by working directory:projectRootint1k unity status/t1k unity instance currentmust be this checkout;unity-forbidden-operations.md§ instance trust), expose and invoke the private[Button]by reflection, then polldefault_config.json’s mtime for an advance —UniTask.Voidis fire-and-forget, so the call returns BEFORE the file is written. NOT reachable → use the on-diskdefault_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 thanRemoteConfigSetting.asset, warn before continuing. -
Ensure repo config —
firebase.json+.firebasercexist at repo root and the project matches step 1. Recreate only if missing, then commit them. -
Point the MCP —
firebase_update_environmentto this project’s dir + the resolved project id. -
Fetch the live template — prefer the MCP read tool
mcp__firebase__remoteconfig_get_template(it returns the template AND its version metadata,versionNumberincluded — which step 11 otherwise needs a separate command for). Thebunx 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 aTMPDIRbase — 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.firebasercprojects.default; the REST payload itself carries no project id field). -
Back up — copy the live template to
.claude/remote-config-backups/<project>-<UTC-ISO>.jsonBEFORE anything else. -
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. -
Diff + confirm — render the merge’s
added[]/changed[]/orphaned[]andAskUserQuestionthe 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. -
Dry-run —
?validate_only=trueon the REST endpoint is a REAL server-side dry run (not a local diff alone), andremoteconfig:getmirrors it withETag— use one of these pre-publish. -
Publish —
mcp__firebase__firebase_deploy(only: "remoteconfig"), afterfirebase_update_environmentfirebase.json/.firebasercare in place (step 4 + step 3). The deploy returns a jobId — pollfirebase_deploy_statusuntilstatus: success(itsresultis{}). Publishing the template directly instead of deploying is the other route:mcp__firebase__remoteconfig_update_template(full template object; it is a FULL REPLACE) — passforce:trueto bypass the ETag; without it this call can fail with a generic “Failed to publish” even though nothing changed server-side. Asuccessjob is NOT a publish. Record the liveversionNumberBEFORE publishing (step 5’s MCP read, elseversions: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.
-
Verify — re-fetch via step 5 (or read step 5’s own
versionNumberif 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.totalOutcounts parameters insideparameterGroupsONLY and excludes top-levelparameters. So the expected re-fetched total iscounts.totalOut + preserved.topLevelParameters. Comparing a re-fetched grand total againsttotalOutalone 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, confirmpreserved.conditionalValueParamsdid not drop, and assert the version advanced past the number recorded in step 10, then report it.remoteconfig:getdoes 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_templatereturnsversionNumberin the same response — use it and this extra call is unnecessary.) Report that number as the rollback target. Rolling back isbunx 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.mdExecuted by
Section titled “Executed by”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.
Hard rules
Section titled “Hard rules”- The MCP DOES have Remote Config tools (an earlier version of this file said it had none; that was wrong).
mcp__firebase__remoteconfig_get_templatereads (and returns version metadata);mcp__firebase__remoteconfig_update_templatepublishes a full template object (force:truebypasses the ETag — without it the call failed with a generic “Failed to publish” even though nothing had changed server-side).bunx firebase-tools remoteconfig:getstays a valid read path. The MCP publish (firebase_deploy(only:"remoteconfig")afterfirebase_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 generateddescription/defaultValue/valueType, KEEP itsconditionalValues(e.g. a develop-test condition onenable_aoa_resume_loading), then delete the top-level copy. Always eyeballset(parameters) ∩ keys(parameterGroups)before publishing. - Moving a top-level param into a group is also how a missing
descriptiongets filled — the generator supplies it fromRemoteConfigKeyDescriptions. 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 asorphanedwith 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_adtrue→false inRemoteConfigSetting.asset; the merge reported it as a plainchanged[]entry — publishing it would have disabled all AOA, including first open. Before the publish gate, diff the asset againstgit show HEAD:<config-asset>and name any flipped kill-switch (enable_*_ad,enable_ads) explicitly in the step-8AskUserQuestion. Also: editing the.asseton 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 getcrossChecked:falseplus a stderr warning — the id is valid but one-sided, so corroborate it againstfirebase_get_environment’s active project before publishing.crossChecked:falseis not a failure; silently ignoring it is. firebase_deployreturns a jobId, not a result. Pollfirebase_deploy_statusuntilstatus: success(itsresultis{}) and then re-fetch to verify — the job status is not verification. Requiresfirebase.json({"remoteconfig":{"template":"remoteconfig.template.json"}}).firebasercdefault project at repo root ANDfirebase_update_environment(project_dir, active_project)first.
- Generation via
t1k unity eval --file gen.cs(the facade now reaches the Pipelineeval_filecommand — 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(typeServiceImplementation.FireBaseRemoteConfig.RemoteConfigSetting). A multi-statement body ending in;is passed through verbatim (a bare expression would be wrapped inreturn …;). ConfirmApplication.dataPathis THIS project andisPlaying/isCompilingare false first; the file appears within ~1s. UniTask.Voidis fire-and-forget. The generator call returns BEFOREdefault_config.jsonis 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.
descriptionis 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.RemoteConfigKeyconst,RemoteConfigKeyDescriptionsentry, the read site (e.g.AdServicesConfig.FetchRemoteConfig), AND the default inRemoteConfigSetting.OnEnable()(TryAddAdsConfig/TryAddMiscConfig). Skip the last and it still compiles, but every project whose asset predates the key logsCannot 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 unitymutating call. Confirm no sibling session holds the Editor before driving any Editor-touching call, and timeouts may be contention, not failure (t1k-unity-editor-cliSKILL.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.mdor a README can go stale about which brand a repo actually ships. com.gdk.3rdis read-only. The generator lives there. A generator bug is a PR to that repo, never a local edit.AskUserQuestiongate (step 8) is mandatory, not cosmetic — this is the firewall between the merge and a destructive full-replace publish.firebase_deployreports 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
parameterGrouppublishes 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’sdetectfirst.
References
Section titled “References”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 evalreflection 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 fixedGOOGLE_APPLICATION_CREDENTIALS, key hygienereferences/key-semantics.md— the ad keys whose name does not match their effect (resume-AOA has no on/off switch;aoa_loading_thresholdis double-duty;is_inters_instead_aoa_first_openreads once in the Editor). Read before setting any AOA/interstitial value.