:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Engineering analytics: read the contract before designing
This is an isolated product with an explicit, locked engineering contract. Before designing or changing anything here, read both in full; don't re-derive what's already decided (you'll get it subtly wrong):
For any frontend change in this product, also read frontend/AGENTS.md: the scope-panel rule (picker-bound content inside the outlined panel, current-state content outside), the single comparison vocabulary, and the table conventions.
The decision most often re-derived wrong: CI ↔ PR linkage is by PR number (the run's pull_requests association), never head SHA.
A head-SHA join silently drops every push but the latest, because the github_pull_requests snapshot keeps only the current head.
See SPEC §6 (Locked decisions).
head SHA is a per-commit precision key only; head_branch is the capture-time / fork fallback.
Two sanctioned exceptions, so you don't "fix" either back:
commit_pr_numberjoins a default-branch run'shead_shato a merged PR'smerge_commit_sha. That is a different key from the banned one: terminal and immutable after merge, one commit per PR, so it drops nothing. It stays correct only while gated onmerged_at(open PRs carry a throwaway test-merge SHA) and deduped to one row per SHA (a raw join fans a run row out and multiplies downstream counts).- A merge-queue gate run takes its
pr_numberfrom its own branch name (trunk-merge/pr-<n>/…), not from itspull_requestsassociation. The association is present but names the throwaway PR the queue opened, not the PR being landed. The branch name is immutable for the branch's life and names exactly one PR, so it carries none of the ambiguity the head-SHA ban is about. Defined once inlogic/merge_queue.py; see SPEC §6.