windmill/docs/fork-triggers.md

Triggers and schedules in workspace forks

A workspace fork is a developer-controlled copy of a parent workspace, used to test changes before merging back via git sync. Triggers and schedules in a fork need special handling for two reasons:

1. Listener take-over: most trigger kinds (Kafka, Postgres, MQTT, NATS, SQS, GCP, Azure) attach to a stateful upstream resource. Two listeners sharing the same identifier compete for events.
2. Merge round-trip: every change made in a fork can flow back to the parent through git sync. If the fork sets a trigger to disabled, that value would otherwise overwrite the parent's enabled state on merge.

Cloning model — always cloned, always disabled

Fork creation always runs clone_triggers_and_schedules. Every row in each *_trigger table and in schedule is copied from the parent into the fork with two invariants:

• Always disabled. The clone forces mode='disabled'::TRIGGER_MODE on triggers and enabled=false on schedules, regardless of the parent's state. Disabled rows have no side effects — no listener attaches to the upstream, no cron fires — so this clone is safe by construction. The user re-enables manually in the fork.
• Listener identifiers copied verbatim. Stored values for group_id, replication_slot_name, subscription_name, client_id, consumer_name, etc. are copied 1:1. Until the runtime-suffix work ships (see below), enabling a cloned listener in the fork would compete with the parent — the conflict warning below catches that case.

native_trigger (Nextcloud, Google Drive, GitHub) is intentionally not cloned. Those triggers manage external webhook state we don't want duplicated.

Non-workspaced HTTP triggers are also skipped. A row with workspaced_route=false (and where neither CLOUD_HOSTED nor the HTTP_ROUTE_WORKSPACED_ROUTE instance setting is on) has a runtime URL without any workspace prefix. A clone would collide with the parent's row at the matchit router level, where duplicate inserts are silently dropped — one trigger would invisibly hijack the other. There is no namespacing escape hatch for these (the whole point of workspaced_route=false is to skip the prefix), so the clone filter excludes them. The fork user can re-create one manually if they need it. When CLOUD_HOSTED or HTTP_ROUTE_WORKSPACED_ROUTE is on, every route is workspace-prefixed at runtime regardless of the column, and the clone copies all rows.

Non-workspaced email triggers are skipped on the same grounds. A row with workspaced_local_part=false exposes a bare local_part@domain address shared instance-wide; a clone would share the address with the parent and incoming mail would be delivered arbitrarily. The clone filter copies email triggers only when workspaced_local_part IS TRUE (or CLOUD_HOSTED, since cloud scopes email lookup by workspace_id natively).

Operational state is owned by the parent

The rule that makes both the normal-git PR merge and the in-app merge behave:

A trigger's mode (and a schedule's enabled) belongs to the parent workspace. Git-sync reads the parent's value into a fork's synced file and never writes a fork's value back. No git-sync / merge / create / update write sets a fork's operational state; the setmode / setenabled endpoint is the intended explicit mutator.

(Runtime error handling can still auto-disable an errored trigger or schedule — that's orthogonal to this rule, which governs git-sync/merge/create/update writes.)

This is enforced in two halves, keyed off parent_workspace_id IS NOT NULL (the column, not the wm-fork-* naming convention — it stays consistent with the conflict-warning gates and survives any future ID rename):

Read half — parent-value substitution on export. When the source workspace is a fork, the tarball export at /api/w/{workspace}/workspaces/tarball rewrites each trigger's mode (and each schedule's enabled) to the parent's value for the same path, looked up at export time. A fork-only path (absent from the parent) keeps the fork's own value — there's no parent state to defer to, so it lands with whatever the fork creator set.

The earlier design stripped these fields instead. That broke a normal-git PR merge: the parent branch (and the merge base) carries the line, the fork branch dropped it, so the 3-way merge either silently deleted mode/enabled from the parent — corrupting the source of truth — or conflicted outright when the parent had also edited it. Substituting the parent's value makes the fork's file byte-identical to the parent on that field, so the merge has nothing to resolve.

Write half — fork writes never set operational state. A write into a fork (git-sync push, merge deploy, clone, or a plain UI create) must not set the state, otherwise pulling the substituted parent value straight back into the fork would re-enable it. So create_trigger/create_schedule force disabled for a fork target, and update_trigger preserves the fork's existing mode (workspace_is_fork in windmill-trigger/src/handler.rs; schedule enabled is naturally preserved because EditSchedule has no enabled field). The same handlers serve both merge paths, so the two can't diverge. The fork owner re-enables locally via setmode/setenabled (which carry the conflict warning below).

For a non-fork target the incoming value is applied as given — so a fork→parent merge of an existing trigger writes the parent's own (substituted) value (a no-op), and a fork-only trigger lands with the fork creator's chosen state.

Conflict warning on enable

The set_*_trigger_mode endpoint fires the warning whenever a fork transitions to a mode that attaches a listener — Enabled or Suspended. Suspended is not "off": the listener still attaches and consumes events; only the auto-run of queued jobs is paused. Two suspended forks would still split Kafka events or share a Postgres slot with the parent. Disabled is the only mode that fully detaches.

The check fires whenever the parent workspace has a row at the same trigger path — regardless of the parent's current mode/enabled. If so, the endpoint rejects the request with an error string of the shape:

fork-conflict:<kind>:<parent_workspace_id>

The frontend's withForkConflictRetry helper detects this prefix, asks the user to confirm via a dialog (a ConfirmationModal mounted at the logged layout root, driven by the forkConflictModal store), and re-issues the call with force: true if the user agrees. The CLI sees the raw error.

The check fires whenever the parent has the row because the fork's row was cloned from the parent — the upstream identifier (Kafka group, PG slot, SQS queue URL, GCP/Azure subscription, …) is shared by construction. That sharing is a risk independent of the parent's current state:

• Both enabled → the listeners compete (split events) or fire twice.
• Parent disabled → the fork can destructively claim shared state (PG WAL advance, Azure secret_hash reuse, MQTT client_id race) before the parent re-enables.

The check is opt-out per kind via TriggerCrud::FORK_CONFLICT_ON_ENABLE (default true). It is skipped for kinds whose upstream identifier is already workspace-scoped at runtime — fork and parent there can never share a real upstream:

• HTTP — routes are /r/<workspace_id>/...; cloned rows always have workspaced_route=true (non-workspaced are filtered out at clone time).
• Email — addresses are workspace-prefixed; cloned rows always have workspaced_local_part=true.

The check fires for every other kind. The frontend modal copy splits the conflict into three families so the user can act on the right risk:

• Split events (Kafka, NATS, MQTT, SQS, GCP, Azure) — events split between the two listeners; each side receives a fraction of its traffic.
• Duplicate firing (Websocket, Schedule) — every event fires the script twice (once in fork, once in parent).
• Slot takeover (Postgres) — the replication slot is exclusive and destructive: enabling either errors with "slot already active" (parent enabled) or hijacks the WAL position (parent disabled).

This warning is the durable solution for trigger kinds where the conflict cannot be eliminated by namespacing alone:

• SQS — the queue is the event source; two consumers will compete for messages no matter what.
• GCP-Existing subscription — same as SQS.
• Schedule — same wall-clock firing.

For the kinds that can be auto-namespaced (see below), the warning is the short-term placeholder until that work lands.

Merge UI behavior

Triggers and schedules flow through the same compare_workspaces API as scripts, flows, and the rest. tally_deployed_object_changes records every trigger/schedule mutation in workspace_diff, and compare_two_* strips runtime fields (mode, enabled, server_id, last_server_ping, edited_at/edited_by, error, extra_perms, permissioned_as, workspace_id, email) plus server-managed fields the merge feature treats as workspace-local (subscription_id for GCP, push_auth_config for Azure — both regenerated by their deploy handlers per workspace) before comparing. A fresh fork (where only mode/enabled differ from the parent) reports no diffs, and a successfully-merged GCP/Azure push trigger doesn't re-appear in the diff list because of the regenerated subscription id / auth secret.

Both the merge UI (CompareWorkspaces.svelte) and wmill workspace merge consume those rows directly. All ten deployable trigger kinds — HTTP, Websocket, Kafka, NATS, Postgres, MQTT, SQS, GCP, Azure, Email — plus schedules are handled. Non-workspaced HTTP routes and email triggers are intentionally not cloned at fork creation (they would collide instance-wide), but tally_deployed_object_changes still records mutations against them; the deploy will fail at the workspace-collision check if the user tries to deploy a non-workspaced row to a fork.

Operational state (mode for triggers, enabled for schedules) follows the same "owned by the parent" rule as the git round-trip (see Operational state is owned by the parent above) — the two paths share the backend create/ update handlers, so they can't diverge.

• Update: the merge deploy strips mode/enabled (stripOperationalStateOnUpdate in the shared windmill-utils-internal package, cli/windmill-utils-internal/src/deploy.ts), so the target's existing value is preserved — equivalent to substituting the target's value. For a fork target the backend preserves it regardless (workspace_is_fork); for a parent target the is_mode_unspecified() safeguard does. Schedules also rely on EditSchedule lacking the enabled field.
• Create: the source's mode/enabled is passed through. Into a parent there's no row to preserve, so a fork-only trigger/schedule lands with the state the fork creator chose (omitting the flag defaults to enabled: BaseTriggerData::mode() → Enabled, schedule insert → true). Into a fork the backend forces disabled — a fork write never enables anything.

Future work — runtime listener suffix

A follow-up PR will append a fork-specific suffix to the upstream identifier at runtime for the kinds that support it:

Kind	Identifier	Notes
Kafka	group_id	Two consumer groups never share messages.
MQTT	client_id	Brokers reject duplicate client_ids; suffix avoids that.
NATS	durable consumer name	Fork consumes independently.
Postgres	replication_slot_name + publication_name	Fork auto-creates its own publication on enable, drops on disable / fork delete.
Azure Event Grid	subscription_name	manage_azure_subscription creates the suffixed sub in Azure.
GCP Pub/Sub (CreateNew)	subscription_id	manage_google_subscription creates the suffixed sub.

The suffix is applied at runtime by the listener — the stored identifier column never carries the suffix, so nothing extra needs to be filtered on export. The follow-up also adds cleanup-on-fork-delete hooks for the upstream resources (Azure / GCP / Postgres publication) so deleted forks don't leak external state.