Your First Workflow

In this guide, you'll create a complete workflow with states, transitions, conditions, and automations. By the end, you'll have a working development workflow that you can customize for your team.

What You'll Build

A development workflow with:

• 4 states: backlog → in_progress → review → done
• WIP limits to prevent overload
• Approval gates for code review
• Automated actions for notifications and cleanup

Prerequisites

• Completed the Quick Start
• A repository connected to your Kiket project
• Basic understanding of Core Concepts

---

Step 1: Create the Workflow File

In your repository, create .kiket/workflows/development.yaml:

workflow: development
version: 1

metadata:
  name: Development Workflow
  description: Standard workflow for feature development

states:
  - backlog
  - in_progress
  - review
  - done

This is the minimal workflow—just states, no transitions yet.

Push and verify:

git add .kiket/workflows/development.yaml
git commit -m "Add development workflow"
git push

Check the Kiket UI—you should see your workflow synced.

---

Step 2: Add Transitions

Transitions define how issues move between states. Update your file:

workflow: development
version: 1

metadata:
  name: Development Workflow
  description: Standard workflow for feature development

states:
  - backlog
  - in_progress
  - review
  - done

transitions:
  - from: backlog
    to: in_progress
  - from: in_progress
    to: review
  - from: review
    to: done
  - from: review
    to: in_progress  # Allow sending back for changes

Now issues can move through the workflow. Push and test by dragging a card on your board.

---

Step 3: Add State Configuration

Make states smarter with WIP limits and approval requirements:

workflow: development
version: 1

metadata:
  name: Development Workflow
  description: Standard workflow for feature development

states:
  - backlog:
      description: "Work not yet started"

  - in_progress:
      description: "Actively being worked on"
      wip_limit: 5
      auto_assign: true

  - review:
      description: "Awaiting code review"
      wip_limit: 3
      require_approval: 1

  - done:
      description: "Completed and deployed"

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

What this does:

• wip_limit: 5 — Warns when more than 5 items are in progress
• auto_assign: true — Assigns the user who moves the card
• require_approval: 1 — Needs at least 1 approval before moving to done

---

Step 4: Add Conditions

Control when transitions are allowed:

transitions:
  - from: backlog
    to: in_progress
    when:
      - field: assignee
        operator: present

  - from: in_progress
    to: review
    when:
      - field: description
        operator: present
      - field: labels
        operator: includes
        value: "ready-for-review"

  - from: review
    to: done
    when: all_approvals_received

  - from: review
    to: in_progress
    # No conditions—always allowed

Conditions explained:

• field: assignee, operator: present — Issue must have an assignee
• field: labels, operator: includes — Issue must have a specific label
• when: all_approvals_received — Built-in check for approval states

---

Step 5: Add Actions

Automate tasks when transitions occur:

workflow: development
version: 1

metadata:
  name: Development Workflow
  description: Standard workflow for feature development

states:
  - backlog:
      description: "Work not yet started"

  - in_progress:
      description: "Actively being worked on"
      wip_limit: 5
      auto_assign: true
      on_enter:
        - run: notify_assignee

  - review:
      description: "Awaiting code review"
      wip_limit: 3
      require_approval: 1
      on_enter:
        - run: notify_reviewers
        - run: add_review_label

  - done:
      description: "Completed and deployed"
      on_enter:
        - run: close_issue
        - run: notify_completion

transitions:
  - from: backlog
    to: in_progress
    when:
      - field: assignee
        operator: present

  - from: in_progress
    to: review
    when:
      - field: description
        operator: present

  - from: review
    to: done
    when: all_approvals_received
    on_success:
      - run: celebrate

  - from: review
    to: in_progress
    on_success:
      - run: notify_changes_requested

actions:
  notify_assignee:
    kind: notify
    recipients:
      - "{{ issue.assignee }}"
    message: "Issue {{ issue.key }} has been assigned to you"

  notify_reviewers:
    kind: notify
    recipients:
      - role: reviewer
    message: "{{ issue.key }} is ready for review"

  add_review_label:
    kind: system
    command: issues.add_labels
    params:
      labels: ["in-review"]

  close_issue:
    kind: system
    command: issues.close

  notify_completion:
    kind: notify
    recipients:
      - "{{ issue.reporter }}"
    message: "{{ issue.key }} has been completed!"

  celebrate:
    kind: notify
    recipients:
      - channel: "#team"
    message: "🎉 {{ issue.key }} shipped by {{ issue.assignee }}!"

  notify_changes_requested:
    kind: notify
    recipients:
      - "{{ issue.assignee }}"
    message: "Changes requested on {{ issue.key }}"

---

Step 6: Create a Matching Board

Create .kiket/boards/development.yaml:

board: development-board
workflow: development

metadata:
  name: Development Board
  description: Kanban board for the development workflow

columns:
  - name: Backlog
    states: [backlog]
    color: gray

  - name: In Progress
    states: [in_progress]
    wip_limit: 5
    color: blue

  - name: Review
    states: [review]
    wip_limit: 3
    color: yellow

  - name: Done
    states: [done]
    collapsed: true
    color: green

Push both files:

git add .kiket/
git commit -m "Add development workflow with board"
git push

---

Complete Workflow File

Here's the full workflow for reference:

workflow: development
version: 1

metadata:
  name: Development Workflow
  description: Standard workflow for feature development
  author: Your Team

states:
  - backlog:
      description: "Work not yet started"

  - in_progress:
      description: "Actively being worked on"
      wip_limit: 5
      auto_assign: true
      on_enter:
        - run: notify_assignee

  - review:
      description: "Awaiting code review"
      wip_limit: 3
      require_approval: 1
      on_enter:
        - run: notify_reviewers
        - run: add_review_label

  - done:
      description: "Completed and deployed"
      on_enter:
        - run: close_issue
        - run: notify_completion

transitions:
  - from: backlog
    to: in_progress
    when:
      - field: assignee
        operator: present

  - from: in_progress
    to: review
    when:
      - field: description
        operator: present

  - from: review
    to: done
    when: all_approvals_received
    on_success:
      - run: celebrate

  - from: review
    to: in_progress
    on_success:
      - run: notify_changes_requested

actions:
  notify_assignee:
    kind: notify
    recipients:
      - "{{ issue.assignee }}"
    message: "Issue {{ issue.key }} has been assigned to you"

  notify_reviewers:
    kind: notify
    recipients:
      - role: reviewer
    message: "{{ issue.key }} is ready for review"

  add_review_label:
    kind: system
    command: issues.add_labels
    params:
      labels: ["in-review"]

  close_issue:
    kind: system
    command: issues.close

  notify_completion:
    kind: notify
    recipients:
      - "{{ issue.reporter }}"
    message: "{{ issue.key }} has been completed!"

  celebrate:
    kind: notify
    recipients:
      - channel: "#team"
    message: "🎉 {{ issue.key }} shipped by {{ issue.assignee }}!"

  notify_changes_requested:
    kind: notify
    recipients:
      - "{{ issue.assignee }}"
    message: "Changes requested on {{ issue.key }}"

---

Test Your Workflow

1. Create an issue in your project
2. Try moving it without an assignee (should be blocked)
3. Assign yourself and move to In Progress
4. Add a description and move to Review
5. Approve the issue and watch it move to Done
6. Check notifications — you should receive the automated messages

---

What's Next?

• Advanced Workflows

  Checklists, approval routing, and workflow orchestration

  Workflow reference

• Add Integrations

  Connect Slack, GitHub, or build custom extensions

  Extensions

• Add Analytics

  Track cycle time, throughput, and team metrics

  Analytics