> ## Documentation Index
> Fetch the complete documentation index at: https://uiform-codex-generated-frontend-snippets.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotion

> Promote a workflow from test to production as a reviewable draft

Promotion copies a workflow's deployable configuration from one
environment to another. It never copies runtime data. The output is a
**production draft** — you still review it and publish explicitly before
live traffic switches over.

```text theme={null}
test published version -> production draft -> production publish
```

## What is copied, and what is not

| Copied                                                           | Not copied                            |
| ---------------------------------------------------------------- | ------------------------------------- |
| Workflow graph and block configuration                           | Runs, steps, artifacts                |
| Published workflow snapshot metadata                             | Files and stored documents            |
| Workflow tests (if `include_tests: true`)                        | Jobs                                  |
| Environment variable / secret **names** referenced               | Raw secret values                     |
| Webhook **definitions** (if `include_webhook_definitions: true`) | Webhook delivery attempts and retries |
|                                                                  | HIL review records                    |
|                                                                  | Usage counters and issue analytics    |

Secret references are copied by name. The production environment must
already hold values for those names — see
[Webhooks and secrets](/environments/webhooks-and-secrets).

## Endpoint

```http theme={null}
POST /v1/workflows/{workflow_id}/promotions
```

Request:

```ts theme={null}
{
  source_environment: "test",
  target_environment: "production",
  source_version_id: "ver_...",
  target_workflow_id?: "wf_...",          // omit to create a paired workflow
  target_name?: "Invoice Workflow",
  include_tests: true,
  include_webhook_definitions: true,
  idempotency_key: "promote-2026-05-19-abc"
}
```

Response:

```ts theme={null}
{
  promotion_id: "prm_...",
  target_workflow_id: "wf_...",
  target_draft_version: "draft_...",
  missing_secrets: ["SALESFORCE_API_KEY"],
  warnings: ["webhook endpoint points at localhost.run"]
}
```

Promotion is idempotent per workspace and idempotency key. Retrying after
a network timeout returns the same promotion result rather than creating a
duplicate production draft.

## `missing_secrets`

If the source workflow references secrets that do not exist in
production, those names are returned in `missing_secrets`. The
production draft is still created so you can inspect the diff, but
publishing or running it will fail until the missing secrets are
populated.

Add the missing values in the dashboard under the production environment,
then re-list secrets to confirm and publish the draft.

## URL warnings

Webhook definitions are scanned before they are copied into production.
The response includes `warnings` if the production target would inherit
endpoints that look like development URLs:

* `localhost`, `127.0.0.1`, or `0.0.0.0`
* `*.ngrok.io`, `*.ngrok-free.app`, `*.ngrok.app`
* Known staging hostnames (any URL containing `staging`, `dev`, `test`,
  or matching common review-app domains)

These are warnings, not errors. Update the endpoint to a real production
URL inside the production draft before publishing.

## Examples

### CLI

```bash theme={null}
# Promote the currently published test version to production.
retab workflows promote wf_test_abc \
  --target-environment production \
  --source-version-id ver_... \
  --include-tests \
  --include-webhook-definitions \
  --idempotency-key promote-2026-05-19-abc
```

Promotion is a release-class command. In CI, pass `--confirm`:

```bash theme={null}
RETAB_API_KEY=rt_live_... retab workflows promote wf_test_abc \
  --target-environment production \
  --source-version-id ver_... \
  --include-tests \
  --include-webhook-definitions \
  --idempotency-key promote-2026-05-19-abc \
  --confirm
```

### curl

```bash theme={null}
curl -X POST https://api.retab.com/v1/workflows/wf_test_abc/promotions \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_environment": "test",
    "target_environment": "production",
    "source_version_id": "ver_...",
    "include_tests": true,
    "include_webhook_definitions": true,
    "idempotency_key": "promote-2026-05-19-abc"
  }'
```

For the full request/response shapes, see the
[workflow promotion API reference](/api-reference/workflows/publish).

## Workflow pairing

Promotion uses a stable logical id (`workflow_family_id`) to associate the
test workflow with its production counterpart. The two workflows have
distinct resource IDs (so cross-environment access still returns `404`),
but the dashboard pairs them for diffs and follow-up promotions.

## Recommended flow

1. Build and iterate on the workflow in the **test** environment.
2. Run workflow tests against the latest test draft.
3. Publish the test draft to get a stable `source_version_id`.
4. `POST /v1/workflows/{workflow_id}/promotions` (or use the dashboard
   *Promote* action).
5. Review the production draft: secrets, webhook URLs, tests.
6. Publish the production draft when you are ready for live traffic.