Workflow Approvals

Kiket’s workflow engine supports built-in approval gates so high-impact transitions can require a human sign-off or an AI assistant’s recommendation before they proceed. This guide explains how to configure approvals in your workflow definitions, how reviewers interact with the approvals UI, and how AI assistants can automatically collect the supporting context.

When to Require Approvals

Approvals are typically used when a transition carries additional risk or needs a domain expert’s blessing, for example:

• Moving a release to production.
• Escalating a security incident to closure.
• Approving a legal/finance request.
• Assigning AI-suggested code changes to a team without review.

Approvals can be triggered based on roles (e.g., manager), specific assignees, or workflow state metadata. Multiple approvals can be collected on the same transition; the transition only completes when all required approvals are resolved.

Configuring Approvals in Workflows

Approvals are defined inside the workflow YAML in your definition repo. Add the require_approval field to the transition configuration:

# definitions/workflows/release.yaml
workflow:
  name: Release Train
  states:
    - key: review
      label: In Review
    - key: production
      label: Production
  transitions:
    - from: review
      to: production
      require_approval:
        - assignment:
            type: role
            identifier: sre_lead
          metadata:
            message: "SRE sign-off required before releasing to production."

require_approval accepts a list of approval entries. Each entry can target a user (type: user, using the user ID), a role (type: role), or even another workflow/state (type: workflow) if you want to fan a request out to a different approval workflow.

When a transition with require_approval is invoked, Kiket will create one or more WorkflowApproval records and display the pending status immediately. The transition is blocked until all approvals are completed.

Conditional Approvals with Guards

You can wrap require_approval inside a KiketScript when: guard to require approvals only in specific scenarios (e.g., production releases created by AI, or issues above a severity threshold). Example:

    - from: review
      to: production
      when:
        any:
          - issue.priority == "critical"
          - issue.metadata.ai_generated == true
      require_approval:
        - assignment:
            type: role
            identifier: security_lead

Reviewer Experience

Whenever a transition is blocked, the approvers see a notification and the issue gains a Workflow Approvals panel. From there reviewers can:

• View pending requests with timestamps, requested-by, and any metadata the workflow author provided.
• Approve directly (one-click for user/role assignments).
• Deny with an optional reason (captured in the timeline and metadata).
• See resolution history (approved/denied/cancelled statuses).

Approvals also surface in the command palette (Cmd/Ctrl+K → Workflow Approvals) so reviewers can jump to outstanding requests quickly.

Working with Paginated Approvals

Large approval queues are paginated. When new approvals arrive and you are not on the first page, the approvals tab shows a badge so you can jump to page 1 without losing your filter state.

AI-Assisted Approvals

Kiket can route approval requests to AI assistants before involving a human. There are two primary modes:

1. Pre-approval context gathering – Use AI agents (Developer Aide or custom agents) to gather logs, test summaries, or risk analyses and attach them to the approval metadata. See the AI agents guide for manifest configuration.
2. AI recommendations – Have an AI agent post a recommendation or auto-approve lower-risk transitions. You can enforce a human-in-loop confirmation by having the agent respond with status: pending while attaching a recommendation payload.

Example extension guard that defers to AI first:

// extensions/my_guard/app.rb
return {
  "status": "pending",
  "message": "AI review pending",
  "metadata": {
    "ai_result": ai_summary,
    "recommendation": "Proceed"
  }
}

The guard response creates a WorkflowApproval entry with the AI recommendation attached. Human reviewers can then accept or override the AI suggestion within the approvals panel.

Automation-Driven Escalations

Workflow automation recipes can now raise approvals automatically based on live risk signals. The predictive escalation beta ships with three core recipes:

• SLA Breach Escalation – watches priority issues that are within eight hours of their due date and raises an approval for the operations_manager role.
• Silent Issue Follow-up – pings the current assignee when work-in-progress has been idle for 48 hours and can auto-reassign to a team lead.
• High-Risk Issue Alert – uses the Vertex AI advisor service to score work and request an engineering manager approval when the AI risk score exceeds configurable thresholds.

Recipes are authored in .kiket/workflows/<workflow>/automation_recipes/*.yaml (see the automation builder in project settings). When a recipe returns pending, the runtime creates a WorkflowApproval and records the associated AutomationRun so reviewers can see the trigger, AI context, and diff snapshot in the issue timeline. Telemetry for these runs is logged as automation.recipe usage events, keeping quota and monetization guardrails intact.

Learn more about the automation runtime and YAML schema in the Automation Recipes guide.

Multi-Level Approval Chains

For complex approval scenarios requiring multiple sign-offs, Kiket supports multi-level approval chains. Approvals progress sequentially through levels, with each level requiring completion before advancing to the next.

workflow:
  transitions:
    - from: draft
      to: production
      approval_chain:
        chain:
          - level: 1
            name: Team Lead Review
            assignments:
              - type: role
                identifier: team_lead
            required: any  # any team lead can approve
            timeout: 24h
          - level: 2
            name: Manager Approval
            assignments:
              - type: role
                identifier: manager
            required: all  # all managers must approve
            timeout: 48h
          - level: 3
            name: Director Sign-off
            assignments:
              - type: user
                identifier: ${issue.custom_fields.director_email}
            required: all

Required Types

Each level supports different approval requirements:

• all - All assigned approvers must approve (unanimous)
• any - At least one approver must approve
• threshold - A specific number of approvals (use with required_count)

Parallel Approval Groups

For levels requiring multiple independent approvals simultaneously:

- level: 1
  name: Stakeholder Approval
  parallel:
    - group: engineering
      assignments:
        - type: role
          identifier: tech_lead
      required: any
    - group: product
      assignments:
        - type: role
          identifier: product_manager
      required: all
  logic: AND  # Both groups must complete (use OR for either)

Conditional Levels

Skip approval levels based on issue attributes:

- level: 2
  name: Security Review
  assignments:
    - type: role
      identifier: security_team
  conditions:
    - field: priority
      operator: "="
      value: critical
    - field: labels
      operator: contains
      value: security

Escalation Policies

Configure automatic escalation when approvals timeout:

approval_chain:
  chain:
    - level: 1
      assignments:
        - type: role
          identifier: team_lead
      timeout: 24h
  escalation:
    - after: 4h
      action: reminder
      channels: [in_app, email]
    - after: 8h
      action: escalate
      to:
        - type: role
          identifier: manager
      channels: [in_app, email, slack]
    - after: 24h
      action: notify_executive
      to:
        - type: role
          identifier: director
    - after: 48h
      action: auto_approve
      reason: "Auto-approved due to timeout - no response within SLA"

Escalation Actions

Action	Description
reminder	Send reminder to current approvers
escalate	Add additional approvers without canceling existing
reassign	Cancel current approval and assign to new approvers
auto_approve	Automatically approve the request
auto_deny	Automatically deny the request
notify_executive	Alert executives without changing approvers

Approval Delegation

Team members can delegate their approval authority during out-of-office periods:

1. In Settings → Delegation: Configure delegation with:
2. Delegate user (who will approve on your behalf)
3. Valid period (start and end dates)

4. Scope (optional - limit to specific approval chains)

5. API Configuration:

   ApprovalDelegation.create!(
     organization: org,
     delegator: current_user,
     delegate: backup_user,
     valid_from: Date.today,
     valid_until: 1.week.from_now,
     scope: ["budget_approval", "release_approval"], # Empty = all chains
     reason: "Vacation"
   )
   

When a delegation is active, new approval requests are automatically routed to the delegate, and the original approver is recorded for audit purposes.

Integrating External Systems

Approvals can also fan out to external services (e.g., ServiceNow, Slack) by subscribing to workflow.before_transition events. Use the Extensions::WorkflowExtensionDispatcher to create a pending response and process the approval externally. Once an external system signs off, resolve the request through the workflow Approvals API (coming soon).

Best Practices

• Start simple: Require approval for one high-risk transition and iterate.
• Provide context: Use metadata messages and AI summaries so reviewers understand why approval is needed.
• Use roles over user IDs: Role-based assignments survive personnel changes.
• Monitor history: Use the automation log and timeline to audit approval timing and outcomes.

For a full configuration example, download the release-management workflow in the definition repo, which ships with approval states, SRE sign-off, and AI recommendations.