Set up workflows

Workflows define how tickets move through your process: the states, the transitions between them, automated actions, and WIP limits.

  1. 1 Understand the structure

    Workflows are defined in YAML. A workflow has a name, a list of states, and transitions between those states.

    # A complete workflow definition name: default states: - open - selected - in_progress - review - done - closed categories: open: todo selected: todo in_progress: in_progress review: in_progress done: done closed: done transitions: - from: open to: selected - from: selected to: in_progress actions: - type: require_fields fields: [assignee] - type: notify to: lead@example.com message: "Work started" wip_limit: 3 - from: in_progress to: review actions: - type: send_webhook webhook: ci - from: review to: done actions: - type: set_field field: resolved_at value: "{{now}}" - type: close_children

  2. 2 Define your states

    States are listed in order, and that order sets the columns on the board. New tickets start in the first state. Keep it simple: most teams need 4–6 states.

    A selected state gives your team a clear queue: pick what should happen next by moving tickets there, and people or agents take work from that column instead of the whole backlog.

  3. 3 Group states into categories

    Give each state a category: todo, in_progress, or done. Categories colour status badges, drive sprint completion and open or done counts, and start the cycle-time clock when work begins. A state without a category counts as todo.

  4. 4 Define transitions

    Each transition specifies a from state and a to state. Only defined transitions are allowed — this enforces your process.

  5. 5 Add actions to transitions

    Actions run automatically when a transition fires. You can chain multiple actions on a single transition.

    # Available action types require_fields # Block transition until fields are set notify # Email a notification to an address set_field # Set a field on the ticket create_ticket # Create a child ticket update_ticket # Same as set_field send_webhook # POST to a registered webhook close_children # Close all child tickets natural_language # Run an LLM prompt (uses your provider)

  6. 6 Set WIP limits

    Add wip_limit to any transition to control how many tickets can be in the target state at once. This helps prevent bottlenecks and keeps flow healthy.

  7. 7 Query via MCP

    List and inspect workflows programmatically through MCP tools.

    // List all workflows in a workspace list_workflows: { "workspace_id": "..." } // Get a workflow: states in order, allowed transitions, categories get_workflow: { "workspace_id": "...", "name": "default" }

Tips

  • Start simple — you can always add states and actions later.
  • The natural_language action uses your configured LLM provider to run AI-powered automations.
  • WIP limits are enforced at transition time. Existing tickets in a state are not affected retroactively.
  • Template variables like {{ticket.key}} and {{now}} are expanded in set_field values.

Next steps