Skip to content
Pipebase

Promote to prod

Pre-requisites

Section titled “Pre-requisites”

The promotion model

Section titled “The promotion model”

Each environment has a promotesTo field pointing at the next one downstream. Pipebase forms a tree (or a DAG with branches):

dev ──→ test ──→ staging ──→ prod

When you promote a flow, Pipebase deploys the same YAML to the downstream environment, substituting {{paramName}} placeholders from each runtime’s cutover matrix — so environment-specific URLs, credentials, and topic names swap in automatically.

Step 1 — Add a parameter to your flow

Section titled “Step 1 — Add a parameter to your flow”

Open your flow in the editor. In the YAML, replace a hard-coded value with a {{token}} placeholder. For example:

- route:
    from:
      uri: platform-http:/order-events
    steps:
      - to: "https://{{host}}/api/orders"

Save the flow. The {{host}} token now needs a value before any runtime will accept a deploy.

Step 2 — Open the Cutover drawer and declare the parameter

Section titled “Step 2 — Open the Cutover drawer and declare the parameter”

Click the Parameters button in the editor toolbar to open the Cutover parameters drawer. Click + Add parameter, set:

  • Key: host
  • Type: string
  • Description: something like Order service API host

The parameter row now appears in the matrix with empty cells for every runtime.

Step 3 — Fill the dev value

Section titled “Step 3 — Fill the dev value”

In the matrix row for host, click the dev cell and enter your dev value, e.g. orders-dev.internal. Press Enter or click away to save. The cell turns green.

Step 4 — Deploy to dev

Section titled “Step 4 — Deploy to dev”

Click Deploy in the toolbar and choose dev. Pipebase substitutes {{host}} → orders-dev.internal from the cutover matrix and PUTs the YAML to the dev runtime. The dev row in the promotion matrix shows In sync.

Step 5 — Open the full Cutover page

Section titled “Step 5 — Open the full Cutover page”

Navigate to /edit/<flowId>/cutover (or click the Cutover link in the flow detail pane). This full-page view adds:

  • The history sidebar — every value change logged with actor and timestamp
  • The Promote modal — copy values up the chain with a diff preview

Step 6 — Promote dev → staging

Section titled “Step 6 — Promote dev → staging”

Click Promote on the staging column header. The modal shows a diff of what will change. You can override individual cells before confirming — for example, change host from orders-dev.internal to orders-stag.internal before the promote lands.

Confirm. Pipebase copies (or replaces) the cutover values into the staging column. Keys that already existed in staging are preserved unless you explicitly overrode them.

Step 7 — Deploy to staging

Section titled “Step 7 — Deploy to staging”

Back in the editor (or from the Cutover page), click Deploy → staging. Pipebase substitutes {{host}} → orders-stag.internal and the staging row turns In sync.

Step 8 — Promote to prod (optional)

Section titled “Step 8 — Promote to prod (optional)”

Repeat the promote step for prod. Fill any prod-specific values (different credentials, partition counts, etc.) in the diff modal before confirming. Then deploy to prod.

Rollback

Section titled “Rollback”

To roll a single flow back: click the runtime’s row in the promotion matrix and hit Undeploy, then redeploy from the upstream environment’s source.

To roll the whole stack back to a previous Pipebase version:

Terminal window
# Pin to a previous version in .env
sed -i 's/^PIPEBASE_VERSION=.*/PIPEBASE_VERSION=v0.4.0/' .env
docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Flow data in the volumes persists across version changes.

What now?

Section titled “What now?”