Skip to main content

Issue Workflows

Issue Workflows are the state-machine specs that drive the Issues screen. An issue is bound to exactly one workflow at create time; the workflow's states + transitions decide what the issue can do next.

Find the admin at Admin → Issue Workflows. Route: /admin/issue-workflows. API: /issue-workflows.

What a workflow contains​

A workflow has:

  • A name and description
  • A list of states: each with an id, label, optional terminal flag, and optional color for the Issues screen's state chip
  • A list of transitions: each with a from state, to state, an optional label, and an optional requiresComment flag

Example:

{
  "name": "Default issue flow",
  "states": [
    { "id": "open",      "label": "Open" },
    { "id": "ack",       "label": "Acknowledged" },
    { "id": "wip",       "label": "In progress" },
    { "id": "blocked",   "label": "Blocked" },
    { "id": "resolved",  "label": "Resolved", "terminal": true }
  ],
  "transitions": [
    { "from": "open", "to": "ack" },
    { "from": "ack",  "to": "wip" },
    { "from": "wip",  "to": "blocked" },
    { "from": "blocked", "to": "wip" },
    { "from": "wip",  "to": "resolved", "requiresComment": true }
  ]
}

The admin​

Master/detail:

  • Left — workflow list
  • Right — split into a states panel (top) and a transitions panel (bottom). Add / remove / rename states; pick from / to state on each transition; toggle the requiresComment / terminal flags

A diagram pane on the right is queued — today the editor is list-based.

How a workflow is consumed​

The Issues screen at /events/:eventId/issues reads the workflow attached to each issue. When the user clicks the state chip, the screen offers only the legal transitions (those whose from is the current state). If the chosen transition has requiresComment: true, a dialog prompts for a reason before the PATCH is sent.

The two convenience endpoints (/issues/:id/acknowledge and /issues/:id/resolve) do the right thing if the active workflow has matching states.

What you can do today​

  • Author multiple workflows per account
  • Bind any issue to a workflow at create time
  • Use the seeded Default issue flow as a template

What's coming​

  • Diagram pane — visual graph editor instead of the list editor
  • State entry / exit hooks — fire a webhook when an issue enters a state
  • Workflow templating — clone an existing workflow as a starting point
  • Per-team default workflow — auto-attach without explicit selection