Guide

How to Add Approval Gates to an AI Agent Workflow

Name: Fleet
Author: Fleet

Full autonomy is not always appropriate. Some stages of a workflow — merging to main, deploying to production, spending above a certain budget — warrant a human check before proceeding. Approval gates let you insert a required human decision point into an otherwise automated chain.

Fleet implements approval gates as required fabric events. An agent or workflow stage pauses and waits for a specific event to appear before continuing. A human (or an authorized reviewer agent) publishes that event to unblock the next stage. This guide shows how to configure and use approval gates.

Before you start

Fleet watcher running with a multi-agent config
An understanding of which stages in your workflow require human oversight
Access to the Fleet CLI to publish manual fabric events when approving

1

Identify the stages that need gates

Map your workflow and mark the transitions that carry risk: merging a large refactor, shipping a breaking API change, running a database migration. These are your gate points. Everything else can flow automatically.

# Example workflow with gate points:
# ticket_ready -> [backend-developer] -> pr_created
# pr_created -> [tech-lead] -> pr_approved  <- gate 1: code quality
# pr_approved -> [release-manager] -> GATE: human confirm before merge
# human publishes pr_approved -> release-manager merges

2

Configure a subscription gate on the release stage

Have the release-manager subscribe to pr_approved, then add a subscription_gate so the match only fires when verifiable GitHub state is true — for example a passing-checks, mergeable PR carrying the approved label. The gate is checked by the watcher before the agent starts, so a half-baked approval event cannot trigger a merge on its own.

agents:
  - name: release-manager
    role: release-manager
    department: engineering
    subscribes_to: pr_approved
    subscription_gate:
      pr_checks_passing: true
      pr_mergeable: true
      label_present: approved

3

Approve a gate manually

When you are ready to unblock a waiting stage, publish the approval event using the Fleet fabric CLI. This is the human's explicit approval action. The watcher picks up the event, re-checks the subscription gate, and fires the waiting agent within 10 seconds.

# Publish the approval event to unblock release-manager:
fleet fabric publish --event pr_approved --sender system:operator \
  --summary "Approved PR #57 for merge" --payload '{"pr": 57}'

# Verify it appears in the event log:
fleet log --type decision

4

Gate on the merge check command

The fleet release check command is a code-based gate used by the release-manager skill. It verifies that a PR has a pr_approved fabric event and the approved label before allowing a merge. You can call this directly to test the gate logic.

fleet release check 57 --label-approved true --review-decision APPROVED
# Exit 0 = gate passes, merge can proceed
# Exit non-zero = gate fails, reason printed to stdout

5

Audit gate decisions in the log

Every approval event published to Fabric is recorded in the Fleet decision log with a timestamp and the publishing agent or user. This audit trail is available for review and debugging.

fleet log --type decision --since 30d | grep pr_approved

Common pitfalls

A gate that requires a manual fabric publish is only as good as the human's discipline to publish it correctly. If someone publishes the event without actually reviewing the PR, the gate provides no real protection.
Gates create a synchronous dependency in what is otherwise an asynchronous system. If the human who must approve a gate is unavailable, the entire downstream chain stalls. Have a backup approver defined.
Publishing the wrong event payload format (e.g., missing required fields the downstream agent checks for) can cause the gate to appear to unblock but the agent to fail on the next step. Test your event payloads in a non-production repository first.
The 15-minute dedup window on work-in-progress labels means a gate that is published and then revoked may not reliably re-block if re-published within that window.

When Fleet is the right tool

Approval gates are worth adding when the cost of an error at that stage is high enough to justify the added latency and human attention. For a personal project or low-stakes internal tool, full autonomy is probably fine. For production deployments, financial operations, or any action that is difficult to reverse, a gate is a reasonable safeguard.

Frequently asked questions

Can an agent act as the approver for a gate instead of a human?

Yes. A reviewer agent can publish the gate event if it meets the criteria. The `pr_approved` fabric event published by the tech-lead reviewer is exactly this pattern — it is an agent acting as the gate approver for the release-manager stage.

Is there a timeout on gates? What if the approver never approves?

Fleet does not have a built-in gate timeout. Waiting agents simply do not receive their trigger event and remain idle. You can implement a timeout externally by setting a cron schedule on a monitoring agent that alerts if a gate remains open longer than expected.

Run your first agent fleet

One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.

See how it works Install Fleet