Operator - Workflow Promotions

Overview

Workflow promotion records an operator release decision for a single workflow target. Its state reports the assigned version per environment and promotion history; a promotion records the candidate version, source, destination, note, and actor.

Targets are stable; versions move

The workflow target identifies the deployable system, while a workflow version is the candidate artifact. Promotion changes the environment's selected version and appends history rather than editing old releases.

Gate evidence is part of the decision

to_environment is validated as development, staging, or production. from_environment is only normalized and recorded as descriptive history, defaulting to the target's current environment; the endpoint does not validate a transition or enforce an eval result.

How it works

1. Read current state

   Open the target in /app/evals/targets, copy its canonical ID, and read promotions. Confirm the source environment currently points to the intended version and inspect prior notes and actors.

2. Promote and reconcile

   Submit the exact workflow_version_id, optional from_environment, required to_environment, and a concise note through the CSRF-protected session. Re-read state and verify environment_versions plus the appended promotion_history.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const id = window.prompt("Workflow target UUID");
if (!id) throw new Error("A UUID is required");
const path = "/api/v1/operator/workflow_targets/ID/promotions".replace("ID", encodeURIComponent(id));
const response = await fetch(path, {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

Promotion is rejected with 400

Check that the nested promotion body names workflow_version_id and to_environment, with optional from_environment, and that the candidate version belongs to this target.

Promotion is forbidden

Only owners and admins may promote; members and auditors are rejected even though they can read the state. Archived workspaces also reject every mutation.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.