Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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

CopiedNot copied
Workflow graph and block configurationRuns, steps, artifacts
Published workflow snapshot metadataFiles and stored documents
Workflow tests (if include_tests: true)Jobs
Environment variable / secret names referencedRaw 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 by (organization_id, 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 "Api-Key: $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.
  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.