Document ticketing integration patterns and Linear/Jira troubleshooting

[samgutentag]

Summary

• New page flaky-tests/management/ticketing/integration-patterns.mdx covering the cross-cutting concerns for Linear and Jira ticketing: button vs webhook vs custom-handler tradeoffs, link-back asymmetry, webhook idempotency, CODEOWNERS routing, the beta auto-analyses 100/month rate limit, and Jira-specific 401 / cross-project-link troubleshooting.
• Small cross-link callouts added to the Linear and Jira integration pages so users hitting these gaps find the new page from where they're already reading.
• docs.json updated to include the new page in the Ticketing group sidebar.

Why

Sourced from customer feedback mining (cluster ticketing-integration-linear-jira, verdict partial, 10 pairs across 6 customers, first-class IA candidate). Linear and Jira ticketing integrations are a top driver of integration questions; recurring gaps include the link-back asymmetry between button-created and webhook-created tickets, missing webhook idempotency, Jira credentials troubleshooting, and the under-surfaced 100/month beta auto-analysis rate limit.

Items flagged for review

• 100/month rate limit — wording is based on the cluster example (trunk-healthie thread, customer raised to 500 on request). Confirm against current eng config; if the default has changed, the number needs a tweak.
• Page placement (Option A vs B) — went with Option B: one shared "Integration patterns and troubleshooting" page cross-linked from both Linear and Jira. Avoids duplicating link-back / idempotency / CODEOWNERS content twice. If preference is to inline these into both Linear and Jira pages instead, easy to refactor.
• Linear automation pattern (Pattern B) — described conceptually but no example snippet included; the cluster examples didn't have a worked example either. If we want one, would need eng input on a recommended Linear automation config.
• test_case.id shape claim — said the webhook payload's test_case.id is "the stable identifier Trunk expects" for link-ticket. Confirm against link-ticket-to-test-case API spec; if the API expects a different field shape, the Info callout needs adjusting.
• CODEOWNERS routing in manual ticket creation — claimed the button flow "does not consult CODEOWNERS either". Confirm against current behavior — verified field defaults exist but no claim about CODEOWNERS in the existing Linear/Jira pages, so this is inferred from absence.
• Jira API token / project access language — pulled directly from the trunk-chainlink thread example. Confirm external_ticket_id is the correct request field name (vs ticket_id, external_id, etc).

Customer signal

• Cluster: ticketing-integration-linear-jira (verdict: partial, 10 pairs / 6 customers, first-class IA candidate)
• Channels: trunk-metabase, trunk-heidihealth, trunk-healthie, trunk-faire, trunk-chainlink
• Source threads (full list in findings/clusters/ticketing-integration-linear-jira.json):
  • webhook ticket link-back
  • webhook idempotency + CODEOWNERS routing
  • link-back patterns
  • Jira required custom fields
  • Jira 401 invalid credentials
  • Jira cross-project link permissions
  • auto-quarantine + auto-ticket misfire
  • 100/month rate limit

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
trunk	🟢 Ready	View Preview	May 20, 2026, 11:25 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.