Set up workflows

Workflows define how tickets move through your process. Each project can have its own workflow with custom states, transitions, automated actions, and WIP limits.

  1. 1 Understand the structure

    Workflows are defined as YAML configurations per project. A workflow has a name, a list of states, and transitions between those states.

    # A complete workflow definition name: default-task states: - todo - in_progress - in_review - done transitions: - from: todo to: in_progress actions: - type: require_fields fields: [assignee] - type: notify message: "{{ticket.id}} started" wip_limit: 3 - from: in_progress to: in_review actions: - type: send_webhook url: https://ci.example.com/trigger - from: in_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 — this order determines how columns appear on the board. Keep it simple: most teams need 3–5 states.

  3. 3 Define transitions

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

  4. 4 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 # Send a notification to the team set_field # Set a ticket field to a value create_ticket # Create a related ticket update_ticket # Update fields on another ticket send_webhook # POST to an external URL close_children # Close all child tickets natural_language # Run an LLM prompt (uses your provider)

  5. 5 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.

  6. 6 Query via MCP

    List and inspect workflows programmatically through MCP tools.

    // List all workflows in a workspace list_workflows: { "workspace_id": "..." } // Get a specific workflow definition get_workflow: { "workspace_id": "...", "name": "default-task" }

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.id}}} and {{now}} are expanded at runtime.

Next steps