Tutorial: Release to Environments

A published version is active, but not yet visible to applications running in environments it hasn't been released to. This tutorial walks through the promotion sequence and the rollback path.

Time: ~10 minutes
Prereqs: Publish version — you have a published v1.2 released to development.

Where we are

welcome_email
├── v1.0   sha=47be37f69681   envs=[]                  not active
├── v1.1   sha=8a201cdef0a4   envs=[]                  not active
└── v1.2   sha=ff42aabb1100   envs=[development]       ACTIVE

development SDK calls return v1.2. testing and production calls return 409.

1. Release to testing

Once dev has validated v1.2, promote it to testing.

Open the version

From the Versions tab, click v1.2.

Manage releases

Click Manage releases in the top-right (or the env-chips row, depending on UI).

Add testing

Check testing. Click Save.

The version's environments list is now [development, testing]. SDK calls with environment="testing" now return v1.2.

welcome_email
└── v1.2   envs=[development, testing]   ACTIVE

2. Verify from the SDK

Before promoting to production, sanity-check from a test environment:

pm = PromptManager(
    api_key=TEST_KEY,
    project_id=PROJECT_ID,
    environment="testing",
)

prompt = pm.get_active_prompt_version("welcome_email")
print(prompt.sha)               # ff42aabb1100  ← matches v1.2
print(prompt.environments)      # ["development", "testing"]

If you get a 409 here instead, double-check the env spelling. The on-prem backend is strict: "test" ≠ "testing".

3. Release to production

When testing is green, promote to production.

Manage releases again

Same flow.

Add production

Check production. Click Save. Some teams require a second approval at this step (configured in project settings). If so, your colleague will get a notification.

Final state:

welcome_email
└── v1.2   envs=[development, testing, production]   ACTIVE

Customers now see v1.2.

4. Rolling back

A customer reports the new email reads too formally. You want to roll back to v1.1.

Find the previous version

Versions tab → find v1.1.

Confirm it's still released

v1.1's environments list should include production (it was previously the active version released there). If it doesn't, you'll need to re-release it.

Set v1.1 as active

Click v1.1's menu → Set as active. Confirm.

INFO

Best practice: when you remove a version from production, don't strip its env tags immediately. Keep the env tags for at least a week so rollback is one click.

Production traffic now serves v1.1 again. No code deploy, no waiting on CI.

5. Multi-version state

A prompt can have multiple versions with overlapping release tags. The active pointer decides which one is served.

welcome_email
├── v1.1   envs=[development, testing, production]   ACTIVE  ← served
├── v1.2   envs=[development, testing, production]
└── v1.3   envs=[development]

In this state:

• production and testing SDK calls return v1.1 (the active version).
• development SDK calls also return v1.1 (because that's the active version, and v1.1 is released to development).
• v1.3 is invisible to all SDK calls — it's released, but not active.

6. Custom environments

You're not limited to development / testing / production. Release a version to any string you want:

• beta — for beta users
• eu_region — for EU-only traffic
• experiment_b — for A/B testing

Whatever string is on the version, the SDK matches that exact string against its environment= argument. Coordinate between your release operations and your application config.

Promotion checklist

Save → review → approve in dev

Standard PR-style review with your team.

Publish + release to development

Set the new version as active for dev users. Verify locally.

Release to testing

Once dev is satisfied. QA verifies in your staging environment.

Smoke-test from the SDK

Run a quick script in your CI / staging that fetches the prompt under environment="testing" and asserts the SHA matches the expected one.

Release to production

Optionally gated on a second approver. Watch your error rates and customer feedback for ~30 minutes.

Set active (if not already)

If you released without simultaneously activating, do it now.

Monitor

Application logs should now show sha=<new sha> on fetches. Verify.