: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.
Workflows review rules
These are the judgement calls that reviewers of Workflows code catch again and again, and that no lint or test enforces yet. Each rule names the failure it prevents and one PR where a reviewer caught it.
When a review catches a problem that a rule here would have named, sharpen that rule. When it catches a new kind of problem twice, add a rule. When a lint, a type, or a test can enforce a rule, add that check and delete the rule.
Sends and retries
- Make every send and enqueue safe to replay. Derive ids from stable keys, such as the invocation id and the action id, never a fresh UUID, and check the row count of a lock-guarded update. A replayed batch, a reassigned lock, or a redelivered webhook otherwise sends the same message twice (#54418, #65864).
- Give every retry loop an attempt cap and a terminal state. A record that can never succeed otherwise retries forever and blocks the queue behind it (#65864, #100830).
- Check suppression, opt-out, frequency caps, and rate limits on every send path, before any other side effect. A suppressed or capped recipient otherwise still gets the message, and a test run must not change the counters of real recipients (#71038).
Failures
- Fail loudly on bad configuration and unprocessable input. Crash at startup, reject at validation, or log with a metric; never skip, return null, or warn and continue. A step that fails silently looks healthy while its messages are dropped or go out without their credential (#72913, #58997).
- Ship a new failure counter or fallback path with its alert, and log the workflow and the action with each failure.
Keep metric labels bounded, such as
kind="transient"orkind="logical", never workflow or action ids. Separate transient errors from real ones, so the alert neither stays silent nor pages on a blip (#57847, #60447).
Saving workflows
- Validate workflows in the serializer, so API and MCP callers get the checks the UI has. A save that the UI blocks but the API accepts gives an active workflow that never runs (#117704).
- Check a new validation rule against the workflows already saved, and accept the parts a save does not change. A stricter rule otherwise makes existing workflows impossible to edit (#63583, #83800).
- Change a rule, an enum, or a list in every copy in the same PR, or derive one copy from the other. The Python and Node sides, and the editor and the backend, drift otherwise, and a step works in one and fails in the other (#88404, #114369).
Secrets and data
- Never write a masked secret back, and mask every secret input type wherever it is serialized. That includes API responses, activity logs, revision snapshots, and HogVM output. A save of a masked value otherwise wipes the stored credential, and an unmasked one leaks into logs (#72913, #83804).
- Declare every custom DRF
@actioninscope_object_read_actionsorscope_object_write_actions, with scopes that fit the data it returns. Recipient emails are person data. An undeclared action is unreachable for API keys and MCP, or exposes data under too weak a scope (#61001, #81483). - Capture events for a person with a distinct id, never with
person.id.person.idis the person UUID, and capturing with it creates a new, empty person (#60647).