Approval Gates & Resume Tokens

+15 Mana ✨
OpenClaw Lobster Approvals(DOCUMENTATION)OpenClaw Pipeline Management(DOCUMENTATION)

Introduction

Not every pipeline step should execute automatically. Approval gates let you pause a pipeline at critical points and wait for human confirmation before proceeding. When a pipeline reaches an approval gate, it halts and issues a resume token. The pipeline only continues when someone submits the token with an approve or reject decision. This pattern is essential for pipelines that involve production deployments, financial transactions, or any action that requires human oversight.

Key Concepts

  • Approval Gate: A special step type that halts pipeline execution until a human approves or rejects
  • Resume Token: A unique token issued when a pipeline pauses at an approval gate
  • approve true / approve false: The two possible responses to an approval gate that continue or abort the pipeline
  • Pipeline Suspension: The state where a pipeline is paused at an approval gate, waiting for a decision
  • Audit Trail: The approval decision, who made it, and when are recorded in the pipeline execution log

Real World Context

A release engineering team uses a Lobster pipeline for production deployments. After the build and staging verification steps, an approval gate pauses the pipeline. The tech lead receives a notification with the resume token, reviews the staging results, and approves the deployment. If something looks wrong, they reject it and the pipeline aborts cleanly without touching production.

Deep Dive

Defining an Approval Gate

Approval gates are defined as steps with type approve:

yaml
steps:
  - id: build-and-test
    type: shell
    config:
      command: "npm run build && npm test"

  - id: deploy-staging
    type: shell
    config:
      command: "kubectl apply -f k8s/staging/"
    dependsOn: build-and-test

  - id: approve-production
    type: approve
    config:
      message: "Staging deployment verified. Approve production deployment?"
      notifyChannel: "releases"
    dependsOn: deploy-staging

  - id: deploy-production
    type: shell
    config:
      command: "kubectl apply -f k8s/production/"
    dependsOn: approve-production

The pipeline builds and deploys to staging, then pauses at the approve-production gate. It sends a notification to the releases channel and waits. Only after approval does the production deployment execute.

Resume Tokens

When the pipeline reaches an approval gate, it generates a resume token:

json
{
  "pipelineId": "deploy-v2.5.0",
  "stepId": "approve-production",
  "resumeToken": "rt_a1b2c3d4e5f6",
  "status": "awaiting_approval",
  "message": "Staging deployment verified. Approve production deployment?",
  "createdAt": "2026-02-20T14:30:00Z"
}

The resume token rt_a1b2c3d4e5f6 is a one-time-use identifier that the approver uses to submit their decision.

Approving or Rejecting

To approve and continue the pipeline:

bash
openclaw lobster approve rt_a1b2c3d4e5f6 --decision true

This submits the approval. The pipeline resumes from the approval gate and continues to the production deployment step.

To reject and abort the pipeline:

bash
openclaw lobster approve rt_a1b2c3d4e5f6 --decision false

This aborts the pipeline. The production deployment step is never executed. The rejection is recorded in the audit log with a timestamp and the identity of the rejector.

Approval Timeout

Approval gates can have a timeout that auto-rejects if no decision is made:

yaml
- id: approve-production
    type: approve
    config:
      message: "Approve production deployment?"
      timeoutMinutes: 60
      onTimeout: reject

If no decision is submitted within 60 minutes, the pipeline is automatically rejected. This prevents pipelines from being stuck indefinitely in a suspended state.

Common Pitfalls

  • Losing resume tokens: If the resume token is not delivered to the right person, the pipeline stays suspended indefinitely. Always configure notifications.
  • Not setting timeouts on approval gates: Without a timeout, a forgotten approval gate can leave a pipeline suspended forever.
  • Approving without reviewing the context: The approval decision should be based on reviewing the pipeline's execution results up to that point, not just clicking approve.

Best Practices

  • Always set a timeout on approval gates to prevent pipelines from being stuck in limbo.
  • Send resume tokens to a team channel rather than a single person to avoid single-point-of-failure.
  • Include relevant context in the approval message so the approver has enough information to make a decision.

Summary

  • Approval gates pause pipelines at critical points to wait for human decisions
  • Resume tokens are one-time-use identifiers for submitting approve or reject decisions
  • approve true continues the pipeline; approve false aborts it cleanly
  • Timeouts can auto-reject gates that receive no decision within a configured window
  • All approval decisions are recorded in the pipeline audit log for traceability
✓ Completed