[TRUNK-17582] Add Multiple Repositories and Forks guide for Flaky Tests

[samgutentag]

Summary

• New page at flaky-tests/get-started/multiple-repositories.md explaining how Trunk identifies repositories by git remote URL, not API token
• Documents safe use of the same org API token across forks and multiple repos
• Covers repo identification, fork workflows, --repo-url overrides, uploading without git checkout, and common scenarios (private forks, multiple forks, monorepo variants)
• Updated summary.md to add the page under Getting Started after CI Providers

Linear

• TRUNK-17582

Context

Customer question in Slack about whether using the same API key for a private fork would mix test results. Answer: repos are identified by git remote URL (host/owner/name), so forks with different remotes are automatically separate.

• Slack thread: https://trunk-io.slack.com/archives/C09E85RBK0B/p1771256832436079

Test plan

• Verify page renders correctly in GitBook preview (Change Request)
• Confirm summary.md entry appears in correct location in sidebar
• Verify hint blocks and code blocks render properly
• Check cross-reference link to CLI reference resolves correctly
• Verify --repo-url and --use-uncloned-repo flag documentation matches current CLI behavior

🤖 Generated with Claude Code

[claude]

Claude finished @pat-trunk-io's task in 2m 7s —— View job

---

PR Review: Multiple Repositories and Forks guide

• Read changed files
• Review for typos, grammar, and formatting issues
• Check documentation best practices
• Post inline comments for specific issues
• Final summary

---

Overall, this is a well-structured and clearly written guide that directly addresses a real customer question. The content is accurate, well-organized, and the examples are helpful. A few minor issues noted:

Issues found:

1. Line 7 — Double hyphens (--) used as em dashes. View inline comment →

2. Line 59 — Missing comma: "In some cases you may need" → "In some cases, you may need". View inline comment →

3. Line 83 — --use-uncloned-repo and --repo-head-author-name flags are not listed in the Trunk Analytics CLI reference. Please verify these flags exist and consider documenting them, or update the example to only use documented flags. View inline comment →

What looks good:

• Frontmatter description is clear and accurate
• Section structure (How It Works → Using with Forks → Overriding → Scenarios → Troubleshooting) follows a logical progression
• The --variant flag is correctly documented in the CLI reference
• The --repo-url cross-reference link to ../uploader.md#full-command-reference resolves correctly
• summary.md entry is placed correctly after CI Providers
• Hint blocks and code examples are used appropriately

The undocumented flags (item 3) is the most important thing to verify before merging. Fix this →

[claude]

Minor style nit: double hyphens (--) used as em dashes can look informal in docs. Consider using an actual em dash (—) or rewording to avoid it:

Suggested change

	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.
	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.

[claude]

Missing comma after the introductory phrase:

Suggested change

	In some cases you may need to manually specify the repository URL:
	In some cases, you may need to manually specify the repository URL:

[claude]

The --use-uncloned-repo and --repo-head-author-name flags referenced in the code example below (lines 90 and 94) do not appear to be documented in the Trunk Analytics CLI reference. Please verify these flags exist in the current CLI and consider adding them to the reference page, or remove them from this example if they aren't valid flags.

[pat-trunk-io]

This link goes to Not Found

[pat-trunk-io]

I meant your link you posted https://github.com/trunk-io/docs/uploader.md#full-command-reference gets me not found

[claude]

Claude finished @pat-trunk-io's task in 2m 7s —— View job

---

PR Review: Multiple Repositories and Forks guide

• Read changed files
• Check uploader.md for flag documentation and correct path
• Review updated content for remaining issues
• Post final summary

---

This is a well-structured, clearly written guide that addresses a real customer question. The content and organization are solid. Three issues remain unaddressed from the previous review:

Issues:

1. Line 7 — Double hyphens (--) used as em dashes. Suggestion:

   ...across multiple repositories — including forks — without mixing test results.

2. Line 59 — Missing comma after introductory phrase:

   In some cases, you may need to manually specify the repository URL:

3. Lines 83–95 (blocking) — --use-uncloned-repo (line 90) and --repo-head-author-name (line 94) are not listed in the flaky-tests/uploader.md Full command reference table. The documented optional flags are: --repo-url, --repo-head-sha, --repo-head-branch, --repo-head-commit-epoch. Please either:

   • Verify these flags exist in the CLI and add them to the reference table in flaky-tests/uploader.md, or
   • Remove them from the example and use only documented flags.
     Fix this →

Clarification on the broken link @pat-trunk-io reported: The relative link ../uploader.md#full-command-reference in line 98 is correct for GitBook — the "Full command reference" section exists in flaky-tests/uploader.md. The "Not Found" error was GitHub rendering the relative path as an invalid URL in the review comment sidebar; the actual rendered doc link should resolve correctly.

What looks good:

• Frontmatter, section structure, and logical progression are all solid
• --repo-url, --repo-head-sha, --repo-head-branch are all correctly documented in the CLI reference
• --variant example is accurate
• summary.md entry placement is correct