actor-allowlist

An actor list is a catalog resource that names a reusable set of usernames, grouped by identity provider. A steering policy references it to decide who may steer agents through externally-sourced events such as pull request comments, reviews, and issue or PR triggers:

named under the policy’s allowlists, the list admits its actors regardless of the policy’s association tier — this is how you let an approved bot or a trusted outside contributor drive an agent without granting them an organization role;
named under the policy’s denylists, the same list refuses its actors, overriding the tier and every allowlist.

The list itself carries no polarity: it is just a named set of actors, and the referencing field decides what it means. The same list may therefore be admitted by one policy and refused by another.

The resource kind is spelled actor-allowlist for historical reasons — it predates the denylists field, and the kind name is part of how stored objects are addressed, so it is kept stable. Read it as “actor list”: the dashboard calls the section Actor Lists, and nothing about a list restricts it to allowing.

Usernames are grouped by provider so the right namespace is matched against the event’s author — a GitHub login is matched in the GitHub OAuth provider, not against an organization or service identity. Matching is case-insensitive. In the dashboard, actor lists are managed under Organization Settings → Actor Lists.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier within the tenant. 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.
`entries`	ActorAllowlistEntry[]	no	The list’s usernames, grouped by identity provider. Each provider may appear at most once.

Entry fields

Each entry in entries groups usernames under one identity provider.

Name	Type	Required	Description
`provider`	enum	yes	The actor’s identity provider. Must be a user namespace — `PROVIDER_GITHUB_OAUTH` for a GitHub login. Organization and service namespaces (`PROVIDER_GITHUB_APP`, `PROVIDER_SERVICE_PROFILE`) are rejected: they never name a person, so an entry keyed on them would match no event author.
`usernames`	string[]	yes	Usernames within the provider, matched case-insensitively against the event author. For GitHub, the login (e.g. `octocat`, `dependabot[bot]`). Each entry must be non-empty.

How it is used

An actor list does nothing on its own — a steering policy references it. When a gated event arrives (a PR comment, review, issue-opened, PR-opened, or PR-labeled trigger), the policy decides in this order:

Denylists first. If the author appears in the union of usernames across the policy’s denylists, the event is refused — whatever the tier says and whatever an allowlist says.
Then the tier. The author’s repository association meets the policy’s tier.
Then the allowlists. The author appears in the union of usernames across the policy’s allowlists, matched within the event’s provider.

So an allowlist is what makes a bot account or a trusted outside collaborator able to steer under a tier they would otherwise fail, and a denylist is what stops an actor a broad tier would otherwise admit. A single list may be named by only one of the two fields on the same policy.

Examples

A list of trusted actors, admitted by a policy

name: trusted-actors
description: "Bots and outside collaborators allowed to steer agents"
entries:
  - provider: PROVIDER_GITHUB_OAUTH
    usernames:
      - dependabot[bot]
      - octocat

cat <<'EOF' | murmur set actor-allowlist trusted-actors
name: trusted-actors
description: "Bots and outside collaborators allowed to steer agents"
entries:
  - provider: PROVIDER_GITHUB_OAUTH
    usernames:
      - dependabot[bot]
      - octocat
EOF

A list of unwanted actors, refused by a policy

The same resource shape; only the referencing field differs.

cat <<'EOF' | murmur set actor-allowlist preview-bots
name: preview-bots
description: "Preview/deploy bots that must never steer agents"
entries:
  - provider: PROVIDER_GITHUB_OAUTH
    usernames:
      - vercel[bot]
      - netlify[bot]
EOF

Reference it from a policy’s denylists, and its actors may never steer.

Listing actor lists

murmur get actor-allowlist

NAME              DESCRIPTION
trusted-actors    Bots and outside collaborators allowed to steer agents

Reading a single actor list

murmur get actor-allowlist trusted-actors

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name`.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use lowercase letters, digits, and hyphens, starting with a letter.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`entries[N]: provider is required`	Set a `provider` on every entry.
`INVALID_ARGUMENT`	`entries[N]: unknown provider <value>`	Use a valid provider — `PROVIDER_GITHUB_OAUTH`.
`INVALID_ARGUMENT`	`entries[N]: provider PROVIDER_GITHUB_APP is an org/service namespace, not an individual actor; use a user namespace such as PROVIDER_GITHUB_OAUTH`	Allowlist entries name people. Use a user-namespace provider.
`INVALID_ARGUMENT`	`entries[N]: duplicate provider <value>`	Merge usernames for a provider into a single entry.
`INVALID_ARGUMENT`	`entries[N].usernames[M]: empty username`	Remove the empty username or fill it in.
`FAILED_PRECONDITION`	`cannot delete actor-allowlist: referenced by steering-policy`	A steering policy still names this list in `allowlists` or `denylists`. Update or delete the policy first.

steering-policy — references actor lists to admit (allowlists) or refuse (denylists) named authors
service-profile — the identity that automated agents commit under
Events — the webhook events steering gates
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

actor-allowlist

Fields

Entry fields

How it is used

Examples

A list of trusted actors, admitted by a policy

A list of unwanted actors, refused by a policy

Listing actor lists

Reading a single actor list

Errors

​Fields

​Entry fields

​How it is used

​Examples

​A list of trusted actors, admitted by a policy

​A list of unwanted actors, refused by a policy

​Listing actor lists

​Reading a single actor list

​Errors

​Related

Fields

Entry fields

How it is used

Examples

A list of trusted actors, admitted by a policy

A list of unwanted actors, refused by a policy

Listing actor lists

Reading a single actor list

Errors

Related