Skip to content

Workflows

Workflows are the heart of Kiket. They define how issues move through your process—from creation to completion—with states, transitions, conditions, and automations.

What is a Workflow?

A workflow is a state machine defined in YAML. It describes:

  • States — The stages an issue can be in (backlog, in_progress, review, done)
  • Transitions — Rules for moving between states
  • Conditions — Guards that control when transitions are allowed
  • Actions — Automations triggered by state changes
workflow: development
version: 1

states:
  - backlog
  - in_progress
  - review
  - done

transitions:
  - from: backlog
    to: in_progress
  - from: in_progress
    to: review
  - from: review
    to: done

Why Workflows as Code?

Version Control

Every workflow change is tracked in Git:

  • Review changes in pull requests before they go live
  • Roll back instantly if something goes wrong
  • Audit history of who changed what and when

Reproducibility

The same workflow file produces the same behavior:

  • Consistent environments — dev, staging, production all work the same
  • Shareable templates — Copy workflows between projects or organizations
  • Portable — Your workflows aren't locked in a vendor database

Automation-Friendly

YAML workflows integrate with your development process:

  • CI/CD validation — Lint workflows before merging
  • Automated testing — Verify workflow logic in tests
  • Infrastructure as Code — Treat workflows like any other configuration

Workflow Structure

graph TB
    subgraph "Workflow File"
        A[metadata]
        B[states]
        C[transitions]
        D[actions]
        E[hooks]
    end

    B --> F[State Config]
    F --> G[WIP Limits]
    F --> H[Approvals]
    F --> I[Checklists]

    C --> J[Conditions]
    C --> K[On Success/Failure]

    D --> L[Notifications]
    D --> M[System Commands]
    D --> N[Webhooks]
    D --> O[AI Actions]

    style A fill:#7C3AED,stroke:#fff,color:#fff
    style B fill:#7C3AED,stroke:#fff,color:#fff
    style C fill:#7C3AED,stroke:#fff,color:#fff
    style D fill:#7C3AED,stroke:#fff,color:#fff
    style E fill:#7C3AED,stroke:#fff,color:#fff

Quick Examples

Simple Kanban

workflow: kanban
states:
  - todo
  - doing
  - done

transitions:
  - from: todo
    to: doing
  - from: doing
    to: done

With Approval Gates

workflow: change-request
states:
  - draft
  - pending_approval:
      require_approval: 2
      approvers: [manager, security-team]
  - approved
  - rejected

transitions:
  - from: draft
    to: pending_approval
  - from: pending_approval
    to: approved
    when: all_approvals_received
  - from: pending_approval
    to: rejected
    when: any_rejection_received

With Automations

workflow: support
states:
  - new:
      on_enter:
        - run: notify_support_team
        - run: start_sla_timer
  - triaged:
      on_enter:
        - run: assign_by_skill
  - resolved:
      on_enter:
        - run: send_satisfaction_survey
        - run: stop_sla_timer

actions:
  notify_support_team:
    kind: notify
    recipients:
      - channel: "#support"
    message: "New ticket: {{ issue.title }}"

  assign_by_skill:
    kind: ai
    agent: skill-matcher
    params:
      strategy: least_loaded

In This Section

  • Workflow Syntax

    Complete YAML syntax for workflows

    Workflow syntax

  • Language Reference

    Full KiketScript reference

    Reference

  • Examples

    Common workflow patterns and recipes

    Examples

  • Workflow Approvals

    Approval gates and routing

    Approvals

  • Boards

    Visualize workflows as boards

    Boards

Visual Workflow Editor

Coming Soon

A drag-and-drop visual workflow editor is in development. Design workflows visually and export to YAML, or import existing YAML for visual editing.

For now, workflows are defined entirely in YAML files.

Getting Started

  1. Your First Workflow — Step-by-step tutorial
  2. Workflow Syntax — Syntax and structure
  3. Examples — Common recipes

Need help? Join the Community Discord or check the Troubleshooting Guide.