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. A person or agent who can read a resource but not write it can propose a new value. Others can endorse it, and a reviewer with permission to write the target can approve it. Approval applies the proposed value to the target in one step. A change-request is created and updated entirely through its own commands for 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 or one executable action. For a resource change, approval writes the targetKind/targetName/proposedPayload fields above. For an action, approval executes the verb. Each change-request has exactly one form. 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 does not run the action twice. 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 both 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.
The id prints on stdout. A confirmation line prints on stderr: Created change-request cr-a1b2c3d4e5f6 (PENDING) for recipe/default. --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), including workspace.use for a workspace-scoped target. The built-in murmur-shared-floor tenant-binding grants proposal, read, and endorsement permissions to organization members and service profiles, extending them live to their running agents. Target access is checked separately.

​
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, whether one at a time or in the list above, requires change-request.read and read access to the target. A caller who cannot read recipes cannot read recipe change-requests, and the list omits change-requests whose target the caller cannot read.

​
Endorse a change-request

Endorsing adds your thumbs-up to a PENDING or APPROVED change-request as an advisory signal of demand. 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 discover and endorse proposals through the MCP server. Their default change-request.create, change-request.read, and change-request.endorse permissions come from murmur-shared-floor, evaluated live against the identity they act as. Reading a proposed value and endorsing require target read access; approving requires target write authority. These default proposal permissions do not confer approval authority.

​
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. Resource kinds that cannot be meaningfully reviewed, or that the server maintains, cannot be targets: Platform builtins (resources whose name begins with murmur-) also cannot be the target of a change-request.

​
Errors