GITBOOK-766: Linear integration + link to ticket API

Author: rdraward

.gitbook/assets/create-ticket-button-dark.png

@@ -48,7 +48,7 @@ If you have a codeowners file configured in your repos, you will see who owns ea
 
 <figure><picture><source srcset="../.gitbook/assets/details-code-owners-dark.png" media="(prefers-color-scheme: dark)"><img src="../.gitbook/assets/details-code-owners-light (1).png" alt=""></picture><figcaption><p>You can find the code owners of each test on the top right of the test details screen.</p></figcaption></figure>
 
-This information will also be provided when creating a ticket with the [Jira integration](jira-integration.md) or [webhooks](webhooks/).
+This information will also be provided when creating a ticket with the [Jira integration](ticketing-integrations/jira-integration.md) or [webhooks](webhooks/).
 
 ### **Failure Types**
 

.gitbook/assets/create-ticket-button-light.png

@@ -39,7 +39,7 @@ In your CI job, update your `pytest` command to include the `--junit-xml` and `j
 pytest --junit-xml=junit.xml -o junit_family=xunit1
 ```
 
-The `junit_family=xunit1` is necessary so that the generated XML report includes file paths for each test case. File paths for test cases are used for features that use code owners like the [Jira integration](../../jira-integration.md) and [webhooks](../../webhooks/).
+The `junit_family=xunit1` is necessary so that the generated XML report includes file paths for each test case. File paths for test cases are used for features that use code owners like the [Jira integration](../../ticketing-integrations/jira-integration.md) and [webhooks](../../webhooks/).
 
 #### Report File Path
 

.gitbook/assets/jira.png

@@ -62,7 +62,7 @@ To learn more, [see our docs about quarantining tests](quarantining.md).
 
 Trunk enables the automation of quickly creating and assigning tickets through integrations with platforms like Jira and Linear, as well as custom workflows with webhooks. The status of tickets created will be reflected in real-time in the Trunk web app. This helps you track efforts to fix high-impact, flaky tests.
 
-To learn more, [learn about our ticketing integrations](jira-integration.md).
+To learn more, [learn about our ticketing integrations](ticketing-integrations/jira-integration.md).
 
 ### **Next Steps**
 

.gitbook/assets/linear-integration-dark.png

@@ -0,0 +1,32 @@
+---
+description: >-
+  Triage your flaky tests faster by creating automatically assigned and labeled
+  tickets in your ticketing system
+---
+
+# Ticketing Integrations
+
+You can integrate directly with your ticketing systems to automatically create tickets when Trunk [detects a broken or flaky test](../detection.md).
+
+### 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.
+
+The ticket description contains the following information:
+
+* Identifier of the test
+* Since when has the test been labeled flaky
+* The last time this test failed
+* The impact when run on PRs
+* The impact when run on branches
+* Quarantine status
+* Most common failure reasons
+* Code owners, according to the [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file in your repository
+
+### Integration Setup
+
+Currently, Ticket Creation supports integrations with Linear and Jira. However, the automatically generated ticket content is formatted in Markdown and can be copied to other platforms like Asana or GitHub issues.
+
+<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><a data-footnote-ref href="#user-content-fn-1"><strong>Linear</strong></a></td><td><a href="../../.gitbook/assets/linear-v2.png">linear-v2.png</a></td><td><a href="linear-integration.md">linear-integration.md</a></td></tr><tr><td align="center"><strong>Jira</strong></td><td><a href="../../.gitbook/assets/jira.png">jira.png</a></td><td><a href="jira-integration.md">jira-integration.md</a></td></tr></tbody></table>
+
+[^1]: 

.gitbook/assets/linear-integration-light.png

@@ -0,0 +1,47 @@
+---
+description: >-
+  Triage your flaky tests faster by creating automatically assigned and labeled
+  tickets with the Jira integration
+---
+
+# Jira Integration
+
+When Trunk Flaky Tests [detects a broken or flaky test](../detection.md), you can create an automatically generated Jira ticket for your team to pick up and fix the test.
+
+Webhook payloads will also contain ticket information when a Jira ticket is created with the integration or when [existing tickets are linked](jira-integration.md#link-existing-tickets-to-tests).
+
+### Connecting to Jira
+
+<figure><picture><source srcset="../../.gitbook/assets/jira-connect-form-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/jira-connect-form-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+To connect a Jira Cloud project, navigate to **Settings** -> **Repositories** -> **Ticketing Integration** and select **Jira** as your Ticketing System.
+
+Then complete the form and click Connect to Jira Cloud with the following information.
+
+<table data-full-width="false"><thead><tr><th width="176">Field Name</th><th width="266">Description</th><th>Examples</th></tr></thead><tbody><tr><td>Jira URL</td><td>The URL to your Jira Cloud project.</td><td><code>https://trunk-io.atlassian.net</code></td></tr><tr><td>Project Key</td><td>The project key for your Jira project.</td><td><code>KAN</code></td></tr><tr><td>Email</td><td>The email associated with your Jira API token.</td><td><code>[email protected]</code></td></tr><tr><td>Jira API token</td><td><a href="https://id.atlassian.com/manage-profile/security/api-tokens">Create your Jira API token here.</a></td><td><code>ATATT*****19FNY5Q</code></td></tr><tr><td>Default label(s) for new tickets</td><td>Labels applied to new Jira tickets created through Trunk Flaky Tests</td><td><code>flaky-test, debt</code></td></tr></tbody></table>
+
+After connecting to Jira, you can specify a default issue type for new tickets and a default assignee for new tickets.&#x20;
+
+### Create a New Ticket
+
+You can create a new ticket for any test listed in Trunk Flaky Tests.&#x20;
+
+There are 2 ways to create a new ticket in the Flaky Test dashboard:
+
+* Click on the options menu for any test case on the repo overview dashboard
+
+<figure><picture><source srcset="../../.gitbook/assets/create-ticket-button-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/create-ticket-button-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+* Use the Create ticket button in the top left corner of the [test case details](../detection.md#test-case-details) page.
+
+Before you create the ticket, you will have a preview of the title and description.
+
+<figure><picture><source srcset="../../.gitbook/assets/jira-ticket-creation-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/jira-ticket-creation-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+#### Create with Jira
+
+If you are connected to Jira, you can click the **Create Jira Ticket** button at the end of the modal, which will automatically create a ticket with the configured labels and assignees.
+
+#### Link existing tickets to tests
+
+If you already have a ticket in Jira that you want to link to a test in the dashboard, you can use the [Link Ticket to Test Case API](../../references/apis/flaky-tests.md#post-flaky-tests-link-ticket-to-test-case).

.gitbook/assets/linear-ticket-creation-dark.png

@@ -0,0 +1,50 @@
+---
+description: >-
+  Triage your flaky tests faster by creating automatically assigned and labeled
+  tickets with the Linear integration
+---
+
+# Linear Integration
+
+When Trunk Flaky Tests [detects a broken or flaky test](../detection.md), you can create an automatically generated Linear ticket for your team to pick up and fix the test.
+
+Webhook payloads will also contain ticket information when a Jira ticket is created with the integration or when [existing tickets are linked](linear-integration.md#link-existing-tickets-to-tests).
+
+### Connecting to Linear
+
+<figure><picture><source srcset="../../.gitbook/assets/linear-integration-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/linear-integration-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+To connect a Linear project:
+
+1. Navigate to **Settings** > **Repositories** > **Ticketing Integration.**
+2. Select **Linear** as your Ticketing System.
+3. Add a Linear API key
+4. Select a Team and **Connect to Linear**.
+
+After connecting to Linear, you can specify a default project and a default assignee for new tickets.&#x20;
+
+### Create a New Ticket
+
+You can create a new ticket for any test listed in Flaky Tests.&#x20;
+
+There are 2 ways to create a new ticket in the Flaky Test dashboard:
+
+* Click on the options menu for any test case on the repo overview dashboard
+
+<figure><picture><source srcset="../../.gitbook/assets/create-ticket-button-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/create-ticket-button-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+* Use the Create ticket button in the top left corner of the [test case details](../detection.md#test-case-details) page.
+
+Before you create the ticket, you get a preview of the title and description.
+
+<figure><picture><source srcset="../../.gitbook/assets/jira-ticket-creation-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/jira-ticket-creation-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+#### Create with Linear
+
+If you are connected to Linear, you can click the **Create Linear Ticket** button at the end of the modal to automatically create a ticket with the configured team and assignees.
+
+Note: You can use [Flaky Tests webhooks](../webhooks/linear-integration.md) to automate ticket creation, or if you need more control over how tickets are created in Linear. This integration is not required when using webhooks.
+
+#### Link existing tickets to tests
+
+If you already have a ticket in Linear that you want to link to a test in the dashboard, you can use the [Link Ticket to Test Case API](../../references/apis/flaky-tests.md#post-flaky-tests-link-ticket-to-test-case).

.gitbook/assets/linear-ticket-creation-light.png

@@ -0,0 +1,27 @@
+---
+description: >-
+  Triage your flaky tests faster by manually creating tickets from generated
+  markdown
+---
+
+# Other Ticketing Platforms
+
+If you have not set up an integration, Trunk Flaky Tests can still generate a ticket title and description so you can copy and paste the details into your project management software.
+
+### Create a New Ticket
+
+You can create a new ticket for any test listed in Trunk Flaky Tests. 
+
+There are 2 ways to create a new ticket in the Flaky Test dashboard:
+
+* Click on the options menu for any test case on the repo overview dashboard
+
+<figure><picture><source srcset="../../.gitbook/assets/create-ticket-button-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/create-ticket-button-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+* Use the Create ticket button in the top left corner of the [test case details](../detection.md#test-case-details) page.
+
+Before you create the ticket, you will have a preview of the title and description.
+
+<figure><picture><source srcset="../../.gitbook/assets/manual-ticket-creation-dark.png" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/manual-ticket-creation-light.png" alt=""></picture><figcaption></figcaption></figure>
+
+Now you can copy and paste the ticket title and description into your project management or ticketing platform.

.gitbook/assets/linear-v2.png

@@ -10,6 +10,8 @@ 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 that **impact more than 2 PRs**. This guide should take 15 minutes to complete.
 
+Trunk also has a [built-in Linear integration](linear-integration.md) for ticket creation. You only need to use webhooks if you want to automate ticket creation or need additional customization.
+
 ### 1. Create a Linear Personal Access Token
 
 Before you can create a webhook to automate GitHub Issue creation, you need to create an API token to authorize your requests.

.gitbook/assets/manual-ticket-creation-dark.png

@@ -8,3 +8,10 @@ All requests must be [authenticated](./#authentication) by providing the `x-api-
 [Broken link](broken-reference)
 {% endopenapi-operation %}
 
+{% openapi-operation spec="trunk-api" path="/flaky-tests/list-quarantined-tests" method="post" %}
+[Broken link](broken-reference)
+{% endopenapi-operation %}
+
+{% openapi-operation spec="trunk-api" path="/flaky-tests/link-ticket-to-test-case" method="post" %}
+[Broken link](broken-reference)
+{% endopenapi-operation %}

.gitbook/assets/manual-ticket-creation-light.png

@@ -63,7 +63,10 @@
 * [Flaky Test Detection](flaky-tests/detection.md)
 * [Quarantining](flaky-tests/quarantining.md)
 * [PR Comments](flaky-tests/github-pull-request-comments.md)
-* [Jira Integration](flaky-tests/jira-integration.md)
+* [Ticketing Integrations](flaky-tests/ticketing-integrations/README.md)
+  * [Jira Integration](flaky-tests/ticketing-integrations/jira-integration.md)
+  * [Linear Integration](flaky-tests/ticketing-integrations/linear-integration.md)
+  * [Other Ticketing Platforms](flaky-tests/ticketing-integrations/other-ticketing-platforms.md)
 * [Webhooks](flaky-tests/webhooks/README.md)
   * [Slack Integration](flaky-tests/webhooks/slack-integration.md)
   * [Microsoft Teams Integration](flaky-tests/webhooks/microsoft-teams-integration.md)