: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.
Knowledge writer
An internal tool for now: it opens posthog.com docs pull requests for changes merged into PostHog repositories, and runs in one PostHog project per deployment.
KNOWLEDGE_WRITER_TEAM_ID,KNOWLEDGE_WRITER_USER_IDandKNOWLEDGE_WRITER_DOCS_REPOSITORYconfigure the one writer.writer_settings()inbackend/settings.pyis their only reader, and nothing runs while any of them is unset.- Turning it into a customer feature means replacing
writer_settings()with a team-scoped model and triggering from the GitHub App webhook, since a customer can't add a workflow and a secret to every repository.
Rollout
Every gate below fails closed without an error, so a missing one looks like a quiet day of merges rather than a failure. Check each one before reading silence as "no docs needed".
Production needs, before any stage:
- The settings in the first bullet above, for the writer team.
- A GitHub integration on the writer team for each repository owner it touches:
PostHog, to read merges, and the owner ofKNOWLEDGE_WRITER_DOCS_REPOSITORY, to publish. backend/README.md covers how one is picked. GITHUB_APP_SLUG, without which no open docs pull request counts as the writer's, so joining and the open pull request cap stop working.AI_GATEWAY_URLandAI_GATEWAY_API_KEY, which the merge check's judge needs.- The
knowledge_writer_merged_pull_requestswebhook consumer and theknowledge-writer-merge-reconcile-scheduleTemporal schedule, which start the merge checks.
Stages, in order:
- Shadow. Turn on
knowledge-writer, the kill switch, and keepknowledge-writer-agent-launchoff. Everymastermerge gets aknowledge_writer verdictevent, and intake returnsshadowfor eachneeds_docsone instead of starting a run. Before stage 2, check that verdicts arrive for each merge, thatreason: merge_check_failedis rare, and thatneeds_docsverdicts name the right pages. - Launch. Turn on
knowledge-writer-agent-launch. Aneeds_docsverdict starts a writer run that opens a draft pull request onKNOWLEDGE_WRITER_DOCS_REPOSITORY, held toDAILY_RUN_CAPandOPEN_PULL_REQUEST_CAPinbackend/logic/caps.py. Check that runs finish with a pushed branch and a draft pull request, that no task carries aknowledge_writer_pull_request_failurestate entry, and whichWriterCapReachedalerts error tracking shows.
To back out, turn off knowledge-writer-agent-launch to stop new runs, which still lets runs already going open their pull requests.
Turn off knowledge-writer to stop everything, publishing included.