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.

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.

Endpoint

POST /v1/workflows/{workflow_id}/promotions

Request:

{
  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:

{
  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

# 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:

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

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.

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.