Promote Configuration

When you'd use it

Koolbase recommends separate projects for dev and prod so their data never mixes. The trade-off is that your project's structure doesn't automatically carry across. Promote closes that gap: build and validate everything in your dev project, then promote the configuration to prod in one step. It copies structure, not content.

What it copies

Clean the source project first

A snapshot is only as clean as the project you take it from. Dev projects accumulate things you never meant to keep — a collection you made while testing, a function you deployed once to try something, a bucket named test-uploads. Apply cannot tell those apart from the structure you care about. It creates all of it, in production, silently.

So before you promote: delete what you do not want in production, then pull a fresh snapshot and look at what you actually captured.

# after cleaning up the dev project
koolbase snapshot pull --project <dev-project-id> --output koolbase.json

# see what you are about to promote
python3 -c "import json; s=json.load(open('koolbase.json')); print({k: len(s.get(k) or []) for k in ['collections','unique_constraints','functions','buckets','crons','triggers','secret_names']})"

If those counts are not what you expect, stop and fix the dev project — not the file. The snapshot is meant to be a faithful description of a project, and hand-editing it means your committed definition no longer matches anything real.

Always preview first

Every promote runs as a diff first. You see exactly what will be added and changed in the target before anything is written. The dashboard previews automatically; the CLI previews with --dry-run.

From the dashboard

1. Open the source project and go to Infrastructure → Promote.
2. Pick the target project from the dropdown.
3. Click Preview to see the diff — collections to add or change, and per-environment changes.
4. Review the summary, then click Promote to apply.

Collections already in sync are collapsed so only the actual changes stand out. Environments that have no matching slug in the target are shown as skipped.

From the CLI

Pull your project's definition from the source, then apply it to the target. By default the CLI reads and writes koolbase.json — a plain-JSON file you commit to your repo and treat as the source of truth for your backend.

# 1. Pull the source project's definition (writes ./koolbase.json)
koolbase snapshot pull --project SOURCE_PROJECT_ID

# 2. Commit it — your backend definition now lives in version control
git add koolbase.json && git commit -m "Update backend definition"

# 3. Preview what would change in the target (writes nothing)
koolbase snapshot apply --project TARGET_PROJECT_ID --dry-run

# 4. Apply for real
koolbase snapshot apply --project TARGET_PROJECT_ID

Pass -o <file> / -f <file> to use a different filename, or -o - to print to stdout instead of writing a file.

Backend as code (CI/CD)

Once koolbase.json lives in your repo, your backend definition is reviewable, versioned, and reproducible. Wire it into CI so a pull request previews the diff and merging to main reconciles your production project — the flow you'd expect from infrastructure-as-code.

CI has no interactive login, so the CLI authenticates from environment variables instead — set KOOLBASE_API_KEY and KOOLBASE_BASE_URL and it skips the login file entirely.

Authority tracks how destructive the operation is. Exporting and applying additively need a write key; pruning needs admin. A read key cannot export — a snapshot carries your function source, so it is not read-tier data.

name: Koolbase backend

on:
  pull_request:
    paths: ["koolbase.json"]
  push:
    branches: [main]
    paths: ["koolbase.json"]

env:
  KOOLBASE_BASE_URL: https://api.koolbase.com
  KOOLBASE_API_KEY: ${{ secrets.KOOLBASE_API_KEY }}

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - run: go install github.com/kennedyowusu/koolbase-cli@latest
      - run: koolbase-cli snapshot apply --project ${{ vars.KOOLBASE_PROD_PROJECT_ID }} --dry-run

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - run: go install github.com/kennedyowusu/koolbase-cli@latest
      - run: koolbase-cli snapshot apply --project ${{ vars.KOOLBASE_PROD_PROJECT_ID }}

What gets copied, in detail

Collections

Matched by name. For each collection, Promote copies the schema and full access-rule definition:

Unique constraints

Each collection's unique constraints travel with the snapshot: the fields, and whether matching ignores case. Apply creates any the target lacks, after the collections they belong to exist. A constraint the target already has on the same fields is left as it is; one with a different case setting is reported as a conflict and not changed.

If the target's existing records already break a constraint, apply creates nothing and reports a conflict with the number of duplicate groups: remove the duplicates, then apply again. Koolbase never merges them for you. A dry run cannot check for duplicates, so they only show up on a real apply. Constraints the snapshot does not mention are never removed.

Storage buckets

A bucket's configuration travels: visibility, access mode, size and file-size limits, allowed MIME types, and whether versioning is on. The files inside do not — a cloned bucket arrives empty and ready.

Only versioning can be changed after creation. If a bucket of the same name already exists in the target with any other setting different, apply reports a conflict and leaves it alone rather than deleting and recreating it, which would take its contents with it.

Functions

Source, runtime, timeout, auth requirement, and enabled state travel together. The target redeploys from the snapshot — no local checkout, no build step — and the deployment goes through exactly the checks a normal deploy does: import validation, dependency resolution, the package denylist, and a vulnerability scan.

For dart-standard functions the snapshot carries the pubspec you wrote, not the merged one, and the runtime string pins the exact profile version — so a clone resolves to the same dependency set as the original, today or in two years.

Triggers and crons

Triggers are what make a cloned function actually fire, so they travel as their own section — a project with every function deployed and nothing bound to events is not a working clone. Crons carry their environment slug and are matched the same way per-environment config is.

Per-environment config

Environments are matched by slug. For each matched environment, Promote copies:

Secrets: names travel, values don't

A snapshot lists which secrets a project expects, never what they contain. Values are encrypted at rest and are not returned by any read path, so there is nothing for an export to copy even in principle.

Apply reports the ones the target is missing, so finishing a clone is a checklist rather than a hunt:

Secrets: 2 pending
  · FCM_SERVICE_ACCOUNT — awaiting a value
  · MESSAGING_SEND_KEY — awaiting a value

Secrets needing values (2) — the clone is ready except these:
  koolbase secrets set FCM_SERVICE_ACCOUNT --project <target>
  koolbase secrets set MESSAGING_SEND_KEY --project <target>

Conflicts

Some differences cannot be reconciled without destroying something. Apply reports these, leaves them exactly as they are, and carries on with the rest — it never guesses on your behalf.

Buckets: 1 conflict
  ! profiles — bucket exists with different immutable settings and was left
               unchanged; converging would require deleting it and its objects
      access_mode (snapshot="owner" destination="project")

How merging behaves

Pruning

By default apply never deletes — removing a collection from your file does nothing on its own. To make the file fully canonical, so it can express deletion too, pass --prune. Pruning is deliberately conservative: it can only delete what apply itself created, and never silently destroys data.

# Preview what prune would remove (writes nothing)
koolbase snapshot apply --project TARGET_PROJECT_ID --prune --dry-run

# Delete manifest-owned collections absent from the file
koolbase snapshot apply --project TARGET_PROJECT_ID --prune

# Also delete collections that still hold records
koolbase snapshot apply --project TARGET_PROJECT_ID --prune --force

API reference