Firebrande documentation

Firebase operations, under control.

Firebrande gives teams a safer, clearer workspace for managing Firebase projects, data, storage, functions, and operational changes.

Getting started

Getting a team from zero to a working Firebase project inside Firebrande is four steps: create an account, start a plan, connect Google and a Firebase project, then open a workspace tool. Each step below shows the actual screen you'll see, in order.

Before you start

• A Google account that already has Owner, Editor, or a role with Firebase access on the project(s) you want to manage. Firebrande only discovers projects that account can already see.
• A card for checkout — every plan starts with a 14-day trial, but Stripe requires a payment method up front to start it.
• A modern browser (Chrome, Edge, Firefox, or Safari). No local install, CLI, or service-account key is required to get started.
• If you're inviting teammates later, decide who should hold the owner role — it's the only role that can transfer ownership or move projects between teams.

Step 1 — Create your account

The signed-out homepage is where every new user lands. Start 14-day trial opens sign-up; Sign in is for a returning account. Both use the same Clerk-hosted authentication card shown below, which supports Google sign-in alongside email and password — Firebrande itself never sees or stores your Google password.

Step 2 — Start a plan

Signing up creates your personal team automatically, but that team starts with no subscription. Firebrande's server-side gate sends any signed-in user without an active or trialing subscription to Plans & billing before it will open any other workspace — the only two routes it lets through unpaid are /billing itself and /teams, so you can always reach billing or check team membership. Choose Solo, Pro, or Team and start the trial from the plan card; Stripe hosts the actual checkout.

See Billing and entitlements for the full plan comparison and screenshot.

Step 3 — Connect Google and a Firebase project

With an active plan, open Team from the sidebar. The first time through, authorize Google access when prompted — Firebrande needs this to discover which Firebase projects your account can see. Once connected, every discoverable, not-yet-claimed project appears in the Connect Firebase projects panel; select one and choose Connect to bring it into the team.

See Connect a project for the full panel walkthrough, environment tagging, and the screenshot.

Step 4 — Open a workspace

Back on the workspace home (select the Firebrande logo, or Dashboard in the sidebar), the connected-project count in the header confirms the project is live, and the Workspace tools grid becomes the jumping-off point for Firestore, Functions, Storage, Team, Gemini, Community, and Billing. The left sidebar mirrors the same tools for every page you visit afterward.

Connect a project

Project connections live on the Teams page, scoped to whichever team you have selected in the sidebar. Owners and admins see a Connect Firebase projects panel listing every Firebase project Google discovers for the signed-in account that this team hasn't claimed yet. Pick one and select Connect to bring it into the workspace; a capacity badge in the panel header (for example 1 projects · team) tracks usage against the plan limit, and the connect button disables itself once the team is at capacity.

If Google access has expired, the panel shows Reconnect Google to discover Firebase projects instead of a list — sign in again from the account menu to refresh discovery. If nothing is missing but a project still won't show up, confirm the signed-in Google account can see that project in the Firebase console itself; Firebrande can only discover projects the connected account already has access to.

Connecting a project whose ID follows the common -dev/-staging/-prod naming pattern does two things automatically: it tags the project's environment to match, and it groups it with any other connected project that shares the same base name — so acme-app-dev and acme-app-prod land together under acme-app in the Firebase projects list below, instead of two unrelated rows. A group missing an environment shows a direct nudge (for example Missing Staging) rather than staying silent about it — the same one-project-per-environment setup Firebase's own documentation recommends, made visible instead of left to remember.

What Firebrande manages

Six Firebase and Google Cloud surfaces, one workspace. Every card below links to the full walkthrough, screenshots included.

Firestore

Inspect collections and documents, edit fields, build queries, manage indexes, and run export, import, and migration jobs.

Storage

Browse buckets and objects, update metadata, review access and lifecycle settings, and use protected upload and transfer operations.

Functions

Inspect deployments, logs, incidents, secrets, alerts, and operational metrics, with GitHub-backed deployment setup.

Authentication

Look up users, create or update accounts, manage verification and password-reset actions, and review bulk operations.

SQL Connect

Inspect services and schemas, run governed queries, compare source, generate SDK artifacts, and use approval-gated delivery.

Intelligence

Ask project-grounded questions across deployments, data, Storage, Authentication, and SQL Connect while keeping proposals reviewable.

Common workflows

Firestore

Firestore is the data workspace for browsing collections, querying documents, editing nested values, designing starter schemas, writing and auditing scripts, and running durable data jobs. Always confirm the active project and collection path before a write.

The Active projects bar pins which connected project the workspace is reading and writing against — every tab underneath stays scoped to it. Open a tab and use the collection picker to choose a path (including nested subcollections like customers/customer-001/events), then reach for Query, New, Export, Import, or Transfer from the workspace toolbar. Add Tab keeps several collections open side by side so you can compare data without losing your place.

Generate code and run scripts

Every document has a code panel: open any row and its detail view adds four Develop tabs — Code, Client Code, Schema, and Subcollections — next to the read-only Firestore and Fields & Tree views and the Editable JSON tab. Nothing here writes to the document; every tab reads the document you already opened and generates code from it.

Scriptlets

For anything beyond a single document, the Scriptlets drawer is a small script runtime scoped to the active project — open it from the terminal icon in the bottom-right corner of any Firestore tab. Write JavaScript or TypeScript against a provided ctx (db, projectId, collection), then Run current to execute a draft immediately or Save draft / Save as new… to keep it. Library lists every script saved with team visibility so a working script becomes something the whole team can reuse, and History keeps every prior version alongside its run log — each run recorded with a success, error, or pending status — so a script's behavior stays auditable, not just its code.

Authentication

The Authentication workspace manages Firebase Authentication identities for the selected project. Search by email, phone number, or user UID, then review account status, providers, verification, activity, MFA factors, and custom claims before taking action.

The user table shows providers, verification status, and last sign-in for every account, with filters for status, recent activity, and linked providers. Current page loads results a page at a time; Load all pulls the full project for bulk filtering. Create user opens a form for a new identity, and selecting a row opens its detail drawer for edits. The toolbar also holds Export, Import, and Transfer for moving users between projects, Operations for job history, and Settings, Scripts, and saved View configurations for the table itself.

Safe Authentication workflow

1. Confirm the active Firebase project and locate the user using a stable identifier.
2. Review providers, verification, disabled status, recent sign-in, MFA factors, and claims.
3. Choose the smallest action that solves the problem and record the reason.
4. For bulk actions, filter first, review the selected count, and type the exact confirmation phrase.
5. Refresh the user or review the operation job and audit entry after the change.

SQL Connect and data modeling

SQL Connect combines a PostgreSQL-backed data model with GraphQL operations and generated Firebase SDKs. Start with the service inventory, select a service, and use the workspace stages to move from modeling to controlled delivery.

The Operations workspace distinguishes query reads from mutation writes. Queries can be used for verification and contract tests. Mutations require explicit confirmation and should be followed by a read that verifies the persisted result. Generated SDKs are repository artifacts; check their configured platform, package, output directory, and commit before shipping them.

Functions

The Functions workspace brings source, GitHub delivery, deployments, logs, secrets, packages, metrics, and incidents together for each selected Firebase project. Use it as a release loop: configure the source, make a reviewable change, deploy through GitHub Actions, then observe the result.

Selecting a deployed function opens its Overview, showing timeout, memory, ingress settings, update time, version ID, runtime, entry point, and its HTTPS or event trigger at a glance. Logs, Metrics, and Source sit next to it as tabs on the same function, and Open Google Cloud jumps to the matching Cloud Console page when you need controls Firebrande doesn't surface directly.

For GitHub Actions setup, use Workload Identity Federation (OIDC) restricted to the intended repository. Configure the firebase-functions environment with the generated provider and service-account variables, add required reviewers in GitHub when supported, and verify the workflow run before treating a release as complete. Never add a service-account JSON key to the repository.

Storage

The Storage workspace manages Firebase Storage buckets and objects without hiding the underlying Google Cloud controls. Browse paths, upload files, inspect versions, update metadata, manage access, configure retention and lifecycle, and monitor folder operations from the selected project.

The bucket list on the left shows every bucket in the selected project; picking one opens its breadcrumb-based browser on the right, scoped to Current, Versions, or Deleted objects. A prefix search narrows the current folder, and Filter refines by type or metadata. Upload and New folder sit above the object table alongside a grid/list view toggle and a settings shortcut for the active bucket.

For sensitive buckets, review public access prevention and IAM before creating access links. Use resumable uploads for large files, validate content type and metadata, and treat exported objects and signed or tokenized links as sensitive credentials.

Intelligence

Firebrande Intelligence has two complementary surfaces. Change Intelligence compares live and Git architecture snapshots for release impact, while Gemini Intelligence answers questions using redacted, project-grounded context.

Gemini Intelligence pairs an Ask Firebrande chat panel — with request, token, and latency counters — against a Provider and policy panel where owners and admins pick the provider (Firebrande-managed Vertex AI or a bring-your-own Gemini API key), model, region, data policy, and usage retention, and can disable Intelligence for the project entirely. The Action review queue below it is where any AI-drafted operation (like a Functions deploy) waits as a named resource, action, and payload until a person approves it — nothing executes from a proposal automatically.

Teams and projects

Teams are the security boundary for collaborators and connected Firebase projects. Team managers control membership, project connections, environment safety, and explicit GitHub repository links. Workspace access then follows the member’s role and the selected project’s policy.

Project safety settings distinguish development, staging, and production and can mark a project read-only. Confirm the team, project ID, environment, and role before any production-sensitive operation.

Owners and admins invite teammates by email with a starting role directly from the Teams page (see the screenshot under Connect a project), and change or remove a member's role at any time. The same page's GitHub repository access panel is where repositories get explicitly linked to a project — Functions and SQL Connect delivery only reach repositories linked here, never a Google account's full repository list.

Billing and entitlements

Billing belongs to the team. Stripe hosts checkout, payment methods, invoices, and cancellation; Firebrande synchronizes subscription state and uses it to enforce paid access, seat capacity, and project capacity.

The Plans & billing page shows the team's Current subscription banner (plan and status) above the three plan cards, each listing its own limits and a trial-start button. Switch which team you're viewing with the team selector at the top — billing is always scoped to one team at a time, never to an individual project.

See docs/BILLING_ENTITLEMENTS.md for checkout, webhook reconciliation, plan limits, environment configuration, and billing incident runbooks.

Firebase Security Rules

Firebase Rules are the client-data authorization boundary for Firestore and Storage. They are separate from Firebrande team roles, Google Cloud IAM, and server credentials, so each layer must be reviewed independently.

The Rules editor lives under a bucket's or project's Settings panel. Edit the ruleset source directly, then either Compile only to catch syntax errors without publishing, or Deploy rules once you're confident. The Rules simulator runs a single request — path, method, authenticated or not — against the current draft and reports allow or deny, and Ruleset history keeps every previously deployed ruleset so you can see what changed and when.

See docs/FIREBASE_RULES.md for Firestore and Storage examples, simulator behavior, CI testing, deployment, and troubleshooting.

Security model

Firebrande combines account identity, team membership, project capability checks, project safety policies, and downstream Firebase or Google permissions. Every sensitive operation should be understood as a chain: user → team → project or resource → capability → external provider.

A confirmation phrase is a literal, typed guard on top of the button click: bulk-disabling users, for example, asks you to type DISABLE <count> — the exact operation and affected count — before Queue operation unlocks. The dialog also states how many users and projects will be touched and that separate durable jobs are created per project, so a multi-project bulk action can't silently apply everywhere at once.

• Never share OAuth tokens, invitation links, API keys, service-account keys, or download tokens.
• Use the least-privileged team role and external provider permission that supports the task.
• Prefer previews, dry runs, staging projects, protected branches, and explicit approvals.
• Record the project, resource, actor, operation, timestamp, and job or commit ID for sensitive changes.

Troubleshooting

When something fails, confirm the signed-in account, selected team, Firebase project ID, environment, read-only state, and exact operation before retrying. Firebrande uses clear failure boundaries: 401 means authentication, 403 means access or capability, 423 means read-only, and 409 usually means a resource conflict.

Some failures come with a built-in fix, not just an error string. A disabled Google Cloud API, for example, surfaces as a step-by-step recovery card with a direct link to enable it and a Retry button — the underlying error text stays visible underneath for anyone who needs to escalate it.

The repository guide docs/TROUBLESHOOTING.md contains symptom-by-symptom runbooks for every workspace.

Safety and access

Firebrande applies team-aware access to connected projects. Some workspaces and operations are read-only, and destructive or production-sensitive actions ask for an explicit confirmation. Treat the selected project as part of the change record: verify its name and ID before acting.

• Use least-privilege Google and Firebase access for each team member.
• Prefer development projects for imports, migrations, policy experiments, and deployment rehearsals.
• Review a preview, diff, or plan before applying a bulk operation.
• Keep credentials, tokens, and secrets out of documents, scripts, commits, and screenshots.

The read-only switch itself lives per project in the Teams page's Environment safety panel (see the screenshot under Connect a project) — checking it blocks writes across every workspace for that project until it's cleared again, regardless of a member's role.

Before launch

1. Confirm your Firebase project and team access.
2. Review security rules and production safeguards.
3. Run a representative workflow in a non-production project.
4. Invite your team and agree on a change-review process.

Core guides: docs/WORKSPACE_OPERATIONS.md covers operational workflows, docs/LIVE_FIREBASE_TESTING.md covers live Firebase verification, and docs/TROUBLESHOOTING.md contains symptom-by-symptom runbooks.