> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Environments: Promote and Roll Back Safely

> Use Scout workflow environments to promote changes from development to production, maintain separate configurations, and roll back to any revision safely.

Shipping a workflow change directly to production is risky — a misconfigured block or a subtle prompt change can silently degrade output quality before you notice. Scout's environment model gives you a structured path from development to live traffic, where each stage points to a specific revision of your workflow and you control when and what gets promoted.

## What Are Environments?

Scout provides three environments for every workflow. Each environment is independently mapped to a workflow revision — changing an environment's revision does not alter the workflow itself or affect other environments.

<CardGroup cols={3}>
  <Card title="Development" icon="code">
    Where you build and iterate. No real user traffic hits this environment. Use it freely for experiments, structural changes, and active debugging in the Console.
  </Card>

  <Card title="Staging" icon="flask">
    Your pre-production gate. Test with realistic inputs — including edge cases and known failure payloads — before anything reaches live users.
  </Card>

  <Card title="Production" icon="rocket">
    Live traffic. Only promote here once staging has confirmed the revision behaves correctly under realistic load and inputs.
  </Card>
</CardGroup>

<Note>
  Each environment points to a revision, not a branch. You promote a specific revision to an environment — you don't "deploy a branch." This makes rollbacks instant and deterministic.
</Note>

## How to Promote a Workflow Revision

<Steps>
  <Step title="Build and test in Development">
    Make your changes in Studio and test them thoroughly using the Console. Verify correct behavior with both happy-path and edge-case payloads before moving forward.
  </Step>

  <Step title="Name the revision">
    Open **History** in the workflow sidebar. Give the revision a descriptive name — for example, `add-urgency-classification` or `fix-null-customer-lookup`. Add a short note describing what changed.
  </Step>

  <Step title="Promote to Staging">
    In History, select the revision and click **Promote to Staging**. Scout updates the staging environment to run this revision immediately.
  </Step>

  <Step title="Validate against Staging">
    Run your full validation suite against the staging environment. Use the API with `environment=staging` to test programmatically, or use the Console with production-representative payloads.
  </Step>

  <Step title="Promote to Production">
    Once staging passes, open History and click **Promote to Production**. Monitor the Logs tab for the next few minutes to confirm the first production runs succeed.
  </Step>
</Steps>

## Targeting Environments via API

When you call a workflow via the API or SDK, always pass an explicit `environment` parameter. This ensures you're testing the right revision at each stage.

```bash theme={null}
# Run against staging before promoting to production
curl -X POST "https://api.scoutos.com/v2/workflows/{workflow_id}/execute?environment=staging" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "ticket_id": "TKT-TEST-001",
      "subject": "Staging smoke test",
      "body": "Validate that the new urgency classifier returns the correct tier.",
      "customer_email": "staging-test@example.com"
    }
  }'
```

Switch `environment=staging` to `environment=production` once you're confident in the revision. Run the same payload against both environments to compare outputs before committing.

## Separate Configuration Per Environment

You can configure different values for each environment — API keys, feature flags, rate limits, and integration endpoints. This lets development workflows use sandbox credentials and staging workflows use pre-production accounts, while production always uses live credentials.

Store environment-specific values as **Environment Variables** in the Scout Settings panel, then reference them in your blocks:

```yaml theme={null}
block: http
id: create_crm_contact
url: "{{ env.CRM_API_BASE_URL }}/contacts"
headers:
  Authorization: "Bearer {{ env.CRM_API_KEY }}"
```

Set `CRM_API_BASE_URL` and `CRM_API_KEY` to different values per environment. Your workflow definition stays identical across all three environments — only the variable values change.

## Reviewing Changes Before Promoting

Before promoting a revision to production, review what actually changed using the revision diff in History.

* **Blocks view** — shows high-level structural changes: blocks added or removed, connections modified. Use this for a quick sanity check.
* **Code view** — shows detailed JSON-level changes in every block's configuration. Use this when a subtle prompt tweak or config change might have unintended side effects.

<Warning>
  If the diff shows more changes than you expected, investigate before promoting. A revision that looks like a small prompt edit may have accumulated other changes since the last deploy.
</Warning>

## Rolling Back to a Previous Revision

If a production deploy degrades output quality or increases failure rates, roll back immediately and fix forward in development.

<Steps>
  <Step title="Identify the last known good revision">
    Open **History** and look for the revision that was running before the problematic deploy. Check **Logs** to confirm it was producing correct output.
  </Step>

  <Step title="Promote it back to Production">
    Select the previous revision in History and click **Promote to Production**. The rollback takes effect immediately — no downtime, no redeploy.
  </Step>

  <Step title="Confirm recovery in Logs">
    Switch to the **Logs** tab and verify that the next few runs succeed. Check that error rates and durations return to baseline.
  </Step>

  <Step title="Fix forward in Development">
    Do not patch the production revision directly. Make your fix in development, test it in staging, and follow the normal promotion path.
  </Step>
</Steps>

<Tip>
  Name your revisions meaningfully before every staging promotion. When you need to roll back quickly under pressure, `add-urgency-classifier` is far easier to identify than `revision-47`.
</Tip>

## Best Practices

* **Never promote directly from development to production.** Always validate in staging first, even for small changes. A one-word prompt edit can shift LLM output in unexpected ways.
* **Run automated checks against staging.** Write a test script that calls your workflow via API with a fixed set of payloads and asserts on the outputs. Run it every time you promote to staging.
* **Keep development noisy.** Add verbose logging blocks and debug outputs in development. Strip them before promoting to staging.
* **Pair Logs with History.** When a failure appears in Logs, note the timestamp and cross-reference it with History to identify which revision introduced the problem.

## Next Steps

<CardGroup cols={2}>
  <Card title="Logs" icon="magnifying-glass" href="/workflows/logs">
    Verify deployment health after every promote and debug failures fast.
  </Card>

  <Card title="Running Workflows" icon="play" href="/workflows/running-workflows">
    Execute workflows with explicit environment targeting via API or SDK.
  </Card>

  <Card title="Creating Workflows" icon="hammer" href="/workflows/creating-workflows">
    Structure your workflow to be testable and easy to promote confidently.
  </Card>

  <Card title="Blocks" icon="cubes" href="/workflows/blocks">
    Understand how blocks and configuration work before building for multiple environments.
  </Card>
</CardGroup>