Skip to content

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

2.7 KB
Raw Blame

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_ID and KNOWLEDGE_WRITER_DOCS_REPOSITORY configure the one writer. writer_settings() in backend/settings.py is 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 of KNOWLEDGE_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_URL and AI_GATEWAY_API_KEY, which the merge check's judge needs.
  • The knowledge_writer_merged_pull_requests webhook consumer and the knowledge-writer-merge-reconcile-schedule Temporal schedule, which start the merge checks.

Stages, in order:

  1. Shadow. Turn on knowledge-writer, the kill switch, and keep knowledge-writer-agent-launch off. Every master merge gets a knowledge_writer verdict event, and intake returns shadow for each needs_docs one instead of starting a run. Before stage 2, check that verdicts arrive for each merge, that reason: merge_check_failed is rare, and that needs_docs verdicts name the right pages.
  2. Launch. Turn on knowledge-writer-agent-launch. A needs_docs verdict starts a writer run that opens a draft pull request on KNOWLEDGE_WRITER_DOCS_REPOSITORY, held to DAILY_RUN_CAP and OPEN_PULL_REQUEST_CAP in backend/logic/caps.py. Check that runs finish with a pushed branch and a draft pull request, that no task carries a knowledge_writer_pull_request_failure state entry, and which WriterCapReached alerts 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.