> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Set up Trunk Flaky Tests by creating a test collection, configuring test result output, uploading from CI, and enabling flake detection monitors.

Trunk Flaky Tests detects flaky tests by analyzing test results from your CI runs. Setup requires a test collection, test result output, and CI upload integration.

## Prerequisites

* Account at [app.trunk.io](https://app.trunk.io)
* Ability to modify repository CI configuration and add secrets
* A Trunk API key with the **Upload test results** permission, or access to create one under **Settings** → **Developer** → **API Keys**
* Tests running in CI on both PRs and stable branches (e.g., main, master, or develop)

### Step 1: Create a test collection

A [test collection](https://docs.trunk.io/flaky-tests/test-collections.md) is a named group of tests with its own flake detection, quarantining, and ticketing settings. CI uploads go to a collection, so create one first.

1. Open Flaky Tests at [app.trunk.io](https://app.trunk.io). Your first collection is created from the form Flaky Tests opens on; later ones from **Create collection** in the actions menu on the collections list.
2. Enter a **Collection name**, and a description if you want one.
3. Copy the new collection's **Collection ID**, from its page header or URL. You pass it to every upload step in Step 3.

Create more than one collection to hold different test suites to different standards, such as unit and end-to-end tests. See [Collections and repositories](https://docs.trunk.io/flaky-tests/test-collections.md#collections-and-repositories).

### Step 2: Ensure JUnit XML output

Trunk ingests test results in JUnit XML format. If your CI already generates JUnit XML, note the file paths and skip to Step 3.

If not, configure your test frameworks to output JUnit XML:

* See [**Test Frameworks**](./frameworks/) for framework-specific configuration
* Supports multiple frameworks simultaneously

### Step 3: Configure CI uploads

Add test result uploads to all CI jobs that run tests. Uploads go through the [`trunk` CLI](./trunk-cli): install it, store a Trunk API key with the **Upload test results** permission with `trunk auth api-key set`, and run `trunk flakytests upload` after your tests. On GitHub Actions, the [`trunk-io/analytics-uploader@v3`](./ci-providers/github-actions) action does all three. Every upload step passes the **Collection ID** from Step 1, as `--test-collection-id` or the `TRUNK_TEST_COLLECTION_ID` environment variable.

1. Create an API key with the **Upload test results** permission. See [Create an API key](https://docs.trunk.io/flaky-tests/get-started/trunk-cli.md#create-an-api-key).
2. See [**CI Providers**](./ci-providers/) for integration instructions
3. Configure uploads in jobs that run on:
   * Pull request branches
   * Stable branches (`main`, `master`, `develop`, etc.)
   * Merge queue branches (if applicable)

Uploads from both PRs and stable branches are required for Trunk Flaky Tests to accurately detect flaky tests.

> [!NOTE]
>
> Trunk automatically recognizes `main`, `master`, and `develop` as stable branches. If your primary branch uses a different name, configure uploads from that branch the same way and Trunk will classify it correctly.

### Step 4: Verify integration

1. Push your changes and trigger a CI run
2. Check CI logs for successful upload confirmation
3. Results typically appear within a few minutes. Verify uploads appear at [app.trunk.io](https://app.trunk.io) on your [test collection](https://docs.trunk.io/flaky-tests/test-collections.md)'s **Uploads** tab

![](https://mintcdn.com/trunk-4cab4936/WAR0qJ1WO0rtUlqz/assets/flaky-tests/get-started/Screenshot_2025-11-11_at_3.58.16_PM.png?fit=max\&auto=format\&n=WAR0qJ1WO0rtUlqz\&q=85\&s=56db555ba48d5c64182d8038b424a005)

Uploads tab

### Step 5: Configure flake detection

After uploads are flowing, open your [test collection](https://docs.trunk.io/flaky-tests/test-collections.md)'s **Monitors** tab to set up detection.

A collection arrives with [five monitors already seeded](https://docs.trunk.io/flaky-tests/test-collections.md#what-a-new-collection-starts-with), including pass-on-retry, failure count, and failure rate. Your job here is to check them against how you actually run tests — the seeded branch patterns in particular are defaults, not a reading of your repository.

**Failure rate monitors** let you detect flakiness based on failure rate over a rolling time window. How you configure them depends on your CI setup:

* **If tests must pass before merging to main**, set up a failure rate monitor scoped to `main` to catch an elevated failure rate. For example, if you run tests 5 times per day on `main`, a 24-hour rolling window with a minimum of 4 runs and a failure threshold of 25% is a reasonable starting point. This gives the monitor enough data before flagging anything.
* **If you use a merge queue**, consider a dedicated monitor scoped to your merge queue branches (e.g., `trunk-merge/*` or `gh-readonly-queue/*`). Failures here are especially suspicious since the code has already passed PR checks, so a low threshold is appropriate.

[How failure rate monitors work →](https://docs.trunk.io/flaky-tests/detection/failure-rate-monitor.md)

### Quarantining

Quarantining suppresses failures from known flaky tests, preventing them from forcing CI re-runs or blocking your merge queue. Flaky tests continue to run and report results — they just don't cause pipeline failures while your team works on fixes. This is especially valuable for unblocking merge queues and keeping development velocity high.

[Configure Quarantining →](../quarantining/)
