Skip to main content

Approval gates

What you will build​

You will add an approval gate to the Implement spec workflow so the run pauses after the Software Developer. You then review the changed files and decide: accept, deny, or accept with comments.

Prerequisites
Tested version
This tutorial was tested on OpenJCockpit develop (draft, not yet verified on a clean machine). OpenJCockpit is in active development, so details may differ on other versions.
About the model
The demo runs on a local Ollama model (qwen3.6:27b). Output varies from run to run and is slower than hosted models, so your results will not match the screenshots exactly. Long waits in the video are sped up and labelled.
Video coming soon: Approval gates: a human decision inside the run. The written steps below cover the same content.
Approval gates: a human decision inside the run

Steps​

1. Open Workflow Design​

Find Implement spec and open it. The default workflows have no gate configured. You add one where you want a human decision.

2. Anchor a gate to the Software Developer​

Add an approval gate and anchor it to the Software Developer agent. A gate always belongs to an agent in the workflow, and the run pauses right after that agent finishes.

Checkpoint
The workflow shows a gate after the Software Developer.

3. Start the workflow on spec 002​

Start Implement spec on 002-validate-book-input. The architect and the developer run, then the run stops with status AWAITING_APPROVAL.

4. Review the approval context​

The dashboard shows the gate context, including the files the developer changed. Open the branch and compare the diff with the spec's acceptance criteria.

Checkpoint

The run is parked and the approval view lists the changed files. The QA Engineer has not run yet.

5. Decide​

DecisionWhat happens
AcceptThe run continues with the QA Engineer
DenyThe run ends
Accept with commentsThe developer runs again with your feedback and its previous output, then the gate opens again

Try accept with comments once, for example: "Also add a test for an author longer than 100 characters." Then accept the second version.

Checkpoint

The run finishes, and the decision, including your comment, is recorded in the approval audit trail.

What just happened​

The gate parked the run in the database, so it survives a restart of the service. Your decision was recorded durably, and exactly one decision wins even if two people click at once.

Know the limits before you rely on this:

  • Feedback loops cost money and time. Each comment re-runs the agent. The default maximum is 3 loops per gate (APPROVAL_GATE_MAX_FEEDBACK_ITERATIONS), and it is the only cost control.
  • Any signed-in user can approve. There is no role restriction on who may decide at a gate.
  • A job times out while waiting. A run on a project stops after WORKFLOW_AGENT_TIMEOUT (3600 s locally), even while a gate is open.
  • Runs that were executing during a restart are lost. Only runs parked at a gate resume.

See the product approval gates runbook and known limitations.

Troubleshooting​

  • The dashboard shows "run state lost": the service restarted while an agent was executing. Start the workflow again.
  • Accepting returns 409: someone else already decided.

Next steps​

Policy as code controls what agents may do before a human is even involved.