From e3c4810e5e2d673c50b9abd519e2dae4081d9aae Mon Sep 17 00:00:00 2001 From: Tyler Beebe Date: Fri, 31 Jul 2026 11:49:42 -0400 Subject: [PATCH 1/4] docs: automatic ticketing for flaky tests New Automatic ticketing page covering the ticket automation settings (auto-create on flaky/broken, auto-close on healthy, reopen behavior and window, close/reopen target statuses) and lifecycle behavior. Cross-linked from the ticketing index and both provider pages; webhook ticket-creation pages gain an FYI recommending the built-in automation for Linear/Jira. --- docs.json | 1 + .../ticketing/automatic-ticketing.mdx | 71 +++++++++++++++++++ flaky-tests/management/ticketing/index.mdx | 4 ++ .../management/ticketing/jira-integration.mdx | 4 ++ .../ticketing/linear-integration.mdx | 4 ++ .../webhooks/github-issues-integration.mdx | 4 ++ flaky-tests/webhooks/index.mdx | 4 ++ flaky-tests/webhooks/jira-integration.mdx | 4 +- flaky-tests/webhooks/linear-integration.mdx | 4 +- 9 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 flaky-tests/management/ticketing/automatic-ticketing.mdx diff --git a/docs.json b/docs.json index 59229c01..f8d561e8 100644 --- a/docs.json +++ b/docs.json @@ -273,6 +273,7 @@ "group": "Ticketing", "root": "flaky-tests/management/ticketing/index", "pages": [ + "flaky-tests/management/ticketing/automatic-ticketing", "flaky-tests/management/ticketing/jira-integration", "flaky-tests/management/ticketing/linear-integration", "flaky-tests/management/ticketing/other-ticketing-platforms" diff --git a/flaky-tests/management/ticketing/automatic-ticketing.mdx b/flaky-tests/management/ticketing/automatic-ticketing.mdx new file mode 100644 index 00000000..0bfc2dc5 --- /dev/null +++ b/flaky-tests/management/ticketing/automatic-ticketing.mdx @@ -0,0 +1,71 @@ +--- +title: "Automatic ticketing" +description: "Automatically create, reopen, and close tickets as your tests change status — no webhooks or custom automation required" +og:title: "Automatic ticket creation for flaky tests in Trunk" +--- + +Trunk can manage the full lifecycle of a test's ticket for you. When a test's status changes, Trunk automatically: + +* **Creates a ticket** when a test becomes flaky or broken +* **Reopens the existing ticket** (or creates a fresh one) when a fixed test regresses +* **Closes the ticket** when the test returns to healthy + +Automatic ticketing works with the built-in [Linear](./linear-integration) and [Jira](./jira-integration) integrations and produces the same rich tickets as manual creation — full [ticket content](./index#ticket-content) (failure history, impact, common failure reasons, code owners), your configured [field defaults](./jira-integration#custom-fields), and complete dashboard support: linked tickets appear on the test case details page, and every automated action is recorded in the test's [Events tab](/flaky-tests/dashboard#test-case-details). + +## Enabling ticket automation + +Navigate to **Settings** → **Repositories** → **[your repository]** → **Ticketing**. Once your Linear or Jira integration is fully configured, the **Ticket automation** section becomes available. + +The three toggles are independent — you can enable any combination: + +| Setting | Behavior | +|---|---| +| **Auto-create tickets for flaky tests** | When a test's status changes to flaky, automatically create a ticket and link it to the test. | +| **Auto-create tickets for broken tests** | When a test's status changes to broken, automatically create a ticket and link it to the test. | +| **Auto-close tickets for healthy tests** | When a test returns to healthy, automatically close its linked ticket. The link is kept so the same ticket can be reopened if the test regresses. | + +All settings default to off. + + +Auto-close applies to whatever ticket is linked to the test — including tickets you created manually or linked yourself — not just tickets the automation created. + + +### Close and reopen target statuses + +When auto-close is enabled, you can pick which status closed tickets move to (for example `Done` vs. `Won't Fix` in Jira, or a specific workflow state in Linear). Similarly, reopened tickets can target a specific status. If you don't pick one, Trunk uses a sensible provider default: the first "done"-category status for closing, and a "to do"-style status for reopening. + +## Reopen behavior + +When a test becomes flaky or broken again after its linked ticket was closed, the **Reopen behavior** setting decides what happens: + +| Option | Behavior | +|---|---| +| **Reopen recent tickets** (default) | If the ticket was closed within the reopen window (default 30 days, configurable 1–99), reopen it with a comment noting the re-detection. If it was closed longer ago, unlink it and create a fresh ticket. | +| **Always create a new ticket** | The closed ticket stays closed; a new ticket is created and linked each time. | +| **Do nothing** | The closed ticket stays closed and no new ticket is created. | + +The reopen window is measured from the ticket's close date in your ticketing system, so it behaves correctly whether Trunk or a person closed the ticket. + +## How the automation behaves + +* **One ticket per test.** Each test case has at most one linked ticket at a time. Previous tickets remain visible in the test's [event history](./index#ticket-event-history). +* **Ticket content stays fresh.** Auto-created tickets have their description refreshed as the test's status evolves — for example when a flaky test escalates to broken — so the ticket always reflects current data. Title edits made by your team are preserved, and tickets you created or linked manually are never edited by Trunk (only closed or reopened per your settings). +* **Quiet updates.** Status escalations update the ticket description in place rather than posting comments, so flip-flopping tests don't generate notification noise. Comments are only posted on reopen and close, where the context matters. +* **Clearly attributed.** Auto-created tickets are badged in the dashboard, and every automated action appears in the test's Events tab attributed to Trunk automation — so it's always clear whether Trunk or a teammate acted on a ticket. +* **Resilient to spikes.** A mass status change (for example, a bad merge flipping many tests at once) is absorbed and drained at a pace that respects your ticketing provider's rate limits. + + +For Jira, the configured close/reopen target status must be reachable in a single workflow transition from the ticket's current status. If your Jira workflow requires intermediate steps, the automation records the issue in the test's event history and skips the transition rather than guessing. + + +## Automatic ticketing vs. webhooks + +Before automatic ticketing, the recommended way to auto-create tickets was a [webhook integration](/flaky-tests/webhooks). Webhooks remain fully supported and are still the right tool for custom workflows and unsupported platforms, but the built-in automation is the better default for Linear and Jira: + +| | Automatic ticketing | Webhooks | +|---|---|---| +| Setup | Toggles on the Ticketing settings page | Svix endpoint + provider API transformation | +| Ticket body | Full Trunk ticket content: failure history, impact, common failure reasons, code owners | Whatever your transformation builds from the event payload | +| Lifecycle | Create, reopen, and close managed end to end | Create only, unless you build the rest | +| Dashboard | Tickets linked to test cases, events recorded, auto-created badge | Tickets are not linked back to Trunk | +| Custom platforms | Linear and Jira | Anything with an API | diff --git a/flaky-tests/management/ticketing/index.mdx b/flaky-tests/management/ticketing/index.mdx index 8a14b9fb..a805a5c0 100644 --- a/flaky-tests/management/ticketing/index.mdx +++ b/flaky-tests/management/ticketing/index.mdx @@ -5,6 +5,10 @@ og:title: "Ticketing for flaky tests in Trunk" --- You can integrate directly with your ticketing systems to automatically create tickets when Trunk [detects a flaky test](/flaky-tests/detection). +## Automatic ticketing + +With a connected Linear or Jira integration, Trunk can manage ticket lifecycle automatically: create a ticket when a test becomes flaky or broken, reopen it if a fixed test regresses, and close it when the test returns to healthy. See [Automatic ticketing](./automatic-ticketing) for setup and behavior. + ## Ticket content Flaky Tests automatically generates tickets complete with a title and description. If you’re connected to Linear or Jira, you can also assign default issue types, teams, or assignees. diff --git a/flaky-tests/management/ticketing/jira-integration.mdx b/flaky-tests/management/ticketing/jira-integration.mdx index 6f3a0703..800b4992 100644 --- a/flaky-tests/management/ticketing/jira-integration.mdx +++ b/flaky-tests/management/ticketing/jira-integration.mdx @@ -76,6 +76,10 @@ You need to create an API token with the following scopes: Jira tokens cannot last longer than 365 days. Once the token expires, you will need to generate a new API token. +## Ticket automation + +Once the integration is fully configured, you can enable [automatic ticketing](./automatic-ticketing) from the same settings page: Trunk will create Jira tickets when tests become flaky or broken, reopen them on regression, and close them when tests return to healthy. + ## Create a new ticket You can create a new ticket for any test listed in Trunk Flaky Tests. diff --git a/flaky-tests/management/ticketing/linear-integration.mdx b/flaky-tests/management/ticketing/linear-integration.mdx index 8a7e2242..3b26e21c 100644 --- a/flaky-tests/management/ticketing/linear-integration.mdx +++ b/flaky-tests/management/ticketing/linear-integration.mdx @@ -32,6 +32,10 @@ The following project permissions must be granted to your Linear API key so Trun Selecting _Full Access_ will also grant the required permissions. +## Ticket automation + +Once the integration is fully configured, you can enable [automatic ticketing](./automatic-ticketing) from the same settings page: Trunk will create Linear issues when tests become flaky or broken, reopen them on regression, and close them when tests return to healthy. + ## Create a new ticket You can create a new ticket for any test listed in Flaky Tests. diff --git a/flaky-tests/webhooks/github-issues-integration.mdx b/flaky-tests/webhooks/github-issues-integration.mdx index be6ccd4a..86e1ac9c 100644 --- a/flaky-tests/webhooks/github-issues-integration.mdx +++ b/flaky-tests/webhooks/github-issues-integration.mdx @@ -7,6 +7,10 @@ Trunk allows you to automate GitHub Issue creation through webhooks. This will a This guide will walk you through integrating Trunk Flaky Tests with GitHub Issues through webhooks. You will be able to automatically generate GitHub issues for new flaky tests. This guide should take 15 minutes to complete. + +If your team uses **Linear or Jira**, consider Trunk's built-in [automatic ticketing](/flaky-tests/management/ticketing/automatic-ticketing) instead — richer ticket bodies (failure history, impact, common failure reasons, code owners), automatic reopen and close as test status changes, and full dashboard support with tickets linked back to their test cases. Webhooks remain the right choice for GitHub Issues and other platforms without a built-in integration. + + ## 1. Create a GitHub Token Before you can create a webhook to automate GitHub Issue creation, you need to create an API token to authorize your requests. diff --git a/flaky-tests/webhooks/index.mdx b/flaky-tests/webhooks/index.mdx index e8ce8f89..f83d3687 100644 --- a/flaky-tests/webhooks/index.mdx +++ b/flaky-tests/webhooks/index.mdx @@ -5,6 +5,10 @@ og:title: "Flaky test webhooks in Trunk" --- Trunk provides webhooks for you to build custom integrations to automate workflows, like notifying your team when a test becomes flaky or automatically creating tickets to investigate flaky tests. Trunk provides built-in connectors for [Linear](./linear-integration) and [Jira](./jira-integration) to automate ticket creation, and webhooks let you build custom integrations for use cases that are not supported out of the box. + +**Creating tickets in Linear or Jira?** Trunk's built-in [automatic ticketing](/flaky-tests/management/ticketing/automatic-ticketing) is the recommended approach — it produces richer ticket bodies (failure history, impact, common failure reasons, code owners), manages the full ticket lifecycle (create, reopen, close), and has full dashboard support with tickets linked back to their test cases. Use webhooks for custom workflows or platforms without a built-in integration. + + For Merge Queue webhook events (`pull_request.*` and `pull_request_batch.*`), see the [Merge Queue webhooks reference](/merge-queue/webhooks). diff --git a/flaky-tests/webhooks/jira-integration.mdx b/flaky-tests/webhooks/jira-integration.mdx index d2709da7..6afdd2d4 100644 --- a/flaky-tests/webhooks/jira-integration.mdx +++ b/flaky-tests/webhooks/jira-integration.mdx @@ -7,7 +7,9 @@ Trunk allows you to automate Jira issue creation through webhooks. When a test b This guide will walk you through integrating Trunk Flaky Tests with Jira through webhooks. You will be able to automatically generate Jira issues for **new flaky tests** found in your repo. This guide should take 15 minutes to complete. -Trunk also has a [built-in Jira integration](../management/ticketing/jira-integration) for manual ticket creation. You only need to use webhooks if you want to automate ticket creation or need additional customization. + +**Prefer the built-in integration for Jira.** Trunk's [Jira integration](../management/ticketing/jira-integration) now supports [automatic ticketing](../management/ticketing/automatic-ticketing) natively — richer ticket bodies (failure history, impact, common failure reasons, code owners), automatic reopen and close as test status changes, and full dashboard support with tickets linked back to their test cases. Use webhooks when you need custom payloads or workflows beyond what the built-in automation covers. + ## 1. Create a Jira API Token diff --git a/flaky-tests/webhooks/linear-integration.mdx b/flaky-tests/webhooks/linear-integration.mdx index 8aec0f16..34e22775 100644 --- a/flaky-tests/webhooks/linear-integration.mdx +++ b/flaky-tests/webhooks/linear-integration.mdx @@ -7,7 +7,9 @@ Trunk allows you to automate Linear Issue creation through webhooks. This will a This guide will walk you through integrating Trunk Flaky Tests with Linear Issues through webhooks. You will be able to automatically generate Linear issues for **new flaky tests** found in your repo. This guide should take 15 minutes to complete. -Trunk also has a [built-in Linear integration](/flaky-tests/management/ticketing/linear-integration) for ticket creation. You only need to use webhooks if you want to automate ticket creation or need additional customization. + +**Prefer the built-in integration for Linear.** Trunk's [Linear integration](/flaky-tests/management/ticketing/linear-integration) now supports [automatic ticketing](/flaky-tests/management/ticketing/automatic-ticketing) natively — richer ticket bodies (failure history, impact, common failure reasons, code owners), automatic reopen and close as test status changes, and full dashboard support with tickets linked back to their test cases. Use webhooks when you need custom payloads or workflows beyond what the built-in automation covers. + ## 1. Create a Linear Personal Access Token From d86ee90f370f9bf3cecb44764eda4613150061c8 Mon Sep 17 00:00:00 2001 From: Tyler Beebe Date: Fri, 31 Jul 2026 13:14:05 -0400 Subject: [PATCH 2/4] Update flaky-tests/management/ticketing/automatic-ticketing.mdx Co-authored-by: Tyler Jang --- flaky-tests/management/ticketing/automatic-ticketing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flaky-tests/management/ticketing/automatic-ticketing.mdx b/flaky-tests/management/ticketing/automatic-ticketing.mdx index 0bfc2dc5..dfeb2843 100644 --- a/flaky-tests/management/ticketing/automatic-ticketing.mdx +++ b/flaky-tests/management/ticketing/automatic-ticketing.mdx @@ -41,7 +41,7 @@ When a test becomes flaky or broken again after its linked ticket was closed, th | Option | Behavior | |---|---| | **Reopen recent tickets** (default) | If the ticket was closed within the reopen window (default 30 days, configurable 1–99), reopen it with a comment noting the re-detection. If it was closed longer ago, unlink it and create a fresh ticket. | -| **Always create a new ticket** | The closed ticket stays closed; a new ticket is created and linked each time. | +| **Always create a new ticket** | The closed ticket stays closed; a new ticket is created and linked each time. _Only one ticket can be linked to a Trunk test at a time._ | | **Do nothing** | The closed ticket stays closed and no new ticket is created. | The reopen window is measured from the ticket's close date in your ticketing system, so it behaves correctly whether Trunk or a person closed the ticket. From 32ea684a1b1fcb5cc0b3d8b0aede84e69a151892 Mon Sep 17 00:00:00 2001 From: Tyler Beebe Date: Fri, 31 Jul 2026 13:14:13 -0400 Subject: [PATCH 3/4] Update flaky-tests/management/ticketing/automatic-ticketing.mdx Co-authored-by: Tyler Jang --- flaky-tests/management/ticketing/automatic-ticketing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flaky-tests/management/ticketing/automatic-ticketing.mdx b/flaky-tests/management/ticketing/automatic-ticketing.mdx index dfeb2843..40f27f24 100644 --- a/flaky-tests/management/ticketing/automatic-ticketing.mdx +++ b/flaky-tests/management/ticketing/automatic-ticketing.mdx @@ -58,7 +58,7 @@ The reopen window is measured from the ticket's close date in your ticketing sys For Jira, the configured close/reopen target status must be reachable in a single workflow transition from the ticket's current status. If your Jira workflow requires intermediate steps, the automation records the issue in the test's event history and skips the transition rather than guessing. -## Automatic ticketing vs. webhooks +## Legacy webhook-based ticket autocreation Before automatic ticketing, the recommended way to auto-create tickets was a [webhook integration](/flaky-tests/webhooks). Webhooks remain fully supported and are still the right tool for custom workflows and unsupported platforms, but the built-in automation is the better default for Linear and Jira: From 7597de893c09002dadf84b614acc90212f26ded6 Mon Sep 17 00:00:00 2001 From: Tyler Beebe Date: Fri, 31 Jul 2026 13:18:54 -0400 Subject: [PATCH 4/4] docs: required fields need defaults for automatic ticket creation --- flaky-tests/management/ticketing/automatic-ticketing.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/flaky-tests/management/ticketing/automatic-ticketing.mdx b/flaky-tests/management/ticketing/automatic-ticketing.mdx index 40f27f24..09477718 100644 --- a/flaky-tests/management/ticketing/automatic-ticketing.mdx +++ b/flaky-tests/management/ticketing/automatic-ticketing.mdx @@ -26,6 +26,10 @@ The three toggles are independent — you can enable any combination: All settings default to off. + +Automatic creation fills tickets from your configured [field defaults](./jira-integration#custom-fields) with nobody in the loop. Every field your project requires must have a default set — fields marked **Require user to fill at creation** are prompted for in the manual create-ticket modal, which automatic creation can't do. + + Auto-close applies to whatever ticket is linked to the test — including tickets you created manually or linked yourself — not just tickets the automation created.