Read-only workflows: the small feature that ships first

[Silthus]

Part of #68

Question

Ship the smallest read-only mode: a workflow marked as code-managed cannot be edited in the PostHog UI, and the editor says why.

This is the one feature Michael called out as shippable on its own. It builds fresh in product code and merges under the ship target the kickoff grilling set.

Scope, per the provenance ticket's minimum column:

• Backend. The column (or table row) that marks a workflow as code-managed. A permission class with has_object_permission that rejects UI and MCP writes on a code-managed workflow with a 403 whose message names the owner and the way out, and lets the API-key push through. Cover every write action, including the ones that never reach perform_update (the research note lists nine). Generated types regenerated with hogli build:openapi.
• Frontend. A badge on the workflow scene and in the list. The canvas mutation listeners and autosave refuse to fire on a code-managed workflow (the research note's trap: the enable button PATCHes the whole graph, so the guard belongs on the mutations, not the save loader). The save button carries a disabledReason.
• Tests. One backend test per write action that must be blocked, one that shows the push still writes, one frontend test for the guarded mutation. Nothing else.
• Docs. The workflows docs under docs/ gain the read-only state in the same PR.

Proof gate and adversarial review per SHIP.md. Anything that cannot be proved locally is a HITL park, not a merge.

Context

• Research note on research/workflow-read-only-mode, sections 3, 4, and "The minimal 1.1 change".
• Skills: /improving-drf-endpoints, /django-migrations, /writing-ui-components, /adopting-generated-api-types, /writing-tests, /writing-user-facing-copy.

---

Locked by #69

From the kickoff grilling (#69, resolution):

• This is the first upstream PR of the whole effort. Ship authority is granted: a PR against upstream PostHog/posthog, on a branch cut from upstream/master. Nothing merges into this fork's master (it carries fork-only agent docs, which have leaked upstream from a branch cut off it before). This slice goes first because it stands on its own merit to the workflows team without them having to buy the whole idea.
• Read-only means three things, and the block is server-side. A badge, a blocked save enforced in the serializer, and a link back to the source. The refusal carries status, message, why, fix.
• A UI-only block does not count. A code-managed workflow would stay writable through the API and through MCP, and the next push would silently revert a person's edit, which is the worst version of the 2am-hotfix problem rather than an answer to it.
• The editor has no read-only mode today: the only readOnly matches under products/workflows/frontend/Workflows/ are in Reputation/ and templates/TemplateJsonModal.tsx, both unrelated. The disabled-state work is new.
• The link back to the source depends on provenance (#75) storing enough to build one, and the rendering is #78.

---

Locked by #75

The provenance grilling (#75, resolution) settled the storage, the lock and the guard. This ticket ships all of it in one PR.

Scope, exactly.

1. Migration 0026_* against head 0025_hogflow_email_sending_paused_by, five AddField operations on HogFlow, all nullable, no backfill: managed_by ({gui, code}, NULL reads as gui), created_via ({web, api, mcp, wizard, self_driving}), source_repository, source_path, source_ref. All max_length=400, following name (hog_flow.py:140). Define both enums in the workflows product; do not import ExternalDataSourceCreatedVia from products/warehouse_sources/backend/facade/types.py across the product boundary, copy the values.
2. Five serializer fields with help_text, because the text reaches api.schemas.ts and the MCP tool descriptions verbatim. created_via is writable on create and stripped in update() with validated_data.pop("created_via", None) (copying products/warehouse_sources/backend/presentation/views/external_data_source/source_setup.py:360-368); on create, resolve it from get_event_source(request) through an explicit EventSource to CreatedVia map, copying _EVENT_SOURCE_TO_CREATED_VIA (products/data_warehouse/backend/presentation/views/table.py:92), and ignore any claimed value. managed_by stays writable so the release can write it.
3. The guard: override check_object_permissions on HogFlowViewSet, in the shape of external_data_source.py:1768-1772. On a row with managed_by == "code", refuse any write touching DRAFT_CONTENT_FIELDS plus name and description, unless get_event_source(request) is in {EventSource.API, EventSource.CLI}. Allow-list, not deny-list: fail closed so a new EventSource upstream is denied by default. Use get_event_source, not the viewset's existing _is_mcp_request (hog_flow.py:4033), which misses every first-party MCP surface in MCP_TRANSPORT_EVENT_SOURCES.
4. bulk_delete gets its own check, because it is detail=False and never calls get_object(). Delete is refused on a code-managed workflow, single and bulk. The path out is release to gui, archive, delete.
5. status stays writable by everyone, from the editor and from the MCP lifecycle tools, so a person can stop a workflow without a deploy. Add the status-only path to saveWorkflowPartial so the enable button stops sending the whole graph.
6. The managed_by-only release: a PATCH whose body is managed_by alone sets it back to gui. A payload carrying managed_by alongside anything else is refused with code="immutable", not silently stripped.
7. The four-field error: status, message, why, fix, naming the recorded source_repository and source_path. Do not copy the managed-viewset error: it raises a bare serializers.ValidationError (products/data_warehouse/backend/presentation/views/saved_query/editing.py:354-355) that drf-exceptions-hog renders with no why and no fix.
8. canEditWorkflow in workflowLogic, combining code-ownership with workflowUserAccessLevel. This also closes a bug that exists today: the canvas never reads the access level, so a Viewer gets a fully interactive canvas and the autosave fires a real PATCH that only the backend rejects.
9. The badge, plus the regenerated products/workflows/frontend/generated/ files. Those come from hogli build:openapi-schema then the orval step in frontend/bin/generate-openapi-types.mjs; a serializer field does not reach the UI types until that runs, so the regenerated files belong in this diff.
10. Amend the comment at posthog/event_usage.py:472-476, which currently asserts that mis-declaring as the CLI "buys no extra write latitude". This guard makes that false. It is not an escalation (the UA needs a key that already holds hog_flow:write), but the sentence is an invariant a reviewer maintains, so correct it here and say why.

Not in scope. Nothing writes source_repository, source_path or source_ref yet: the CLI tickets do that, along with --allow-move and the path comparison. The columns ship null for every row, exactly as created_via did on ExternalDataSource. The source link is composed in #78; this ticket ships the fields and the badge. Per-revision git state is #77; HogFlowRevision is untouched here. HogFlowFilterSet.Meta.fields gains key from #72, not from this ticket.

Named cost to document: a push can re-enable what a person disabled, because status lives in the source (#69 decision 7) and stays UI-writable.

[Silthus]

Claimed by worker wf68-76-read-only-implement (Claude Code background agent, cast opus). CodeRabbit slot 1. Branch feat/workflows-code-managed-read-only cut from upstream/master.

[Silthus]

Decision entailed by #75: the guard keys on the action and the payload shape, not on field names

Folded in from the revisions grilling (#77), before implementation rather than at review.

The hole. The #75 spec refuses a write that "touches DRAFT_CONTENT_FIELDS plus name and description". Five write actions carry bodies that name none of those fields: restore_revision ({overwrite, expected_draft_updated_at}), publish ({confirm, confirm_token}), graph, action_email and discard_draft. A field-based check passes all five, and restore_revision plus publish together replace the live definition of a code-managed workflow from the editor. Same class of hole #75 already caught for bulk_delete.

The rule implemented instead. On a row with managed_by == "code", a request whose get_event_source is not in {EventSource.API, EventSource.CLI} may do exactly two things:

1. PATCH with status alone (decision 5: a person can stop a workflow without a deploy).
2. PATCH with managed_by alone (decision 3: the release back to gui).

Every other write on that row is refused with the four-field error: update/partial_update carrying anything else, destroy, bulk_delete, graph, action_email, publish, discard_draft, restore_revision, and any write action added upstream later, because the allow-list is on the action and the payload shape rather than on a set of field names. This is the same fail-closed reasoning #75 used for EventSource.

Named cost, to state in the docs and the PR. The allow-list also refuses the runtime write actions on a code-managed workflow from the UI: rerun, invocations, batch_jobs and schedules. That is the price of fail-closed. The path out is unchanged and is three steps: release to gui, then act, then let the next push re-claim it. Widening the allow-list to the run actions is additive and needs no migration, so it can follow once someone asks.

Tests: one blocked-write test per action in that list, plus the API-key push, the status-only path and the release rule.

[Silthus]

Proof bundle

Branch feat/workflows-code-managed-read-only, cut from upstream/master at cea129a217b. One commit, 904e4985bfe, SSH-signed.

Red: the new tests fail without the change

Run in a throwaway worktree at upstream/master carrying only the model, the migration and the new tests, so the guard itself is absent. 17 of 20 backend cases fail. The 3 that pass are the two status-only cases and the API-key push, which must stay green either way, so they prove the guard adds no refusal of its own to those paths.

FAILED test_hog_flow_code_managed.py::TestCodeManagedHogFlow::test_a_gui_workflow_cannot_claim_code_ownership_from_the_web
FAILED ...::test_agent_and_spoofed_cli_writes_are_refused_0_mcp_transport
FAILED ...::test_agent_and_spoofed_cli_writes_are_refused_1_cli_user_agent_from_the_browser
FAILED ...::test_agent_and_spoofed_cli_writes_are_refused_2_cli_consumer_header_from_the_browser
FAILED ...::test_bulk_delete_is_refused
FAILED ...::test_managed_by_alone_releases_the_workflow_and_a_mixed_payload_is_refused
FAILED ...::test_refusal_names_the_recorded_source_and_the_way_out
FAILED ...::test_web_write_is_refused_0_update_content
FAILED ...::test_web_write_is_refused_1_update_name
FAILED ...::test_web_write_is_refused_2_update_description
FAILED ...::test_web_write_is_refused_3_update_status_and_content
FAILED ...::test_web_write_is_refused_4_destroy
FAILED ...::test_web_write_is_refused_5_graph
FAILED ...::test_web_write_is_refused_6_action_email
FAILED ...::test_web_write_is_refused_7_publish
FAILED ...::test_web_write_is_refused_8_discard_draft
FAILED ...::test_web_write_is_refused_9_restore_revision
======================== 17 failed, 3 passed in 14.76s =========================

Sample failure, the plain content write that the whole ticket exists to stop:

E  AssertionError: assert 200 == 403

Frontend, same worktree, the new case alone:

● workflowLogic auto-save › a workflow managed by code › refuses a canvas mutation, so nothing is edited and nothing is saved

  expect(received).toBe(expected) // Object.is equality
  Expected: false
  Received: undefined

  > 105 |             expect(logic.values.canEditWorkflow).toBe(false)
Tests:       1 failed, 29 skipped, 30 total

Green: after the change

products/workflows/backend/api/test/test_hog_flow_code_managed.py
============================= 20 passed in 10.23s ==============================

pnpm --filter=@posthog/frontend exec jest products/workflows/frontend/Workflows
Test Suites: 50 passed, 50 total
Tests:       828 passed, 828 total

No regression in the suites that cover the paths this change touches:

Suite	Result
products/workflows/backend/api/test/test_hog_flow.py	407 passed
test_hog_flow_draft_publish.py, test_hog_flow_revisions.py, test_hog_flow_access_control.py, test_hog_flow_action_email.py	108 passed
products/workflows/frontend/Workflows (jest)	828 passed

The repo's own gates

hogli ci:preflight --strict
summary {"changed_files": 3302, "triggered": [...18 checks...], "failures": 0, "mode": "strict"}

• uv run mypy --cache-fine-grained . (repo-wide): No issues found
• pnpm --filter=@posthog/frontend typescript:check: No errors reported by tsgo
• ruff check . --fix and ruff format .: clean
• semgrep --config .semgrep/rules/security/ over the three changed Python files: 0 findings, 29 rules
• hogli build:openapi ran; the regenerated products/workflows/frontend/generated/ and services/mcp/ files are in the commit

Screenshots

Rendered from a new Storybook story, Products/Workflows/Code managed tag.

The badge beside the workflow name, with the save button refusing and saying why:

The tooltip, which names the recorded file:

The badge before a push has recorded a source, which is what every row looks like until the CLI lands:

Two disclosures

• The screenshots live on the orphan branch pr-assets-workflows-read-only on this fork. hogli pr:upload-image needs employee access this session does not have. That orphan commit carries four PNGs and no code, and it was made with --no-verify because the commit hook cannot run against an orphan tree. No hook was bypassed on the code branch or on any push.
• The docs bullet landed in products/workflows/CONTRIBUTING.md rather than under docs/. There is no workflows doc under docs/ that covers editing or ownership (the four that exist cover email tiers, auto-pause, batch audience resolution and AI task limits), and the repo rule is to update an existing doc rather than add a new one.

[Silthus]

Adversarial review: 21 findings, 4 changed the code

One fresh general-purpose agent, cast opus, read the full diff and the proof bundle with a brief to break it. It ran its own probes against the live stack rather than reasoning from the code alone, which is how the first finding surfaced.

Fixed before the PR opened

1. The release rule refused every ordinary save. _validate_managed_by_release keyed on the presence of managed_by, and the editor seeds its form from the whole GET response and spreads it into every save. A plain rename on any workflow, code-managed or not, came back 400 immutable. Proved with a pytest probe. Fixed twice over: the rule now refuses only a payload that would move the lock, and the editor strips provenance from the payload it sends. Covered by two new tests.
2. An agent could declare itself the CLI through the MCP server. services/mcp forwards a caller-supplied x-posthog-mcp-consumer verbatim with no allow-list, and get_event_source honors posthog-cli there with no first-party gate. An MCP request carries a bearer token, so the session check did not catch it. is_code_managed_writer now refuses the MCP transport outright, whatever the request calls itself. New test.
3. Every operational action was refused along with the content writes. rerun, invocations, run, cancel_invocations, batch_jobs, cancel_batch_job and resume_email_sending all returned 403. The sharpest is resume_email_sending: PostHog's own detector applies that pause and the endpoint is the only way out of it, so a code-managed workflow could be paused by us and un-resumable by the customer. Those seven are now allowed, because operating a workflow is not defining it. schedules and schedule_detail stay refused: a schedule is part of the trigger, and the trigger is in the file. New tests on both sides of that line.
4. The three source fields could be claimed by anyone with hog_flow:write. They are rendered back to the reader in the refusal, in the tooltip, and later as a link, so a browser session could put someone else's repository name in front of a user. Now gated behind the same writer check, with an unchanged value allowed. New test.

Also fixed from the same pass: the MCP tools no longer offer managed_by or the source fields (exclude_params), so an agent cannot release a workflow and then edit it in two calls; created_via moved to callable choices per the repo's growing-enum rule; the admin shows the five columns read-only; the duplicate path strips them (found and fixed independently, just before the review landed).

Accepted with a reason

• A personal API key writes a code-managed workflow. EventSource.API is get_event_source's fallback, so the allow-list's default answer for a programmatic caller is yes. This is Provenance: a workflow records whether code, the UI, or MCP owns it #75 decision 4 as written, and it is what lets a CI push on a plain key work at all. The lock reorders which client may write the row; it is not a defense against a credential that already holds hog_flow:write. A dedicated scope would make it one, and that is a platform change. Stated in the PR body rather than hidden.
• The editor's panel inputs still accept typing. setWorkflowValue is a kea-forms action whose reducer applies the value before the listener runs, so a step config still changes on screen, never saves, and reverts on reload. Disabling every panel control is the UI pass How a code-managed workflow renders in the PostHog UI #78 owns; this ticket's ten items cover the mutation listeners, the auto-save and the save button, and nothing persists either way.
• Internal writers bypass the lock. Management commands, Celery tasks and the Django admin write the row directly. Gating them is a different question from "the editor must not fight a push". Written into the docs and surfaced in the admin.
• max_length=400 on the two enum columns. Provenance: a workflow records whether code, the UI, or MCP owns it #75 fixed this explicitly. A wider varchar costs nothing in Postgres.
• update (PUT) in the action allow-list is unreachable for a status-only body, because field validation rejects it first. Kept, so the rule does not silently change if that validation does.
• Archive is inside the status-only escape hatch. That follows from Kickoff: lock the frame for a shippable v1 #69 decision 7, and the docs now say so.

Could not break

The reviewer tried and failed on: migration safety (five nullable AddFields, metadata-only, no non-Django writer of the column list), coverage of every detail write action through get_object(), revision and draft snapshots carrying managed_by back in, session spoofing from a browser, created_via spoofing, the error envelope shape, case and query-param smuggling, and the new-workflow and template-edit paths staying editable.

[Silthus]

Parked: the PR is open upstream and needs a human

PR: PostHog#103540 (draft, Silthus:feat/workflows-code-managed-read-only into PostHog/posthog:master, cut from upstream/master at cea129a217b).

Decisions locked so far

The ten items of the #75 scope all ship, plus the guard shape the conductor folded in mid-flight (#76 (comment)) and four changes the adversarial review forced (#76 (comment)).

Three decisions I made that depart from the plan, each because the plan did not survive contact with the code:

1. created_via is read-only on the serializer, not writable-and-stripped. The value is resolved from the request either way, so a writable field could only ever be ignored. The ExternalDataSource pattern exists because its settings page spreads a GET payload into a PATCH; nothing in workflows does that for this field.
2. The guard keys on the action and the payload shape, not on DRAFT_CONTENT_FIELDS. This is the conductor's correction, and the review confirmed the hole was real.
3. The operational actions are allowed. Fail-closed over every write took resume_email_sending away from a customer whose workflow PostHog had paused. The allow-list stays explicit and an action added later is still refused by default.

Proof bundle: #76 (comment) (red run, green run, preflight, screenshots). Re-run after the review changes, on 2001c4b40e7:

Gate	Result
test_hog_flow_code_managed.py	28 passed
the four workflows API suites plus the admin test	520 passed
products/workflows/frontend (jest)	860 passed
pnpm --filter=@posthog/frontend typescript:check	clean
uv run mypy --cache-fine-grained .	No issues found
semgrep --config .semgrep/rules/security/	0 findings
hogli ci:preflight --strict (also on push)	0 failures
manage.py analyze_migration_risk	workflows.0026_* = Safe

Two things the bundle does not contain, both stated in the PR body: no manual pass in a running app, and no CodeRabbit CLI pass. The CLI is installed but signed out, and signing in opens a browser tab a background session cannot use.

Pending for the human

One item: upstream review and merge of PostHog#103540.

What Michael needs to do:

1. Approve the CI runs. A fork PR sits at action_required until a maintainer approves the workflows, so nothing runs until then. Nine checks are registered and none has started.
2. Mark it ready for review when CI is green. It opened as a draft, which is the repo's default and runs a narrower matrix.
3. Answer the reviewer on the three judgment calls if they come up: the operational-action allow-list (the workflows team may want schedules in or resume_email_sending out), the fact that a personal API key writes a code-managed row by design, and whether the products/workflows/CONTRIBUTING.md section is the right home for the docs (no workflows doc under docs/ covers editing or ownership).
4. Nothing to merge from here. The Trunk queue and the required approval belong to PostHog maintainers, and an agent must not enqueue it.

Assignment: the PR could not be assigned to @Silthus, because an outside contributor cannot set an assignee on that repository. The DRI is named in the body instead.

The ticket closes on the merged commit. Ping this worker when a reviewer asks for changes.

[Silthus]

Review round one: pushed, head is e20b93523cb

The CodeRabbit major finding and a second adversarial review are folded in, on top of 2001c4b40e7. One commit, SSH-signed, pushed to feat/workflows-code-managed-read-only.

Proof on the new head, with the command table and the diff since the reviewed commit: PostHog#103540 (comment)

What changed:

• Publish, Discard draft, Restore as draft and the schedule flush all reached a 403 from a live control on a code-managed workflow. All four now read workflowEditDisabledReason.
• A push could not re-claim a released workflow in one write, because the release rule ran for every caller. The client that may write the row is now exempt.
• One MCP classifier instead of two: _is_mcp_request is gone and every call site reads is_mcp_transport_request.
• The delete tooltip no longer tells the reader to use a control this PR does not ship.
• Comment, docs and test trims, no behavior change.

Still open for a human: the upstream review and merge, unchanged from the earlier parking note. The operational allow-list was left alone on purpose.

[Silthus]

Review round two: head is 7c6077d6110

CodeRabbit re-reviewed e20b93523cb and left one new Major, a TOCTOU between the ownership check and the later row lock (CWE-367). Verified against the code and fixed rather than accepted, because every mutating path already took the lock and only had to ask the question again on the locked row.

• _refuse_if_code_managed now carries the decision, and the six locked paths call it after select_for_update(): perform_update, graph, action_email, publish, discard_draft, restore_revision.
• bulk_delete reads managed_by from the rows it locks and refuses the whole request the same way.
• One test, proved red with the perform_update re-check removed.

Accepted and stated on the PR rather than fixed: the single destroy path takes no row lock, so that window stays open. Closing it means adding locking this PR does not otherwise need, and it sits under the limit the PR body already states, that the lock reorders which client may write the row and is not a credential boundary.

Proof on the new head: PostHog#103540 (comment)
Reply to the reviewer: PostHog#103540 (comment)

The PR stays a draft. Still open for a human: the upstream review and merge.