Support Firebase SDK auto-initialization for Cloud Run services

src/commands/run-services-update.ts

@@ -16,6 +16,8 @@ export const command = new Command("run:services:update <serviceId>")
     "set the base image (e.g. nodejs22) and enable automatic base image updates",
   )
   .option("--clear-base-image", "clear the base image and disable automatic base image updates")
+  .option("--app <appId>", "associate a Firebase Web App ID for SDK auto-initialization")
+  .option("--clear-app", "disassociate the Firebase Web App and disable SDK auto-initialization")
   .before(requireConfig)
   .before(requirePermissions, TARGET_PERMISSIONS.run)
   .action((serviceId: string, options: Options) =>

src/deploy/apphosting/prepare.ts

@@ -318,6 +318,8 @@ export async function injectAutoInitEnvVars(
       )) as WebConfig;
 
       // We inject autoinit env vars into the build and runtime env vars.
+      // TODO: Match FAH remote builds by only injecting FIREBASE_CONFIG (and not
+      // FIREBASE_WEBAPP_CONFIG) into runtimeEnv.
       const autoinitVars = getAutoinitEnvVars(webappConfig);
       for (const [envVarName, envVarValue] of Object.entries(autoinitVars)) {
         buildEnv[cfg.backendId][envVarName] ??= { value: envVarValue };

src/deploy/run/args.ts

@@ -16,6 +16,12 @@ export interface ServiceDeploy {
    * this deploy sets or clears it. Undefined means none, so automatic base image updates are off.
    */
   baseImage?: string;
+  /**
+   * Set by prepare: the linked Firebase Web App, if any. Deploy saves `appId` on the service so
+   * later deploys reuse it, and sets `firebaseConfig` as the FIREBASE_CONFIG env var, which the
+   * Admin SDK reads at runtime.
+   */
+  autoInit?: { appId: string; firebaseConfig: string };
   /**
    * Set by prepare: the build-time env vars from the service's annotation, each a plain value or
    * a secret. Only local builds can use secrets: builds on Cloud Build only take plain values.
@@ -33,4 +39,6 @@ export interface Context {
   projectId: string;
   /** Overrides the service's base image. null clears it; undefined keeps the current one. */
   baseImage?: string | null;
+  /** Overrides the service's Firebase Web App ID. null clears it; undefined keeps the current one. */
+  appId?: string | null;
 }

src/deploy/run/deploy.spec.ts

@@ -14,6 +14,7 @@
 
 const NODEJS22 = "us-central1-docker.pkg.dev/serverless-runtimes/google-22/runtimes/nodejs22";
 const DEPLOY_MESSAGE = "firebase.google.com/deploy-message";
+const APP_ID = "firebase.google.com/app-id";
 
 describe("run deploy", () => {
   const options = { config: { projectDir: "/project" } } as unknown as Options;
@@ -76,7 +77,7 @@
     await deployOne({ config: web });
 
     // Without a base image, Cloud Build can't turn on automatic base image updates.
     const { buildpackBuild } = submitBuildStub.firstCall.args[2];
     expect(buildpackBuild).not.to.have.property("baseImage");
     expect(buildpackBuild).not.to.have.property("enableAutomaticUpdates");
   });
@@ -86,7 +87,7 @@
 
     await deployOne({ config: web, buildEnv });
 
     const { environmentVariables } = submitBuildStub.firstCall.args[2].buildpackBuild;
     expect(environmentVariables).to.include({ API_URL: "https://api.example.com" });
     expect(environmentVariables).not.to.have.property("NPM_TOKEN");
   });
@@ -112,16 +113,65 @@
     expect(updateServiceStub).to.have.been.calledOnceWithExactly(
       {
         name: "projects/my-project/locations/us-central1/services/web",
+        annotations: {},
         template: { containers: [{ name: "web", image }] },
         traffic: [
           { type: "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST", percent: 100 },
           { type: "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION", revision: "web-000", tag: "preview" },
         ],
       },
-      { updateMask: ["template", "traffic"], pollTimeoutMs: 10 * 60 * 1000 },
+      { updateMask: ["template", "traffic", "annotations"], pollTimeoutMs: 10 * 60 * 1000 },
     );
   });
 
+  describe("linked Firebase Web App", () => {
+    const linkedWeb = {
+      name: "projects/my-project/locations/us-central1/services/web",
+      annotations: { team: "frontend", [APP_ID]: "1:123:web:abc" },
+      template: { containers: [{ name: "web", image: "old-image" }] },
+    } as unknown as runv2.Service;
+
+    it("is saved on a new service", async () => {
+      await deployOne({ config: web, autoInit: { appId: "1:123:web:abc", firebaseConfig: "{}" } });
+
+      expect(createServiceStub).to.have.been.calledWithMatch("my-project", "us-central1", "web", {
+        annotations: { [APP_ID]: "1:123:web:abc" },
+      });
+    });
+
+    it("replaces the app saved on an existing service", async () => {
+      await deployOne({
+        config: web,
+        existing: linkedWeb,
+        autoInit: { appId: "1:123:web:def", firebaseConfig: "{}" },
+      });
+
+      expect(updateServiceStub).to.have.been.calledWithMatch(
+        { annotations: { team: "frontend", [APP_ID]: "1:123:web:def" } },
+        { updateMask: ["template", "traffic", "annotations"] },
+      );
+    });
+
+    it("is removed when the service is unlinked", async () => {
+      await deployOne({ config: web, existing: linkedWeb });
+
+      expect(updateServiceStub.firstCall.args[0].annotations).to.deep.equal({ team: "frontend" });
+    });
+
+    it("keeps the service's annotations as they are if the app didn't change", async () => {
+      await deployOne({
+        config: web,
+        existing: linkedWeb,
+        autoInit: { appId: "1:123:web:abc", firebaseConfig: "{}" },
+      });
+
+      expect(updateServiceStub.firstCall.args[0].annotations).to.deep.equal({
+        team: "frontend",
+        [APP_ID]: "1:123:web:abc",
+      });
+    });
+  });
+
   describe("local builds", () => {
     const localWeb = { ...web, localBuild: true };
     let rmSyncStub: sinon.SinonStub;
@@ -149,7 +199,7 @@
     /** Deploys web with "localBuild": true and returns the container that it rolled out. */
     async function deployLocalBuild(): Promise<runv2.Container> {
       await deployOne({ config: localWeb, baseImage: NODEJS22 });
       return createServiceStub.firstCall.args[3].template.containers[0];
     }
 
     it("builds on this machine, in a scratch folder that it deletes afterwards", async () => {
@@ -308,6 +358,54 @@
       expect(template).to.deep.equal({ containers: [{ name: "web", image }] });
     });
 
+    describe("FIREBASE_CONFIG", () => {
+      /** The live web service, with FIREBASE_CONFIG set to `value`. */
+      function withConfig(value: string): runv2.Service {
+        return webRunning({ env: [{ name: "FIREBASE_CONFIG", value }] });
+      }
+      const linked = { ...withConfig("old"), annotations: { [APP_ID]: "1:123:web:abc" } };
+
+      it("is set from the linked app's current config", () => {
+        const svc = {
+          config: web,
+          existing: linked,
+          autoInit: { appId: "1:123:web:abc", firebaseConfig: "current" },
+        };
+
+        const template = revisionTemplate(svc, image);
+
+        expect(template.containers?.[0].env).to.deep.equal([
+          { name: "FIREBASE_CONFIG", value: "current" },
+        ]);
+      });
+
+      it("is removed when the app is unlinked, and the other env vars stay", () => {
+        const existing = {
+          ...webRunning({
+            env: [
+              { name: "MODE", value: "prod" },
+              { name: "FIREBASE_CONFIG", value: "old" },
+            ],
+          }),
+          annotations: { [APP_ID]: "1:123:web:abc" },
+        };
+
+        const template = revisionTemplate({ config: web, existing }, image);
+
+        expect(template.containers?.[0].env).to.deep.equal([{ name: "MODE", value: "prod" }]);
+      });
+
+      it("is left alone if the user set it on a service that was never linked", () => {
+        const svc = { config: web, existing: withConfig("mine") };
+
+        const template = revisionTemplate(svc, image);
+
+        expect(template.containers?.[0].env).to.deep.equal([
+          { name: "FIREBASE_CONFIG", value: "mine" },
+        ]);
+      });
+    });
+
     describe("localBuildTemplate", () => {
       it("runs a local build's output with the build's start command", () => {
         // The command is split on whitespace, so stray spaces don't become empty arguments.

src/deploy/run/deploy.ts

@@ -17,7 +17,7 @@
 import { createLocalBuildTarArchive, createSourceDeployArchive } from "../apphosting/util";
 import { Context, Payload, ServiceDeploy } from "./args";
 import { nonSecretValues, secretNames, toLocalBuildEnv } from "./buildEnv";
-import { mainContainer } from "./util";
+import { FIREBASE_APP_ANNOTATION, mainContainer } from "./util";
 
 const DEPLOY_MESSAGE_ANNOTATION = "firebase.google.com/deploy-message";
 /** Rolling out a revision can take longer than the operation poller's default timeout. */
@@ -128,7 +128,7 @@
         e.value !== undefined &&
         (!e.availability || e.availability.includes("RUNTIME")),
     )
     .map((e) => ({ name: e.variable, value: e.value! }));
   return { outputFiles, runCommand: buildConfig.runCommand, env };
 }
 
@@ -265,6 +265,21 @@
   } else {
     delete container.baseImageUri;
   }
+  // FIREBASE_CONFIG is how the Admin SDK auto-initializes at runtime. The client SDK's
+  // FIREBASE_WEBAPP_CONFIG is only needed at build time, so it isn't set on the container.
+  // TODO: Stop setting FIREBASE_CONFIG once Cloud Run injects it from the app-id annotation.
+  const wasLinked = svc.existing?.annotations?.[FIREBASE_APP_ANNOTATION] !== undefined;
+  const otherEnv = (container.env || []).filter((e) => e.name !== "FIREBASE_CONFIG");
+  if (svc.autoInit) {
+    // An app is linked. Always rewrite FIREBASE_CONFIG from the app's current config, so that
+    // changes like enabling Storage reach the service.
+    container.env = [...otherEnv, { name: "FIREBASE_CONFIG", value: svc.autoInit.firebaseConfig }];
+  } else if (wasLinked) {
+    // This deploy unlinks the app (--clear-app): the service had an app, and the deploy has none.
+    // Remove the FIREBASE_CONFIG that was set for the app.
+    container.env = otherEnv;
+  }
+  // Otherwise the service was never linked, so a FIREBASE_CONFIG on it is the user's. It stays.
   // The message describes this deploy only, so don't carry over the last one.
   if (message) {
     template.annotations = { ...template.annotations, [DEPLOY_MESSAGE_ANNOTATION]: message };
@@ -287,7 +302,7 @@
 ): runv2.RevisionTemplate {
   const template = revisionTemplate(svc, NO_IMAGE, message);
   // revisionTemplate has already checked that there's a container.
   const container = mainContainer(template)!;
   container.sourceCode = { cloudStorageSource: builtApp };
   // Split on any whitespace, so that stray spaces don't become empty arguments.
   const command = build.runCommand?.trim();
@@ -309,58 +324,75 @@
   return template;
 }
 
+/**
+ * Returns the service's annotations after this deploy: its current ones, with the linked Firebase
+ * Web App's ID set, or removed if no app is linked. Later deploys read the ID back to reuse the app.
+ */
+function serviceAnnotationsToDeploy(svc: ServiceDeploy): Record<string, string> {
+  const annotations = { ...svc.existing?.annotations };
+  if (svc.autoInit) {
+    annotations[FIREBASE_APP_ANNOTATION] = svc.autoInit.appId;
+  } else {
+    delete annotations[FIREBASE_APP_ANNOTATION];
+  }
+  return annotations;
+}
+
 /** Rolls out the new revision: creates the service if it's new, or updates it. */
 function rollOut(
   projectId: string,
   svc: ServiceDeploy,
   template: runv2.RevisionTemplate,
 ): Promise<runv2.Service> {
+  const annotations = serviceAnnotationsToDeploy(svc);
   if (svc.existing) {
-    return deployRevision(svc.existing, template);
+    return deployRevision(svc.existing, template, annotations);
   }
-  return createNewService(projectId, svc.config, template);
+  return createNewService(projectId, svc.config, template, annotations);
 }
 
 /** Creates a new service with its first revision. */
 function createNewService(
   projectId: string,
   config: RunSingle,
   template: runv2.RevisionTemplate,
+  annotations: Record<string, string>,
 ): Promise<runv2.Service> {
   const { serviceId, region } = config;
-  return runv2.createService(
-    projectId,
-    region,
-    serviceId,
-    {
-      name: `projects/${projectId}/locations/${region}/services/${serviceId}`,
-      template,
-      client: "cli-firebase",
-      // Like an App Hosting backend, the service is public.
-      invokerIamDisabled: true,
-      ingress: "INGRESS_TRAFFIC_ALL",
-    },
-    { pollTimeoutMs: ROLLOUT_TIMEOUT_MS },
-  );
+  const service: Omit<runv2.Service, runv2.ServiceOutputFields> = {
+    name: `projects/${projectId}/locations/${region}/services/${serviceId}`,
+    annotations,
+    template,
+    client: "cli-firebase",
+    // Like an App Hosting backend, the service is public.
+    invokerIamDisabled: true,
+    ingress: "INGRESS_TRAFFIC_ALL",
+  };
+  return runv2.createService(projectId, region, serviceId, service, {
+    pollTimeoutMs: ROLLOUT_TIMEOUT_MS,
+  });
 }
 
 /** Rolls out a new revision of an existing service and sends it all traffic. */
 function deployRevision(
   service: runv2.Service,
   template: runv2.RevisionTemplate,
+  annotations: Record<string, string>,
 ): Promise<runv2.Service> {
   // Tagged revisions keep their tags (Hosting's pinned rewrites use them), but no traffic.
   const tags = (service.traffic || [])
     .filter((t) => t.tag)
     .map((t) => ({ type: t.type, revision: t.revision, tag: t.tag }));
-  return runv2.updateService(
-    {
-      name: service.name,
-      template,
-      traffic: [{ type: "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST", percent: 100 }, ...tags],
-    },
-    { updateMask: ["template", "traffic"], pollTimeoutMs: ROLLOUT_TIMEOUT_MS },
-  );
+  const update: Omit<runv2.Service, runv2.ServiceOutputFields> = {
+    name: service.name,
+    annotations,
+    template,
+    traffic: [{ type: "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST", percent: 100 }, ...tags],
+  };
+  return runv2.updateService(update, {
+    updateMask: ["template", "traffic", "annotations"],
+    pollTimeoutMs: ROLLOUT_TIMEOUT_MS,
+  });
 }
 
 /** Adapts a Cloud Run config so that it can reuse App Hosting's local build and archive helpers. */