Skip to content

Create Your First Workflow

Workflows describe how issues move from idea to completion. They live as YAML files inside .kiket/workflows/ in your Git repository. This guide walks through building and publishing a simple development workflow using the hosted platform.

1. Add the Workflow File

Create .kiket/workflows/development.yaml in the repository that is attached to your project:

workflow: development
version: 1

states:
  - backlog:
      wip_limit: 999
  - in_progress:
      wip_limit: 4
      auto_assign: true
  - review:
      require_approval: 1
  - done:
      on_enter:
        - action: close_issue

transitions:
  - from: backlog
    to: in_progress
    when: assigned

  - from: in_progress
    to: review
    when: pull_request.opened

  - from: review
    to: done
    when: approval.received

actions:
  close_issue:
    kind: system
    command: issues.close

Commit and push the file to your main branch (or open a pull request—workflows are just code, so review them like any other change).

2. Sync the Repository

  1. Open Organization → Repositories.
  2. Locate the repository you just updated and click Sync. The platform validates the YAML, caches the workflow definition, and logs the result.
  3. Fix any validation errors surfaced in the sync log, then rerun the sync.

3. Map the Workflow to a Board

  1. Edit your board configuration under .kiket/boards/. Make sure each column references the workflow state keys:
name: Development Board
workflow: development
columns:
  - key: backlog
    name: Backlog
  - key: in_progress
    name: In Progress
  - key: review
    name: Review
  - key: done
    name: Done
  1. Sync the repository again so the board definition is refreshed.
  2. Visit Projects → Your Project → Boards. The Kanban board now reflects the states defined in the workflow file. Moving an issue between columns invokes the workflow executor, which enforces guards and side-effects before updating the ticket.

4. Iterate Safely

  • Treat workflow changes like code: use pull requests, run automated YAML linting, and record the reasoning in commit messages.
  • Add automated tests in your CI to lint workflow files (see the KiketScript Reference for validation helpers).
  • Use feature flags inside YAML (when: feature.enabled('beta_actions')) to phase in new automation.

With this workflow in place you can extend transitions, actions, and guard logic using the full KiketScript DSL. Continue to the Boards guide for advanced layouts and swim lane configuration.