role

A role is a catalog resource that bundles permissions under a reusable name. Tenant bindings reference roles to grant permissions to users and groups.

Synopsis

murmur get role [name]
murmur set role <name> < role.yaml
murmur rm role <name>

Manage this resource with murmur get, murmur set, and murmur rm.

Arguments

Name	Type	Required	Description
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. Names starting with `murmur-` are reserved for platform builtins.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.
`permissions`	string[]	yes	One or more permission strings. Must be non-empty.

Permission format

Each entry in permissions is a string in one of four forms:

Form	Meaning
`*`	All permissions on all catalog kinds.
`{kind}.*`	All verbs on the specified kind.
`*.{verb}`	The specified verb on all kinds.
`{kind}.{verb}`	A single verb on a single kind.

Kinds

A {kind} is any catalog kind that murmur describe lists, plus agent and change-request. Authorization-only kinds are also valid: placement-sa, tenant, attachment, developer, bake, event-delivery, access-log, access-log-body, github-request-log, github-request-log-body, and analytics.

Verbs

Verb	Description
`read`	Get a resource, or see it in a listing. A listing returns exactly the resources the caller can read.
`create`	Create a new resource.
`edit`	Mutate an existing resource.
`delete`	Delete a resource.
`assume`	Use a resource as a runtime credential.
`encrypt`	Encrypt tenant secret material. Distinct from `read` so a tenant-wide read grant cannot also encrypt.
`endorse`	Add or remove an advisory thumbs-up on a change-request. Never authorizes a write.
`login`	Sign in to a tenant. Valid only as `tenant.login`.
`purge`	Permanently destroy a resource and everything Murmur holds for it. Distinct from `delete`.
`use`	Access a workspace’s contents in addition to the resource’s own kind permission. Valid only as `workspace.use`.

Use read to make resources visible in listings. For agent discovery, grant agent.read through a tenant binding, a runtime binding, or a workspace grant, together with access to the workspace.

Examples

Create a role with full agent access

name: agent-operator
description: "Full access to agents and workspaces"
permissions:
  - "agent.*"
  - "workspace.*"

cat <<'EOF' | murmur set role agent-operator
name: agent-operator
description: "Full access to agents and workspaces"
permissions:
  - "agent.*"
  - "workspace.*"
EOF

Create a read-only role

*.read supplies kind reads, not workspace.use. Add workspace access separately for scoped contents. This grant also covers audit-body reads; use explicit kind permissions for a narrower reader.

name: viewer
description: "Read access, including listings, to all resources"
permissions:
  - "*.read"

cat <<'EOF' | murmur set role viewer
name: viewer
description: "Read access, including listings, to all resources"
permissions:
  - "*.read"
EOF

Create a role scoped to secrets

name: secret-manager
description: "Manage secrets only"
permissions:
  - "secret.read"
  - "secret.create"
  - "secret.edit"
  - "secret.delete"

Listing roles

murmur get role

agent-operator
secret-manager
viewer

The list prints one name per line.

Reading a single role

murmur get role agent-operator

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use only lowercase letters, digits, and hyphens. Must start with a letter.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit (N bytes)`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`permissions must be non-empty`	Add at least one permission string to `permissions`.
`INVALID_ARGUMENT`	`permissions[N]: invalid permission "{perm}": must be "", "{kind}.", "*.{verb}", or "{kind}.{verb}"`	Fix the permission string to use a valid form.
`INVALID_ARGUMENT`	`permissions[N]: invalid permission "{perm}": unknown kind "{kind}"`	Use a valid catalog kind name. See Kinds.
`INVALID_ARGUMENT`	`permissions[N]: invalid permission "{perm}": unknown verb "{verb}"`	Use a valid verb: `read`, `create`, `edit`, `delete`, `assume`, `encrypt`, `endorse`, `login`, `purge`, or `use`.
`INVALID_ARGUMENT`	`permissions[N]: invalid permission "{perm}": verb "{verb}" applies only to {kinds}`	Pair the verb with a kind it applies to (for example, `tenant.login`).
`INVALID_ARGUMENT`	`permissions[N]: duplicate permission "{perm}"`	Remove the duplicate entry from `permissions`.
`INVALID_ARGUMENT`	`permissions: "*" makes other permissions redundant`	When using `*`, it must be the only entry in `permissions`.
`INVALID_ARGUMENT`	`permissions: "{perm}" is subsumed by "{wildcard}"`	A more specific permission is redundant because a broader wildcard already covers it. Remove the narrower entry.
`FAILED_PRECONDITION`	`cannot delete role "{name}": referenced by tenant-binding: {bindings}`	Remove or update the tenant bindings that reference this role before deleting it.

Authorization: how roles, groups, and tenant bindings work together
Permissions: default permissions and how to grant admin access
Catalog: overview of all catalog resource types
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Synopsis

Arguments

Permission format

Kinds

Verbs

Examples

Create a role with full agent access

Create a read-only role

Create a role scoped to secrets

Listing roles

Reading a single role

Errors

​Synopsis

​Arguments

​Permission format

​Kinds

​Verbs

​Examples

​Create a role with full agent access

​Create a read-only role

​Create a role scoped to secrets

​Listing roles

​Reading a single role

​Errors

​Related

Synopsis

Arguments

Permission format

Kinds

Verbs

Examples

Create a role with full agent access

Create a read-only role

Create a role scoped to secrets

Listing roles

Reading a single role

Errors

Related