Version Security Rules and Index Definitions, CI Validation, Staged Deployment, and Rollback

1. AtlasMart drift incident: console hotfix meets source control

A developer fixes a production Rules bug in the console. Another engineer merges a repository change to firestore.rules and deploys with the CLI. The local file overwrites the console rules, reintroducing the bug. At the same time, a new query passed in the emulator because compound indexes are not tracked there, but production rejects it until a composite index finishes building.

The repair is not “be more careful.” Rules and index definitions are release artifacts: version them, diff them, test them, deploy them in a deliberate order, and record the resulting release evidence.

2. Source-of-truth files

rules_version = '2';service cloud.firestore {  match /databases/{database}/documents {    function signedIn() { return request.auth != null; }    function sameTenant(tenantId) {      return signedIn() && request.auth.token.tenantId == tenantId;    }    match /products/{productId} {      allow read: if resource.data.visibility == "public"                  || sameTenant(resource.data.tenantId);      allow write: if sameTenant(request.resource.data.tenantId)                   && request.resource.data.schemaVersion in [1, 2];    }    match /orders/{orderId} {      allow read, write: if sameTenant(resource.data.tenantId);      allow create: if sameTenant(request.resource.data.tenantId);    }  }}

{  "indexes": [    {      "collectionGroup": "products",      "queryScope": "COLLECTION",      "fields": [        { "fieldPath": "tenantId", "order": "ASCENDING" },        { "fieldPath": "active", "order": "ASCENDING" },        { "fieldPath": "updatedAt", "order": "DESCENDING" }      ]    }  ],  "fieldOverrides": [    {      "collectionGroup": "products",      "fieldPath": "rawDescription",      "indexes": []    }  ]}

The repository copy is authoritative for automated releases. If the console is used for emergency response, export/reconcile the change into source control before the next CLI deployment.

3. CLI deployment selectors and what they change

4. There is no magic dry-run for production semantics

Local Rules tests are strong for authorization logic. Index JSON is reviewable and deployable. But the emulator cannot prove composite-index requirements/readiness. Use a separate managed staging project/database for production-only checks. Do not call a local emulator run a “dry-run deployment.”

set -euo pipefail# 1. Local deterministic gatefirebase emulators:exec --project demo-atlasmart-firestore \  --only auth,firestore "npm run test:rules && npm run test:integration"# 2. Explicit human/CI identity chooses STAGING, never implicit active projectfirebase deploy --project atlasmart-staging --only firestore:rulesfirebase deploy --project atlasmart-staging --only firestore# 3. Run bounded staging canary that exercises each new query shapenode scripts/canary-staging.mjs# 4. Production promotion is a separate approved job# firebase deploy --project atlasmart-prod --only firestore:rules# firebase deploy --project atlasmart-prod --only firestore

5. Deployment ordering is a compatibility problem

6. CI diff gate: reject unreviewed Rules/index drift

import fs from "node:fs";import crypto from "node:crypto";const files = ["firestore.rules", "firestore.indexes.json"];for (const file of files) {  const text = fs.readFileSync(file, "utf8");  const sha = crypto.createHash("sha256").update(text).digest("hex");  console.log(`${file} ${sha}`);  if (/(?:TO\x44O)|allow read, write: if true/.test(text)) {    throw new Error(`unsafe marker in ${file}`);  }}JSON.parse(fs.readFileSync("firestore.indexes.json", "utf8"));

Store hashes in the release record with commit SHA, Firebase CLI version, project/database ID and test results. The hash does not prove correctness; it proves which exact configuration was reviewed and deployed.

7. Rules rollback and index rollback are not symmetric

Rules can be restored to a previous reviewed ruleset, but active clients may experience propagation delay. An index change has build/delete lifecycle and query dependencies. Therefore rollback must be application-aware:

8. Controlled failure: deploy rules and indexes together with unready app

Failure: a one-shot release simultaneously removes schema-v1 access, deploys an index, and releases schema-v2-only code. Old clients fail immediately; new code can race index build.

Repair: expand compatibility first, add index, verify, release code behind flag, backfill, observe, then contract Rules/schema. This is the database version of expand–migrate–contract.

9. Mandatory lab

1. Add a composite query to AtlasMart products: tenantId == t-red, active == true, order by updatedAt desc.
2. Show that it runs in the emulator even if the composite index definition is temporarily removed.
3. Restore the source-controlled index JSON and record its SHA.
4. Run Rules tests for tenant isolation and schema versions 1/2.
5. Simulate staging index readiness with a deterministic state file (CREATING → READY); gate app flag on READY. Clearly label this as simulation, not managed-index proof.
6. Exercise rollback by disabling the feature flag first and restoring the prior Rules file in the local test harness.

Production judgment and bridge

Configuration-as-code reduces drift only when deployment ordering and rollback are designed with client compatibility. Lesson 4 applies the same expand–migrate–contract discipline to document schema evolution and long-running backfills.

Knowledge check

1. Why can a query pass locally yet fail in production for an index?
2. What happens to console Rules when the CLI deploys the repository Rules?
3. Why deploy an index before releasing the dependent query?
4. Why is a feature flag part of database rollback?
5. Why is index rollback not simply “delete the new index”?

Authoritative references

• Firebase: Connect your app to the Cloud Firestore Emulator — demo projects, edition selection, Admin SDK environment variables, reset/import/export, Rules reports, and production differences.
• Firebase: Install, configure and integrate Local Emulator Suite — emulators:exec, import/export and CI workflow.
• Firebase: Test Cloud Firestore Security Rules — emulator rules testing and CI execution.
• Firebase: Build Security Rules unit tests — @firebase/rules-unit-testing, mocked auth, clearing state and disabled-rules fixture setup.
• Firebase: Manage and deploy Security Rules — source control, local testing and selective deployment.
• Firebase: Manage indexes in Cloud Firestore — source-controlled index definitions and CLI deployment.
• Firebase: Cloud Firestore index definition reference — composite, field override and vector index JSON shapes.
• Firebase CLI reference — configured multi-database rules/indexes and deployment selectors.