Configure and manage App Hosting backends

App Hosting has been designed for ease of use and low maintenance, with default settings optimized for most use cases. At the same time, App Hosting provides tools for you to manage and configure backends for your specific needs. This guide describes those tools and processes.

Set and update environment variables and secrets

App Hosting lets you use environment variables for non-sensitive configuration values and secrets for sensitive parameters like API keys, database credentials, and service tokens.

  • Standard environment variables: Used for non-sensitive, plain-text configurations (such as public API URLs, feature flags, or build targets). Values are visible to all project members.
  • Secrets: Used for sensitive parameters (such as OAuth client secrets, API tokens, or database passwords). Secrets are backed by Cloud Secret Manager. Secret values are protected and never displayed in plain text in the Firebase console; instead, the console provides deep links to view and manage secret values directly in Cloud Secret Manager.

You can define and manage environment parameters using two complementary approaches:

  • Firebase console: Quickly add, edit, and attach secrets or variables dynamically during initial backend creation or post-deployment in backend settings.

  • Code-first (apphosting.yaml): Declare environment variables and secret references in your repository's configuration file for version-controlled deployments, or use apphosting.<env>.yaml to set different values for different environments.

Firebase console

A screen capture of the Firebase console dialog for adding environment variables

apphosting.yaml 

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

Manage variables and secrets in the Firebase console

You can configure environment variables and secrets in the Firebase console when creating a backend or at any time from your backend settings. Changes saved without deploying take effect on your next rollout and don't affect the current one.

Set up variables and secrets during backend creation

When creating a new App Hosting backend in the Firebase console, you can configure standard environment variables and secrets during the Configure your backend step of the setup wizard:

  1. In the Firebase console, navigate to Hosting & Serverless > App Hosting and click Create backend.
  2. Complete the initial wizard steps to select your primary region and code repository.
  3. In the Configure your backend section, locate the collapsible cards for Environment variables and Secrets, where you can add standard variables and attach secrets.
  4. Complete the backend creation wizard and click Finish & deploy.

Manage variables and secrets in backend settings

You can view, add, edit, or delete environment variables and secrets for active backends from the backend settings dashboard:

  1. In the Firebase console, select your App Hosting backend and open Settings > Environment.
  2. Review existing configurations in the Environment variables table:
    • Standard variables: Values are displayed as plain text in copyable code blocks.
    • Secrets: Displayed as a clickable link showing the secret name (which opens Cloud Secret Manager in the Google Cloud console) alongside its targeted version (such as latest or a specific version number like 2).
  3. To add a variable or secret:
    1. Click Add new.
    2. In Step 1: Select type, choose Standard environment variable (for non-sensitive data visible to all project members) or Secret (for API keys and sensitive credentials with restricted access), and then click Next.
    3. In Step 2: Configure settings, enter the Key name and either the plain-text Value (for standard variables) or select the Secret ID and Version (for secrets).
    4. Save your changes using one of the following options:
      • Save and deploy: Immediately updates the backend configuration and triggers a new build and rollout.
      • Just save (from the drop-down arrow next to Save and deploy): Saves the configuration changes without triggering an immediate rollout. The updated settings take effect on your next deployment.
  4. To edit or delete an existing entry, click the More actions (...) menu at the end of the row:
    • Select Edit to modify the key, value, secret mapping, or version, and then click Save and deploy or Just save.
    • Select Delete and confirm removal in the dialog.

Transfer variables from dotenv files

For Next.js apps, dotenv files containing environment variables work with App Hosting.

When creating or updating a backend, you can transfer environment variables from your dotenv file to the Firebase console by copying and pasting the entire contents of the dotenv file into the first Key field in the Add new form in Settings > Environment.

All the environment variables copied this way are automatically formatted into the form without needing to enter each one individually, as long as the input uses standard KEY=value formatting:

KEY1=value1
KEY2=value2
KEY3=value3

For complex or granular environment variable control with any framework, we recommend using apphosting.yaml.

Manage variables and secrets in apphosting.yaml

For code-first workflows, declare standard environment variables and secret references under the env: key in your project repository's apphosting.yaml configuration file (see Create and edit apphosting.yaml).

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

Each entry in env: supports the following fields:

  • variable: The environment variable name exposed to your application process.
  • value: The plain-text string value (for standard environment variables).
  • secret: The Cloud Secret Manager secret reference (for secrets). You can use the short secret name (such as myGeminiApiKeySecret or pinned myGeminiApiKeySecret@1) or the full resource path (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). See Store and access secret parameters for more details.
  • availability: Controls whether the variable or secret is accessible during the BUILD phase, at RUNTIME, or both.

Set variable availability

Environment variables and secrets configured in the Firebase console are available at both build time and run time. This is also the default behavior for entries defined in apphosting.yaml unless you narrow the scope using the availability property. In apphosting.yaml (but not in the console), you can restrict a variable or secret to only the build environment (BUILD) or only the runtime environment (RUNTIME).

Access variables and secrets in application code

Whether configured in the Firebase console or apphosting.yaml, environment variables and secrets are exposed to your application runtime as standard environment variables (for example, process.env in Node.js).

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • Server-side access: All environment variables and secrets are securely accessible in server-side execution contexts (such as Next.js Server Components, API routes, or Node.js backend handlers).

  • Client-side exposure: To expose standard environment variables to the browser in frameworks like Next.js, ensure the variable key follows framework conventions (for example, prefixed with NEXT_PUBLIC_).

    env:
  - variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

Variable hierarchy

Firebase App Hosting applies your environment variables and secrets in an order of precedence based on their source. Configurations set in the Firebase console always override parameters declared in apphosting.yaml and dotenv files. If an environment variable or secret key with the same name exists in both apphosting.yaml and the Firebase console, the console value takes precedence during build and runtime execution.

Here is the full order of precedence:

  1. Firebase console → variables and secrets set in the console
  2. apphosting.<env>.yaml → variables and secrets specified in an environment-specific YAML file such as apphosting.staging.yaml (see Deploy multiple environments)
  3. apphosting.yaml → variables and secrets specified in the apphosting.yaml file
  4. Firebase system → variables set by Firebase that contain values for FIREBASE_CONFIG or FIREBASE_WEBAPP_CONFIG, as well as environment variables that set the hostnames and ports for SSR apps (set by App Hosting adapters in bundle.yaml)

Automatically populated environment variables

There are environment variables that are automatically populated by App Hosting. These include those populated by Google Cloud, as well as Firebase-specific environment variables when appId is set on the backend during setup:

  • FIREBASE_CONFIG: (available in the build & runtime environments) Provides the following Firebase project config info:

    {
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "storageBucket": "PROJECT_ID.firebasestorage.app",
  "projectId": "PROJECT_ID"
}

    This configuration is applied automatically when you initialize the Firebase Admin SDK with no arguments.

  • FIREBASE_WEBAPP_CONFIG: (available in the build environment only) Provides the following Firebase project config info:

    {
  "apiKey": "API_KEY",
  "appId": "APP_ID",
  "authDomain": "AUTH_DOMAIN.firebaseapp.com",
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "messagingSenderId": "PROJECT_NUMBER",
  "projectId": "PROJECT_ID",
  "storageBucket": "PROJECT_ID.firebasestorage.app"
}</span>

    The Firebase JS SDK automatically checks for this FIREBASE_WEBAPP_CONFIG environment variable in a postinstall script during build, allowing you to also initialize the client SDK without any arguments.

See Automatically initialize Firebase Admin SDK and web SDKs for more details on how to use these environment variables to initialize the SDKs.

Note that the values in your actual Firebase configuration will correspond to the particular resources you've provisioned in your project.

Variable hierarchy

Firebase App Hosting applies your variables in an order of precedence based on their source. For example, values set in the Firebase console always override, or take precedence over, values set in apphosting.yaml and dotenv files.

Here is the full order of precedence:

  1. Firebase console → variables set in the console
  2. apphosting.<env>.yaml → variables specified in an environment specific yaml file such as apphosting.staging.yaml (see Deploy multiple environments)
  3. apphosting.yaml → variables specified in the apphosting.yaml file
  4. Firebase system → variables set by Firebase that contain values for firebase_config json or firebase_webapp_config, as well as environment variables that set the hostnames and ports for SSR apps (set by App Hosting adapters in bundle.yaml)

Reserved names and limitations

The environment variables defined in the Cloud Run container runtime contract are reserved and can't be set.

Environment variables that are provided by the environment, other than the ones that are set automatically, might change in future runtime versions. As a best practice, we recommend that you don't depend on or modify any environment variables that you haven't set explicitly, and consider prefixing any environment variables with a unique key to avoid conflicts.

Some environment variable keys are reserved for internal use. Don't use any of these keys in your configuration files:

  • Empty strings ("")
  • Keys that contain "="
  • Keys beginning with X_FIREBASE_, X_GOOGLE_, or CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Duplicate Keys

Create and edit apphosting.yaml

For advanced configuration such as secrets or runtime settings such as concurrency, CPU, and memory limits, you'll need to create and edit the apphosting.yaml file in your app's root directory. This file supports references to secrets managed with Cloud Secret Manager, making it safe to check into source control.

To create apphosting.yaml, run the following command:

firebase init apphosting

This creates a basic starter apphosting.yaml file with example (commented) configuration. After editing, a typical apphosting.yaml file might look like the following, with settings for the backend's Cloud Run service, some environment variables, and some references to secrets managed by Cloud Secret Manager:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

The rest of this guide provides more information and context for these example settings.

Configure Cloud Run service settings

With apphosting.yaml settings, you can configure how your Cloud Run service is provisioned. The available settings for the Cloud Run service are provided in the runConfig object:

Note that cpu, memoryMiB, and concurrency have interdependent limits (for example, higher memory configurations require higher minimum CPU limits, and fractional CPUs require a concurrency of 1). See the Cloud Run documentation on CPU limits and memory limits for valid ranges and required combinations.

Override build and run scripts

App Hosting infers your app's build and start command based on the detected framework. If you want to use a custom build or start command, you can override App Hosting's defaults in apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

The build command override takes precedence over any other build commands and opts your app out of the framework adapters and disables any framework specific optimizations that App Hosting provides. It's best used when your app features aren't well supported by the adapters. If you want to change your build command but still use the provided adapters, set your build script in package.json instead as described in App Hosting framework adapters.

Use the run command override when there is a specific command you want to use to start your app that's different from the App Hosting-inferred command.

Configure build output

App Hosting optimizes your app deploys by default by deleting unused output files as indicated by the framework. If you want to further optimize your app deploy size or ignore the default optimizations, you can override this in apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

The include parameter takes in a list of directories and files relative to the app root directory that are necessary to deploy your app. If you want to make sure that all files are kept, set include to [.] and all files will be deployed.

Store and access secret parameters

Sensitive information such as API keys should be stored as secrets. You can attach secrets to your backend in the Firebase console or reference them in apphosting.yaml to avoid checking sensitive information into source control.

Parameters of type secret represent string parameters that have a value stored in Cloud Secret Manager. Instead of deriving the value directly, secret parameters check against existence in Cloud Secret Manager and load the values during rollout.

env:
  - variable: API_KEY
    secret: myApiKeySecret

Secrets in Cloud Secret Manager can have multiple versions. By default, the value of a secret parameter available to your live backend is pinned to the latest available version of the secret at the time the backend was built. If you have requirements for versioning and lifecycle management of parameters, you can pin to specific versions in the Firebase console or in apphosting.yaml. For example, to pin to version 5 in apphosting.yaml:

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

You can create secrets with the Firebase CLI command firebase apphosting:secrets:set, and you'll be prompted to add necessary permissions. This flow gives you the option to automatically add the secret reference to apphosting.yaml.

Grant access to Cloud Secret Manager

For App Hosting to fetch secret values during build and runtime rollouts, the App Hosting backend service account must have permission to access Cloud Secret Manager.

If you create secrets using the Cloud Secret Manager console or gcloud CLI instead of firebase apphosting:secrets:set, grant access to your backend using the Firebase CLI:

firebase apphosting:secrets:grantaccess SECRET_NAME

Alternatively, you can grant the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) to the App Hosting service agent (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) or your backend's runtime service account using the gcloud CLI:

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Console access and role-based permissions

The Firebase console dynamically restricts environment and secret management features based on user IAM permissions:

  • Viewer role: Users with read-only project permissions can view existing configuration settings but cannot make changes.
    • During backend creation, the Create backend button is disabled.
    • In backend Settings > Environment, the Add new button is disabled and the More actions (...) row menus are hidden.
  • Missing Secret Manager permissions: Users who do not have IAM permissions to interact with Cloud Secret Manager see a warning message in the console (Ask a project owner for permission to add secrets):
    • During backend creation, the Secrets card is disabled.
    • In backend Settings > Environment, the Secret option is disabled when clicking Add new, and some of the options in the More actions (...) row menu are hidden on existing secret entries.

Configure VPC access

Your App Hosting backend can connect to a Virtual Private Cloud (VPC) network. For more information and an example, see Connect Firebase App Hosting to a VPC network.

Use the vpcAccess mapping in your apphosting.yaml file to configure access. Use either a fully qualified network/connector name or an ID. Using IDs allows for portability between staging and production environments with different connectors/networks.

Direct VPC Egress Configuration (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

Serverless Connector Configuration (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Manage backends

Commands for basic management of App Hosting backends are provided in the Firebase console and the Firebase CLI. This section describes some of the more common management tasks, including creating and deleting backends.

Create a backend

An App Hosting backend is the collection of managed resources that App Hosting creates to build and run your web app.

Firebase console: Navigate to Hosting & Serverless > App Hosting, and then click Create backend (if this is the first backend in your Firebase project, click Get started).

Firebase CLI: (v13.15.4 or later) To create a backend, run the following command from the root of your local project directory, supplying your project ID as an argument:

firebase apphosting:backends:create --project PROJECT_ID

For both console or CLI, follow the prompts to choose a region, set up a GitHub connection, and configure these basic deployment settings:

  • Set your app's root directory (defaults to /)

    This is usually where your package.json file is located.

  • Set the live branch

    This is the branch of your GitHub repository that gets deployed to your live URL. Often, it's the branch into which feature branches or development branches are merged.

  • Accept or decline automatic rollouts

    Automatic rollouts are enabled by default. At completion of backend creation, you can choose for your app to be deployed to App Hosting immediately.

  • Assign a name to your backend.

  • Select your runtime environment. By default, the newest recommended Node.js version is pre-selected for you.

    • Configure Automatic Base Image Updates (ABIU). ABIU is enabled by default and automatically applies security patches to your underlying environment. You can opt out of ABIU by selecting "Not specified" for your runtime.

Delete a backend

To fully remove a backend, first use the Firebase console or the Firebase CLI to delete it, and then manually remove related assets, taking special care not to delete any resources that might be used by other backends or other aspects of your Firebase project.

Firebase console: From the Settings menu, select Delete backend.

Firebase CLI: (v13.15.4 or later)

  1. Run the following command to delete the App Hosting backend. This disables all domains for your backend and deletes the associated Cloud Run service:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Optional) In the Google Cloud console tab for Artifact Registry, delete the image for your backend in "firebaseapphosting-images".

  3. In Cloud Secret Manager, delete any secrets with "apphosting" in the secret name, taking special care to make sure these secrets aren't used by other backends or other aspects of your Firebase project.