[TRUNK-17841] Add Jira webhook integration docs by samgutentag · Pull Request #526 · trunk-io/docs

samgutentag · 2026-03-27T18:38:27Z

Summary

New docs page for configuring automated Jira issue creation via Svix webhooks (flaky-tests/webhooks/jira-integration.md)
Mirrors the existing Linear webhook integration page structure: API token setup, endpoint config, custom headers, transformation code, testing, and monitoring
Updated webhooks overview to mention both Linear and Jira connectors
Added Jira integration to summary.md table of contents

Linear tickets

TRUNK-17841 - Create Jira Connector for Svix webhooks

Engineering authors

@tyler-jang (Tyler Beebe - created TRUNK-17841, configured the Svix connector)

Context links

Tyler Beebe Slack DM (2026-03-27): https://trunk-io.slack.com/archives/D0A82G6A1JB/p1774631462446669
Live on staging: https://app.trunk-staging.io/trunk-staging-org/settings/organization/webhooks

Files changed

flaky-tests/webhooks/jira-integration.md (new) - Full setup guide for Jira webhook integration
flaky-tests/webhooks/README.md (updated) - Overview text and card grid
summary.md (updated) - TOC entry

Open questions

Is there a dedicated "Automate Jira Issues Creation" button in the Svix UI, or do users create a generic endpoint? (Assumed button exists based on Linear pattern)
Should we mention the scoped API token URL difference (api.atlassian.com/ex/jira/{cloudId}) for users with scoped tokens? Tyler flagged this in #team-flaky-tests.
Transformation code uses Jira wiki markup for descriptions - should we note that Jira Cloud also supports ADF (Atlassian Document Format)?

Test plan

Check GitBook preview renders correctly on the change request branch
Verify all internal links resolve (ticketing integration cross-reference, webhooks overview)
Confirm transformation code matches what's in the Svix dashboard
Verify the setup steps match the actual connector UI flow

🤖 Generated with Claude Code

New page for configuring the Svix Jira connector to automatically create Jira issues when tests become flaky. Mirrors the existing Linear webhook integration page. Updates webhooks overview and summary TOC. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

trunk-staging-io · 2026-03-27T18:38:31Z

Merging to main in this repository is managed by Trunk.

To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

acatxnamedvirtue

Looks good!
nice work claude :P

claude · 2026-03-27T18:52:48Z

Claude finished @samgutentag's task in 2m 18s —— View job

PR Review

Gather context and read changed files
Review documentation for typos, grammar, and formatting
Check documentation best practices
Post review feedback

Overall this is a well-structured doc that cleanly mirrors the Linear webhook integration page. No blocking issues — a few minor nits below.

flaky-tests/webhooks/jira-integration.md

Line 37 — confirm button exists: The PR flags it as an open question whether the Automate Jira Issues Creation button exists in the Svix UI. If it doesn't, step 3 in section 2 would guide users to the wrong place.
Line 80 — phrasing nit: "Here is the provided transformation for context" is awkward. Suggested alternative in the inline comment.
Line 173 — repetitive phrasing: "You can create test issues… You can do this by:" — suggested simplification in the inline comment.

Open questions from the PR body (not blocking, but worth tracking):

Scoped API token users need a different base URL (api.atlassian.com/ex/jira/{cloudId}) — currently undocumented.
Jira Cloud supports ADF (Atlassian Document Format) in addition to Jira wiki markup — the hint at line 168 could mention this as an option.

flaky-tests/webhooks/README.md and summary.md — both look good.

acatxnamedvirtue · 2026-03-27T18:53:33Z

RE: Open questions:

Is there a dedicated "Automate Jira Issues Creation" button in the Svix UI, or do users create a generic endpoint? (Assumed button exists based on Linear pattern)
Yes it is a dedicated button
Should we mention the scoped API token URL difference (api.atlassian.com/ex/jira/{cloudId}) for users with scoped tokens? Tyler flagged this in #team-flaky-tests.
I wouldn't mention it until we fully add support for scoped tokens later
descriptions as ADF format
I doubt anyone would willingly write ADF themselves in the transformer. Blegh

claude · 2026-03-27T18:54:58Z

flaky-tests/webhooks/jira-integration.md

+
+<table><thead><tr><th width="346">Constant</th><th>Description</th></tr></thead><tbody><tr><td><code>JIRA_PROJECT_KEY</code></td><td>(<strong>Required)</strong> Your Jira project key (e.g., <code>ENG</code>, <code>PROJ</code>).</td></tr><tr><td><code>JIRA_ISSUE_TYPE</code></td><td><strong>(Optional)</strong> The issue type to create. Defaults to <code>Bug</code>.</td></tr><tr><td><code>JIRA_LABELS</code></td><td>(<strong>Optional)</strong> Array of labels to add to the issue. Defaults to <code>["flaky-test"]</code>.</td></tr><tr><td><code>JIRA_CUSTOM_FIELDS</code></td><td>(<strong>Optional)</strong> Object of custom field key-value pairs for projects that require additional fields.</td></tr><tr><td><code>PRS_IMPACTED_THRESHOLD</code></td><td>Issues will be created only for flaky tests that have impacted more PRs than the <code>PRS_IMPACTED_THRESHOLD</code>.<br><br>You can adjust this value if you see many issues about low-impact flaky tests.</td></tr></tbody></table>
+
+Here is the provided transformation for context. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.


Minor phrasing nit — "Here is the provided transformation for context" is slightly awkward.

Suggested change

Here is the provided transformation for context. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.

Here is the default transformation code for reference. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.

claude · 2026-03-27T18:55:02Z

flaky-tests/webhooks/jira-integration.md

+
+### 6. Test your webhook
+
+You can create test issues by delivering a mock webhook. You can do this by:


Nit: "You can … You can do this by:" is slightly repetitive.

Suggested change

You can create test issues by delivering a mock webhook. You can do this by:

Send a test Jira issue by delivering a mock webhook:

claude · 2026-03-27T18:55:05Z

flaky-tests/webhooks/jira-integration.md

+
+1. Login to [Trunk Flaky Tests](https://app.trunk.io/login?intent=flaky%20tests)
+2. From your profile on the top right, navigate to **Settings**
+3. Under **Organization > Webhooks**, click **Automate Jira Issues Creation**.


The PR notes this as an open question — if the Automate Jira Issues Creation button doesn't exist in the Svix UI (unlike the Linear connector), users would need to create a generic endpoint instead. Worth confirming with Tyler that this specific button is live before this page gets traffic.

github-actions

Auto-approved: Claude code review passed.

samgutentag requested review from TylerJang27 and acatxnamedvirtue March 27, 2026 18:38

acatxnamedvirtue approved these changes Mar 27, 2026

View reviewed changes

samgutentag marked this pull request as ready for review March 27, 2026 18:52

samgutentag merged commit 6b549ed into main Mar 27, 2026
5 of 6 checks passed

samgutentag deleted the sam-gutentag/jira-webhook-integration branch March 27, 2026 18:52

claude bot reviewed Mar 27, 2026

View reviewed changes

github-actions bot approved these changes Mar 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[TRUNK-17841] Add Jira webhook integration docs#526

[TRUNK-17841] Add Jira webhook integration docs#526
samgutentag merged 1 commit intomainfrom
sam-gutentag/jira-webhook-integration

samgutentag commented Mar 27, 2026

Uh oh!

trunk-staging-io bot commented Mar 27, 2026

Uh oh!

acatxnamedvirtue left a comment

Uh oh!

Uh oh!

claude bot commented Mar 27, 2026 •

edited

Loading

Uh oh!

acatxnamedvirtue commented Mar 27, 2026

Uh oh!

claude bot Mar 27, 2026

Uh oh!

claude bot Mar 27, 2026

Uh oh!

claude bot Mar 27, 2026

Uh oh!

github-actions bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants


		<table><thead><tr><th width="346">Constant</th><th>Description</th></tr></thead><tbody><tr><td><code>JIRA_PROJECT_KEY</code></td><td>(<strong>Required)</strong> Your Jira project key (e.g., <code>ENG</code>, <code>PROJ</code>).</td></tr><tr><td><code>JIRA_ISSUE_TYPE</code></td><td><strong>(Optional)</strong> The issue type to create. Defaults to <code>Bug</code>.</td></tr><tr><td><code>JIRA_LABELS</code></td><td>(<strong>Optional)</strong> Array of labels to add to the issue. Defaults to <code>["flaky-test"]</code>.</td></tr><tr><td><code>JIRA_CUSTOM_FIELDS</code></td><td>(<strong>Optional)</strong> Object of custom field key-value pairs for projects that require additional fields.</td></tr><tr><td><code>PRS_IMPACTED_THRESHOLD</code></td><td>Issues will be created only for flaky tests that have impacted more PRs than the <code>PRS_IMPACTED_THRESHOLD</code>.<br><br>You can adjust this value if you see many issues about low-impact flaky tests.</td></tr></tbody></table>

		Here is the provided transformation for context. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.

	Here is the provided transformation for context. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.
	Here is the default transformation code for reference. You can customize your Jira issues integration by following the [Jira REST API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post) and [Svix transformations](https://docs.svix.com/transformations#using-transformations) documentation.


		### 6. Test your webhook

		You can create test issues by delivering a mock webhook. You can do this by:

	You can create test issues by delivering a mock webhook. You can do this by:
	Send a test Jira issue by delivering a mock webhook:

Conversation

samgutentag commented Mar 27, 2026

Summary

Linear tickets

Engineering authors

Context links

Files changed

Open questions

Test plan

Uh oh!

trunk-staging-io bot commented Mar 27, 2026

Uh oh!

acatxnamedvirtue left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Uh oh!

acatxnamedvirtue commented Mar 27, 2026

Uh oh!

claude bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

claude bot commented Mar 27, 2026 •

edited

Loading