Skip to main content
A change-request proposes a new value for another catalog resource and holds that value until someone with write access approves it. It is how a person — or an agent — who can read a resource but not write it suggests a change: propose the new value, others endorse it, and a reviewer with permission to write the target approves it. Approving applies the proposed value to the target in one step. A change-request is created and updated entirely through its own commands — proposing, approving, rejecting, withdrawing, and endorsing. You do not author it with murmur set change-request, and you do not delete it with murmur rm. You read one with murmur get change-request.

​
Lifecycle

A change-request moves through these states: A PENDING change-request the proposer no longer wants is withdrawn — removed entirely. Withdrawal works only while PENDING; once a change-request is APPROVED or later, the proposer cannot cancel it and must ask a reviewer to reject it. The proposed value applies only if the target has not changed since the change-request was proposed. If the target changed in the meantime, approval fails with a conflict and the change-request stays APPROVED so the conflict can be resolved or the change rejected. Nothing is merged silently.

​
Fields

Change-requests are managed by the API, not authored by hand. Reading one with murmur get change-request <id> shows these fields:

​
Action change-requests

A change-request carries either a resource change (the targetKind/targetName/proposedPayload fields above — approval writes the target) or one executable action — approval executes the verb. Exactly one form per change-request. Two actions exist: Actions have no target resource, so they carry no baseVersion and no conflict window — the action content is validated against the current catalog when proposed and re-resolved when executed, so referenced-resource drift fails the approval loudly. The executors are idempotent: re-approving an applied action joins the running bake or agent (or no-ops on a cached image) — it never doubles. Proposing an action needs change-request.create plus read on its primary kind (recipe.read for a bake, workspace.read for a spawn). The agent an approved spawn action starts — and the VM an approved bake runs on — act as the named service-profile, never as the proposer or approver: a proposal carries no one’s personal credentials. murmur bake and the dashboard’s “New Bake” execute immediately through the imperative Bake API — no change-request is created; murmur bake --propose stages a bake action for review, and its approval runs the identical executor. Likewise, murmur spawn executes immediately, and murmur spawn --propose stages a spawn action for review. The platform’s automated re-bake proposals (source: recipe_bake) are bake actions derived from your bake execution history.

​
Propose a change

To suggest a change to a catalog resource without writing it directly, read the resource, edit the value, and pipe it to murmur set with --propose. This creates a PENDING change-request and prints its id instead of writing the target.
--propose takes the full resource value as the proposed replacement and validates it against the target’s schema immediately — an invalid proposal is rejected at propose time, not at approval. --rationale is optional and records why you are proposing the change. Proposing requires change-request.create and read access to the target ({targetKind}.read). Every org member and every service profile can propose by default.

​
Read change-requests

List every change-request in your tenant:
Read one change-request in full, including its proposed value and rationale:
Reading a change-request requires change-request.read (or change-request.list to list) and read access to the target. A caller who cannot read recipes cannot read recipe change-requests, and list results omit change-requests whose target the caller cannot read.

​
Endorse a change-request

Endorsing adds your thumbs-up to a PENDING or APPROVED change-request — an advisory signal of demand that aggregates onto one proposal. It never approves or applies the change, and approval never depends on the endorsement count.
Remove your endorsement with unendorse:
Endorsing is idempotent: endorsing twice leaves one endorsement, and un-endorsing when you have not endorsed does nothing. Endorsing requires change-request.endorse and read access to the target. Agents can participate in the same signal through MCP tools — find_change_requests discovers open proposals so an agent endorses an equivalent one instead of filing a duplicate, and endorse_change_request / unendorse_change_request toggle its thumbs-up. Unlike org members and service profiles, agent runtimes hold no change-request permissions by default; an agent uses these tools only where the tenant grants change-request.read, change-request.list, and change-request.endorse to its agent runtimes.

​
Approve, reject, or withdraw

A reviewer with permission to write the target drives the change-request to a terminal state with murmur change-request (alias murmur cr).

​
Approve

Approving records the approval and writes the proposed value to the target in one step:
Approval requires the same permission as writing the target directly: {targetKind}.create if the target did not exist when the change was proposed, otherwise {targetKind}.edit. --note records an optional decision note.

​
Reject

Rejecting requires the same target-write permission as approving.

​
Withdraw

The proposer removes their own PENDING change-request:
Only the proposer can withdraw, and only while the change-request is PENDING.

​
Targets you cannot propose against

A change-request carries the full proposed value of its target, so kinds whose value cannot be meaningfully reviewed — or whose value the server itself maintains — cannot be targets: Platform builtins (resources whose name begins with murmur-) also cannot be the target of a change-request.

​
Errors