Workflow proposals
See the workflow changes that agents or members propose. An owner or admin reviews them in the app and applies or rejects each one.
Any workspace member can propose a change to a type’s workflow — for example, adding a stage or
adjusting a stage gate. Every proposal is submitted from a task with ch workflow propose. An
agent working the task is one common source, but a person can submit one too. See Customising a
task’s workflow for how a proposal is created.
Owners and admins review proposals on the Workflow proposals page. To open it, go to
Settings → Workflows and select Workflow proposals in the page header. The button shows
how many proposals are new. You can also open the page at your workspace’s own address,
https://app.codeherder.com/<slug path>/-/workflow-proposals (see
Using the ch CLI for what a slug
path is).
Reading the queue
Filter the queue by status: New, Applied, or Rejected. A search box narrows the list by text.
Each proposal shows:
- Which type the proposed change targets, which task and stage it was submitted from, and its submission time.
- A diff — a compact summary of what would change if the proposal is applied: stages, fields and stage gates added, removed, or changed. It also names stages that were edited or reordered, changed transitions, a change to auto-staffing of unassigned work, a changed label, a changed workflow environment (tools or before-stage script), and a note when other workflow settings changed. A Privileged changes (review before approving) line appears when the proposal changes auto-staffing, or changes what a stage can write, how it is isolated, its image, its environment or its escalation capabilities. Read that line first. A Show JSON toggle opens the full current-vs-proposed schema side by side, for anyone who wants to check the raw change.
- A stale badge — if the workflow’s schema changed after the proposal was submitted, the proposal is marked stale. Apply is refused for a stale proposal (see below).
- Decision details, once a proposal is no longer New — when it was decided, who decided it, and, for a rejection, the reviewer’s own rejection reason, if they gave one.
Only a workspace owner or admin can open this page at all — anyone else sees a notice that only an owner or admin can review proposals, with a button to go back, and no queue, even though any member can submit a proposal in the first place.
Deciding a proposal
Two actions are available on a New proposal:
- Apply — accept the proposed change and update the workflow’s schema immediately. This needs the Custom workflows plan feature, the same one editing a workflow directly needs; submitting a proposal itself is open on every plan. Applying a proposal against a built-in workflow your workspace hasn’t customised yet gives your workspace its own copy of it, the same as editing that workflow directly would (see Customising workflows). CodeHerder refuses to apply a proposal that removes a stage a live task of that type currently sits in — move those tasks to a stage the proposal keeps (see Moving a task forward), then apply again. Applying also re-checks every hand-set override on a task of that type: an override that becomes redundant or stale is cleared, the same way editing the workflow directly would clear it — see Customising a task’s workflow for what “redundant” and “stale” mean.
- Reject — dismiss the proposal without changing the workflow. You can add a rejection reason (up to 2,000 characters); it’s shown on the proposal afterwards, for anyone who reads the queue later.
Apply refuses a stale proposal with a proposal_stale error, because it was written against an
older version of the workflow. To get the change, submit a new proposal against the current
workflow, then reject the stale one. Only Apply and Reject change a proposal’s status.
Reading and deciding proposals both require a workspace owner or admin. Other members can submit
a proposal with ch workflow propose, but they cannot read the queue or decide one.
Reading the queue from the CLI
ch workflow proposals list and ch workflow proposals show read the same queue as the web
page — see Customising a task’s workflow for the exact commands. show
prints the same decision details the web page does, once a proposal is decided: when, by whom,
and any rejection reason. Applying or Rejecting a proposal stays web-app only, and a person has to do it: an agent session
cannot decide a proposal, even with the admin role. There is no CLI verb for either.
Related guides
- Customising a task’s workflow — how a per-task override differs from
a workflow proposal, and the full
ch workflow propose/proposalscommand reference - Agent Experience surveys — a sampled, server-initiated question set instead of an open-ended proposal
- Workspace wiki — the alternative for durable, session-persistent knowledge
Last updated