Environment Promotion

Promote a project's configuration from one environment to another — export a declarative bundle from dev, import it into prod, in one call.

Stand up a fresh project (say, prod) from another project's (say, dev) configuration in a single operation instead of replaying dozens of sequential create calls. Export a declarative bundle from the source project, then import it into the target. Your coding agent can run both halves over MCP.

Bundles carry configuration only — no secrets, no per-user data, no end-user rows. They're safe to commit to version control, diff in a pull request, or hand to an agent.

What's in a bundle

A bundle is a single JSON document with a version and one section per reusable configuration type:

Section	What it carries
`remote_configs`	Flag / value definitions you authored (system rows are excluded).
`collections`	Collection schema only — column definitions + indexes, not the rows.
`content_libraries`	Libraries and their authored items (no per-user deliveries).
`currencies`	Currency definitions (not user balances).
`achievements`	Achievement definitions (not user grants).
`streaks`	Streak definitions (not user streaks).
`challenges`	Challenge definitions.
`leaderboards`	Leaderboard definitions (not entries).
`xp_rules`	XP rules (not user XP or the XP ledger).
`monetization`	Declared subscription config — entitlements, products, offerings, packages, paywalls (nested, not a flat array). Importing writes Amba's declared definitions only — it never touches RevenueCat, and the next monetization plan shows the imported config as pending `create` ops until you apply or adopt.
`integrations`	Each active integration's non-secret config — push settings like the bundle id, team/key ids, and environment. Credential material (`.p8` keys, service-account JSON, API keys) is always stripped and marked `credentials: "stripped"`. See Integrations and push credentials.

This also closes the "gamification has no seed mechanism" gap — currencies, achievements, streaks, challenges, leaderboards, and XP rules all export as definitions and re-create on import.

Promote dev → prod

# 1. Export the source (dev) project's config to a bundle.
curl 'https://api.amba.dev/v1/admin/projects/$DEV_PROJECT_ID/promotion/export' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  | jq '.data' > bundle.json
 
# 2. Import it into the target (prod) project.
curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROD_PROJECT_ID/promotion/import' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d "{ \"bundle\": $(cat bundle.json), \"mode\": \"skip_existing\" }"

Import modes

Mode	Behaviour
`skip_existing`	Default. An entity whose key already exists in the target is left untouched.
`merge`	An existing entity is updated in place from the bundle; new entities are created.

Import returns a per-section summary so you can see exactly what was created, updated, or skipped:

{
  "data": {
    "mode": "skip_existing",
    "summary": {
      "currencies": { "created": 2, "updated": 0, "skipped": 1 },
      "achievements": { "created": 8, "updated": 0, "skipped": 0 },
      "collections": { "created": 3, "updated": 0, "skipped": 0 }
    }
  }
}

Promotion is idempotent in skip_existing mode. Re-running the same import is safe — anything already present is skipped. Use merge when you want the target to converge on the source's definitions.

Integrations and push credentials

Your push setup (APNs / FCM) promotes too — without its secrets ever entering the bundle. The exported integrations section carries only non-secret config, so the import needs credentials one of two ways:

Same developer? Copy them server-side. When the source and target projects belong to the same developer, pass include_integration_credentials: true on import. The stored credentials are copied directly between the two projects' credential stores — entirely server-side, never through your terminal or the bundle file — and the integrations activate immediately. Dev → prod push promotion becomes part of the same single import call:

curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROD_PROJECT_ID/promotion/import' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d "{ \"bundle\": $(cat bundle.json), \"mode\": \"skip_existing\", \"include_integration_credentials\": true }"

Otherwise: pending_credentials. Without the flag (or across developers, where the flag is refused with a 403), each integration is created inactive in a pending_credentials state. The import response tells you per provider exactly which call uploads the credentials — configure the integration with the full config including the credential (or use the amba_integrations_configure MCP tool), and it activates.

In merge mode, an integration that already works on the target keeps its credentials and active state — re-imports refresh non-secret fields only.

{
  "data": {
    "summary": { "integrations": { "created": 2, "updated": 0, "skipped": 0 } },
    "integrations": [
      { "provider": "apns", "status": "activated" },
      { "provider": "fcm", "status": "activated" }
    ]
  }
}

Reference

Admin API — export + import
MCP tools — amba_project_export, amba_project_import