4.4 Gates, policies and retirement

Included from Basic tier

After this you can: put an approval gate on a workflow the policy way, answer the gates a run parks on, and retire a definition without deleting it.

Before you start — tick each one:

• Lesson 4.2 — Store, browse, run (opschain learn 4.2)

In the GUI: the Reviews & approvals inbox holds every workflow run a policy gates, with a red bubble counting what waits on you; Policies & owners is where the policies live.

Who may let a workflow run is not a question the workflow's author answers. In OpsChain the author writes the orchestration; approval policies — owned by governance, imposed from outside the definition — decide which runs are held for sign-off, by whom, and with what quorum. This lesson puts a gate on your workflow that way, shows how the gates a run parks on are answered, and closes with the two ways a definition leaves service: archive, and the administrator's destroy.

1. Policies impose the gate

An approval policy is one row of the change matrix: a node-path glob it covers, optionally the actions it covers, and the approvers it resolves — named users, directory groups, or a kind such as the impacted assets' owners. A policy matching the project holds every covered workflow run in pending_approval before it starts, and the approvals inbox shows it to the people whose names resolved:

opschain approval-policies create --name "prod sign-off" \
  --path-pattern '/projects/acme/environments/prod/**' \
  --approver-group release_managers --quorum 2

Nothing in the YAML changes. The requester states why with runs create workflow … --rationale "…", approvers read that rationale, the chain and the recommendation in the approval context, and decide with opschain approvals approve|reject or in the inbox. The policy surface needs the packs:change-governance entitlement; the whole funnel — matrix, quorum, validity, break-glass, the approval context an approver reads — is module M10, starting at lesson 10.1 (opschain learn governance-approvals).

2. Answer the gates a run parks on

Whatever holds a run, the verbs that release it are the ones lesson 3.2 taught, and the run id picks the right step family automatically — they work the same whether the gate lives in a change or a workflow. A wait: step inside the definition parks the run at waiting:

opschain runs show <run-id> -o json       # find the waiting step's id
opschain runs continue <run-id> --step <step-id> --message "window open"

continued step 01a14402-…-example of run <run-id> — now success

approve and reject answer an approval-gated step the same way, and a run held by a policy in pending_approval is released through the approvals inbox — never through the step verbs, because there is no step: the hold sits in front of the run.

3. Retire without deleting

opschain workflows archive acme/env_start

archived workflow acme/env_start

An archived workflow is hidden from new runs while its history — versions, past runs, audit events — stays intact; a run already in flight finishes on its own terms. Archive is the everyday "stop using this"; it is always reversible:

opschain workflows unarchive acme/env_start

unarchived workflow acme/env_start

4. Destroy, deliberately

When an archived workflow is truly obsolete, an administrator can remove it permanently — versions and, with the flag, runs and their logs — while audit events always survive:

opschain admin workflows destroy acme/env_start --with-runs

destroyed workflow acme/env_start — removed:
  runs             7
  versions         2
  …
events were not touched; the audit trail persists

The workflow must already be archived (destroying is a two-step act), the command prints the destroy manifest and prompts unless --yes, and the server refuses by name while a run is still active or while a trigger or scheduled activity still references the workflow. Export first if the definition should outlive the catalog (opschain docs cli/admin-workflows-destroy).

A closing note on the legacy key. Older definitions may still carry requires_approval_from: on a wait step — an in-YAML approval gate for named users or directory groups. It keeps working and stays enforced, but it is the author's ask, not governance's: opschain approval-policies convert-step-gates creates the equivalent policies from those keys without touching the YAML, and new definitions should not use it.

Check yourself

• Archive the workflow while one of its runs is still in flight: what happens to that run, and what does runs create workflow answer for the archived code? Then: where does a policy's hold sit relative to the run's first step, and which command releases it?

What you learned

• Approval gates come from approval policies — path glob, actions, approvers, quorum — imposed outside the definition; the whole funnel is module M10.
• A run held by a policy waits in pending_approval before it starts and is released through the approvals inbox; a wait: step inside the run is answered with runs continue|approve|reject --step.
• workflows archive hides a definition from new runs and keeps every version, run and event; unarchive reverses it.
• admin workflows destroy removes an archived definition for good, refusing while anything still references it; events survive.

Next: lesson 4.5 — Operating the catalog (opschain learn 4.5), or back to your track (opschain learn).