Skip to content

fix(linear): store state IDs in status mappings#1117

Merged
zbigniewsobiecki merged 1 commit intodevfrom
fix/linear-status-uuid-mapping
Apr 15, 2026
Merged

fix(linear): store state IDs in status mappings#1117
zbigniewsobiecki merged 1 commit intodevfrom
fix/linear-status-uuid-mapping

Conversation

@zbigniewsobiecki
Copy link
Copy Markdown
Member

Summary

The Linear status-mapping step in the PM wizard was saving workflow-state names (e.g. 'Planning') as the dropdown's value, but Linear webhooks deliver state UUIDs in data.stateId. The trigger handler at src/triggers/linear/status-changed.ts:60 does strict equality — so every status transition since Linear support landed has been silently no-oping.

JIRA gets away with names because JIRA's webhook delivers names; Linear does not.

Root cause

web/src/components/projects/pm-wizard-linear-steps.tsx:178 rendered each option with { label: s.name, value: s.name } instead of { label: s.name, value: s.id }.

Fix

  • Use s.id as the option value; keep s.name as the label so the dropdown still reads naturally.
  • Inline comment explaining the contract so it doesn't regress.
  • Regression test asserts every Linear state's id appears as an <option value="…"> and no state name does.

Reproducing the bug (before fix)

Move any Linear issue between configured states. Router logs Linear state transition does not map to any agent with newStateId: <UUID> and configuredStatuses: { planning: 'Planning', ... }. CLI: cascade webhooklogs list --source linear shows the request hit but no agent fired.

Operator action required after this lands

Existing projects have status mappings stored as names — those will not match incoming UUIDs. Re-run the Status Mappings wizard step for each Linear-backed project: each dropdown will appear empty (because the saved name no longer matches a value), pick from the dropdown, save. Going forward the wizard saves UUIDs.

Out of scope (separate follow-ups)

  • Caddy ingress for /linear/* and /sentry/* was missing from both prod and dev hostnames in mongrel-intelligence/infra — fixed there separately (committed directly to main; already live). Without it the webhook never reached the router at all (404 from dashboard).
  • Production router image at commit fb14e237 predates Linear support entirely; needs a redeploy from `main` to pick up the /linear/webhook route. Caddy now routes correctly but the prod router itself returns 404 until rebuilt.
  • Labels semanticslinearLabels wizard input is free-text; the create-issue adapter (src/pm/linear/adapter.ts:88-94) treats values as label IDs while triggers (src/triggers/linear/label-added.ts:46) tolerate either name or ID. Not breaking the user's reported flow; deserves a focused PR.

Test plan

  • npm run lint, npm run typecheck, npm test all clean locally
  • New regression test: tests/unit/web/linear-field-mapping-step.test.ts > uses state IDs (not names) as dropdown option values
  • After merge to `dev`: re-run Status Mappings wizard step on the dev project, then move a Linear issue to Planning and confirm router log shows Linear issue transitioned to agent-triggering state and a planning agent run starts

🤖 Generated with Claude Code

Linear webhooks deliver workflow-state UUIDs in data.stateId, but the
PM wizard's status-mapping dropdown was saving display names as the
option value. The status-changed trigger does strict-equality matching
on the saved value, so every Linear status transition since the
integration landed has been silently no-oping.

JIRA gets away with names because JIRA webhooks deliver names; Linear
does not.

Changed the option value to s.id (s.name remains as the label so the
dropdown still reads naturally). Added a regression test asserting
every state ID appears as an option value and no state name does, plus
a WHY comment to anchor the contract for future maintainers.

Operator action required after deploy: re-run the Status Mappings
wizard step on existing Linear-backed projects. Each saved name will
no longer match a value, so dropdowns will appear empty — re-pick from
the dropdown and save. New mappings persist as UUIDs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@zbigniewsobiecki zbigniewsobiecki merged commit 77c5617 into dev Apr 15, 2026
9 checks passed
@zbigniewsobiecki zbigniewsobiecki deleted the fix/linear-status-uuid-mapping branch April 15, 2026 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant