Expand impacted targets API recipe and gotchas

[samgutentag]

Summary

• Adds a "Reading testing details" section to parallel-queues/api.mdx documenting the impactedTargets vs impactedTargetsForTestedPrs distinction in /getMergeQueueTestingDetails responses and the testRunId derivation from the trunk-merge/pr-N/UUID branch name.
• Adds a "Recipes and gotchas" section covering: filtering CI triggers to skip trunk-merge/* branches, the "ALL" keyword does NOT short-circuit other PRs' impact matching, last-upload-wins per head SHA, and the bazel-diff reuse pattern between PR and MQ jobs.
• Flags the documented 20 MiB request body limit vs ~10 MB cited in customer threads as a discrepancy worth verifying with Trunk support before relying on headroom.

Why

Sourced from customer feedback mining (cluster impacted-targets-api-discovery, verdict partial, 13 pairs across 6 customers). Recurring API integration questions: testRunId derivation, impactedTargets vs impactedTargetsForTestedPrs, the ALL keyword footgun, the trunk-merge/* CI-filter requirement, bazel-diff reuse, and the upload size limit (which has a documentation discrepancy worth verifying).

Items flagged for review

• 10 MB vs 20 MiB size limit discrepancy. The API reference (merge-queue/reference/merge.mdx) and the existing Warning in that file cite 20 MiB. Engineering has cited ~10 MB in customer threads (see trunk-appliedintuition thread). I added an <Info> callout flagging both numbers rather than picking one — confirm the actual current limit and replace the callout with a single authoritative number.
• testRunId field name. The cluster source describes the UUID in trunk-merge/pr-X/UUID as "the testRunId", but I could not find testRunId already mentioned in docs2. Verify that the field is actually named testRunId in /getMergeQueueTestingDetails responses (vs testId, runId, etc.) before merging.
• impactedTargetsForTestedPrs field name. Same as above — confirm exact field casing/spelling in the live API response. The cluster examples use this exact name, but I have not seen it in an OpenAPI spec inside this repo.
• trunk-temp/** in the branches-ignore example. I included trunk-temp/** alongside trunk-merge/** because docs2 elsewhere mentions trunk-temp/* as a precursor branch (see merge-queue/reference/common-problems.mdx). The cluster only explicitly called out trunk-merge/*. If trunk-temp/* never reaches the impacted-targets workflow trigger (it gets renamed before push), drop it from the example.

Customer signal

• Cluster: impacted-targets-api-discovery (verdict: partial, 13 pairs / 6 customers)
• Channels: trunk-faire, trunk-appliedintuition, trunk-agencyanalytics, trunk-perplexity
• Source threads (full list in findings/clusters/impacted-targets-api-discovery.json):
  • testRunId derivation
  • impactedTargets vs impactedTargetsForTestedPrs
  • upload size limit
  • ALL keyword semantics
  • trunk-merge/* CI filter requirement
  • bazel-diff reuse
  • last-upload-wins per SHA

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
trunk	🟢 Ready	View Preview	May 20, 2026, 11:01 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[samgutentag]

Verification status (2026-05-20): unknown

Could not determine state from available signals. Manual check needed.

• Eng PR: none referenced in PR body
• Flag: n/a (no eng work to verify)
• Signals checked:
  • No trunk-io/<repo>#NNN or PR URL references in PR body
  • No TRUNK-XXX Linear ticket linked
  • PR scope is content (documenting existing impacted-targets API behavior), not a flag-gated new feature

This is a content-accuracy PR, not a feature-rollout PR, so the usual flag/staging signals don't apply. The four "items flagged for review" in the PR body (20 MiB vs 10 MB upload limit, testRunId field name, impactedTargetsForTestedPrs field name, trunk-temp/** behavior in branches-ignore) are the real review blockers and need direct confirmation from engineering before merge.

[samgutentag]

Code verification (2026-05-21): 4 confirmed / 0 contradicted / 0 ambiguous / 0 unverifiable

Claim	Verdict	Source
Upload body limit is 20 MB	confirmed (after fix)	constants.ts:1
testRunId field on /getMergeQueueTestingDetails	confirmed	schema.ts:155
impactedTargetsForTestedPrs field on same endpoint	confirmed	schema.ts:269-280
trunk-temp/** is a real CI-triggerable branch	confirmed (defensive entry, valid)	utils/index.ts:939-964

Initial verification surfaced one contradiction: the page said "20 MiB" (with a hedge against a "10 MB" customer-thread figure), but source says express.json({ limit: "20mb" }) which is base-10 MB, not MiB. Resolved in commit 4caa0f3: the <Info> callout now states the limit as 20 MB definitively.

---

Source #1 — Upload body limit (confirmed after fix)

File: trunk-io/trunk/trunk/services/public-api/src/constants.ts#L1

export const EXPRESS_JSON_LIMIT = "20mb"; // https://expressjs.com/en/api.html

Adjacent usage in http_server.ts#L273:

this.app.use(express.json({ limit: EXPRESS_JSON_LIMIT })); // allow payloads of 20mb, or ~400k targets

Reasoning: The bytes npm package (used by Express to parse the limit option) treats "20mb" as 20 × 10⁶ bytes (20 MB, base-10), not 20 × 2²⁰ (MiB). The "~10 MB" figure cited in customer support threads traces to test-harness mocks in merge-action/bazel-action (their local express.json({ limit: "10mb" })), not the prod constant. The page now states 20 MB without a hedge.

Source #2 — testRunId field (confirmed)

File: trunk-io/trunk/trunk/services/public-api/src/schema.ts#L155

testRunId: z.string({
  description:
    "The ID of the test run. This is the last section of the names of the branches Merge Queue creates for testing (eg, for `trunk-merge/pr-1815/5df78918-4654-40a0-822a-313f540ea0be`, the ID is `5df78918-4654-40a0-822a-313f540ea0be`",
}),

Reasoning: The field name is exactly testRunId (camelCase). The Zod schema's own .describe() documents the same UUID-derivation rule the PR explains: last segment of the trunk-merge/pr-N/UUID branch name. The PR's wording matches the source description verbatim, so the docs are self-consistent with the API contract.

Source #3 — impactedTargetsForTestedPrs field (confirmed)

File: trunk-io/trunk/trunk/services/public-api/src/schema.ts#L269-L280

impactedTargets: z.array(z.string()).optional()
  .describe("..."),
impactedTargetsForTestedPrs: z.array(z.string()).optional()
  .describe("The impacted build/test targets for only the PRs being tested in this run (i.e. `testedPullRequests`), excluding any dependent PRs. Only present when impacted targets are being uploaded for the repository.")

Reasoning: Both fields exist on GET_MERGE_QUEUE_TESTING_DETAILS_RESPONSE_SCHEMA with exactly the casing the PR uses. The schema's description of impactedTargetsForTestedPrs ("for only the PRs being tested in this run, excluding any dependent PRs") aligns with the PR's contrast against the broader impactedTargets field (which also includes upstream PRs in the batch). The PR explains the distinction correctly.

Source #4 — trunk-temp/** branch behavior (confirmed)

File: trunk-io/trunk/trunk/services/merge/src/controller/utils/index.ts#L939

const TEMP_BRANCH_NAME_PREFIX = "trunk-temp/";

Cross-referenced in docs2 itself at merge-queue/reference/common-problems.mdx:

"you should configure your CI to completely ignore trunk-temp/* branches. Running workflows on them will only create unnecessary or canceled builds. The trunk-temp/* branch is a temporary, intermediate branch that the merge queue uses to assemble the necessary commits for a test run. Once the build is prepared, this branch is immediately renamed to a trunk-merge/* branch."

Reasoning: trunk-temp/* is a real branch that gets pushed to the remote before being renamed to trunk-merge/*. Existing docs2 self-confirms it can trigger CI workflows (which is why other docs2 pages already recommend ignoring it). Including trunk-temp/** in the branches-ignore example is correct and defensible. This is a behavioral claim (does this branch fire the workflow?), not just a string-existence check — the branch exists and lands on the remote before rename.