From 96bed58df6ab5057b701006c528aedf6b8532173 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 20:22:38 -0800 Subject: [PATCH] Add Multiple Repositories and Forks page for Flaky Tests Document how Trunk identifies repos by git remote URL (not API token), enabling safe use of the same org token across forks. Covers repo identification, fork workflows, --repo-url overrides, and common scenarios like private forks, multiple forks, and monorepo variants. Co-Authored-By: Claude Opus 4.6 --- .../get-started/multiple-repositories.md | 151 ++++++++++++++++++ summary.md | 1 + 2 files changed, 152 insertions(+) create mode 100644 flaky-tests/get-started/multiple-repositories.md diff --git a/flaky-tests/get-started/multiple-repositories.md b/flaky-tests/get-started/multiple-repositories.md new file mode 100644 index 00000000..02e7554e --- /dev/null +++ b/flaky-tests/get-started/multiple-repositories.md @@ -0,0 +1,151 @@ +--- +description: Learn how Trunk identifies repositories and how to use Trunk Flaky Tests with forks or multiple related repositories. +--- + +# Multiple Repositories and Forks + +Trunk Flaky Tests identifies repositories by their **git remote URL**, not by the API token. You can safely use the same organization API token across multiple repositories -- including forks -- without mixing test results. + +## How Repository Identification Works + +When the Trunk Analytics CLI uploads test results, it reads the git remote URL from your local git configuration: + +```bash +git config remote.origin.url +# Example: git@github.com:your-company/your-repo.git +``` + +The CLI parses the URL into three components that uniquely identify the repository: + +| Component | Example | +| --------- | ------------------- | +| **Host** | `github.com` | +| **Owner** | `your-company` | +| **Name** | `your-repo` | + +The API token determines which **organization** the upload belongs to. The **repository** is determined entirely by the git remote URL. + +## Using Trunk with Forks + +If you run tests from a fork, Trunk automatically keeps results separate based on the fork's remote URL. No special configuration is needed. + +### Example: Forking an Open Source Project + +Suppose your company forks `metabase/metabase` to `your-company/metabase-fork`: + +| Repository | Remote URL | Trunk Repo ID | +| ----------- | -------------------------------------------- | ------------------------------ | +| Original | `github.com/metabase/metabase` | `metabase/metabase` | +| Your fork | `github.com/your-company/metabase-fork` | `your-company/metabase-fork` | + +Both repositories can use the **same organization API token**. Trunk creates separate repo entries and keeps all test data isolated. + +### Verify Your Remote URL + +Before setting up uploads, verify your CI job uses the correct remote: + +```bash +git remote -v +# origin git@github.com:your-company/metabase-fork.git (fetch) +# origin git@github.com:your-company/metabase-fork.git (push) +``` + +{% hint style="info" %} +Some CI providers set environment variables like `GITHUB_REPOSITORY` that may differ from your git remote. The CLI prioritizes the git remote URL by default. +{% endhint %} + +## Overriding Repository Detection + +In some cases you may need to manually specify the repository URL: + +* CI environments where the git remote is not available or is incorrect +* Uploading results from a build artifact without a git checkout +* Shallow clones with modified remotes + +### Using the `--repo-url` Flag + +```bash +./trunk-analytics-cli upload \ + --junit-paths "test_output.xml" \ + --org-url-slug \ + --token $TRUNK_API_TOKEN \ + --repo-url "https://github.com/your-company/your-repo.git" +``` + +You can also set this via environment variable: + +```bash +export TRUNK_REPO_URL="https://github.com/your-company/your-repo.git" +``` + +### Uploading Without a Git Checkout + +For CI environments where you download build artifacts instead of checking out the repository, use the `--use-uncloned-repo` flag along with the required metadata: + +```bash +./trunk-analytics-cli upload \ + --junit-paths "test_output.xml" \ + --org-url-slug \ + --token $TRUNK_API_TOKEN \ + --use-uncloned-repo \ + --repo-url "https://github.com/your-company/your-repo.git" \ + --repo-head-sha "abc123def456" \ + --repo-head-branch "main" \ + --repo-head-author-name "CI Bot" +``` + +{% hint style="info" %} +For the full list of CLI flags and environment variables, see the [Trunk Analytics CLI](../uploader.md#full-command-reference) reference. +{% endhint %} + +## Common Scenarios + +### Private Fork of a Public Repository + +**Goal:** Track flaky tests in your private fork separately from the upstream project. + +**Solution:** No special configuration needed. Your fork has a different remote URL by default, so Trunk automatically keeps the data separate. Use your existing organization API token. + +### Multiple Forks in the Same Organization + +**Goal:** Track tests from multiple forks (for example, `your-company/fork-a` and `your-company/fork-b`) using the same Trunk organization. + +**Solution:** Use the same API token for all forks. Each fork appears as a separate repository in Trunk based on its remote URL. + +### Monorepo with Multiple Test Suites + +**Goal:** Track different test suites within the same repository separately. + +**Solution:** Use the `--variant` flag to group test results by suite: + +```bash +# Frontend tests +./trunk-analytics-cli upload \ + --junit-paths "frontend/test_output.xml" \ + --variant "frontend" \ + --org-url-slug \ + --token $TRUNK_API_TOKEN + +# Backend tests +./trunk-analytics-cli upload \ + --junit-paths "backend/test_output.xml" \ + --variant "backend" \ + --org-url-slug \ + --token $TRUNK_API_TOKEN +``` + +## Troubleshooting + +### Test Results Appearing in the Wrong Repository + +1. **Check your git remote:** Run `git remote -v` in your CI job to verify the URL matches the expected repository. +2. **Check CI environment variables:** Some CI providers override git configuration. See your [CI provider's guide](ci-providers/) for details. +3. **Use an explicit override:** Set `--repo-url` to force the correct repository. + +### Duplicate Repositories in the Dashboard + +This can happen if the same repository is uploaded with different URL formats (for example, HTTPS vs SSH). Trunk normalizes most formats, but if you see duplicates: + +1. Standardize the remote URL format across all CI jobs. +2. Use `--repo-url` to set a consistent URL explicitly. +3. Contact [support@trunk.io](mailto:support@trunk.io) to merge duplicate repository entries. diff --git a/summary.md b/summary.md index 89ef27cb..a8e83191 100644 --- a/summary.md +++ b/summary.md @@ -90,6 +90,7 @@ * [Semaphore CI](flaky-tests/get-started/ci-providers/semaphoreci.md) * [Travis CI](flaky-tests/get-started/ci-providers/travisci.md) * [Other CI Providers](flaky-tests/get-started/ci-providers/otherci.md) + * [Multiple Repositories and Forks](flaky-tests/get-started/multiple-repositories.md) * [Managing detected flaky tests](flaky-tests/managing-detected-flaky-tests.md) * [Dashboard](flaky-tests/dashboard.md) * [Flaky test detection](flaky-tests/detection.md)