docs(ci): document the CI tab, the PR CI view, and span ingestion

[EliSchleifer]

Adds a top-level CI tab to the docs, covering the two places the CI product shows up in the app and how to get data into it.

Page	Covers
ci/index	What Trunk CI is, the provider→Trunk concept mapping, 90-day retention
ci/get-started/index	The two shared prerequisites: repo connected, CI Intelligence on
ci/get-started/github-actions	No-pipeline-change setup, job-key identity, the "Other checks" quirk
ci/get-started/buildkite	Notification-service + agent OTLP export, token, troubleshooting
ci/pull-requests	PR list CI column, attempt picker, CI / Activity / Dynamic CI tabs
ci/ci-tab	Jobs list, job detail, Overview, In flight
ci/commit-traces	The waterfall

Decisions worth reviewing

A new top-level tab, not a group inside an existing one. The product is its own top-navbar tab in the app, and mirroring that keeps the docs navigable by someone looking at the app. Folding it into the Dynamic CI tab was the alternative, and it's wrong: the two products are deliberately decoupled flags (showCiDashboard vs showDynamicCI), so an org can have either without the other. Putting them under one tab would imply otherwise. It sits immediately before Dynamic CI so the two CI products are adjacent.

Public, not group-gated. Dynamic CI's page carries groups: ["dynamic-ci"] and is served only to readers whose docs JWT lists it. Gating these the same way would need a companion trunk2 PR — docsGroupsForSession in mintlify-docs.ts only ever emits dynamic-ci today, and reusing that group would show CI docs to exactly the wrong set of orgs. Shipping public avoids a cross-repo dependency for docs that describe a product customers are already being onboarded onto. Easy to gate later if that's wrong.

commit-traces is its own page rather than duplicated prose. The waterfall is literally one view with two hosts (the PR detail CI tab and the CI tab's job history), so describing it twice would guarantee drift. Both pages link to it.

Definitions are stated, because the numbers are not self-evident. Pass rate excludes cancelled and skipped from both halves; run count includes zero-duration runs while duration percentiles cannot. That asymmetry is visible in the UI (a duration chart's count sits below the run count) and reads as a bug unless the docs say why.

Scope. Failures, Monitors, Logs, Pricing and Kiln sub-tabs are deliberately left out — Failures renders empty in production today and Logs is a placeholder. A reader will see tabs these docs don't mention; worth a follow-up once those are real.

Two things I could not confirm

The Buildkite ingest host. I published https://api.trunk.io/v2/ci/buildkite. The route is mounted on publicApiDomain, but per ADR-0013 only private.api.<domain> has a CloudFront origin today and the apex is a later cutover. Both hosts return 403 to an unauthenticated POST, which proves the edge is enforcing but not which host external callers should be given. If the apex isn't live for customers yet, this one string needs changing (ci/get-started/buildkite.mdx, two occurrences).

Buildkite's own UI labels. CONTRIBUTING.md asks that nav paths be walked in the live product. I verified Settings → Notification Services and the --opentelemetry-tracing agent flag against Buildkite's current docs, not their UI. Someone with a Buildkite org admin seat should confirm the OpenTelemetry Tracing service name and the URL/Headers field labels.

Separately and not fixed here: docs/trd/ci-data-ingestion/per-provider-ingestion.md in trunk2 still says the agent flag is --tracing-backend opentelemetry. Buildkite's current docs and the comment in handlers.rs both say --opentelemetry-tracing. Docs here use the current flag; the TRD needs its own fix.

Screenshots

Eight <Frame> slots are in place pointing at /assets/ci/…, currently unfilled:

• get-started/ci-intelligence-toggle.png — Settings → Repositories, CI Intelligence column
• get-started/org-api-token.png — Settings → Organization → General, API Token row
• pull-requests/pr-list.png — the /pulls table with CI + merge-queue columns
• pull-requests/pr-detail.png — PR detail with attempt picker and CI tab
• ci-tab/jobs-list.png — Jobs index with repo picker
• ci-tab/job-detail.png — job page stat strip + pass/fail chart
• ci-tab/overview.png — in-flight boxes + concurrency chart
• commit-traces/waterfall.png — a trace with several workflow lanes and visible queue stripes

Don't merge before these land — the pages render broken images until they do.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated
trunk	🟢 Ready	View Preview	Sep 18, 2026, 7:28 AM