> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# actor-allowlist

> Catalog resource that names a reusable set of usernames, grouped by identity provider, permitted to steer agents via webhook events regardless of their repository association.

An **actor allowlist** is a catalog resource that names a reusable set of usernames — grouped by identity provider — who may steer [agents](/concepts/agents) through externally-sourced events such as pull request comments, reviews, and issue or PR triggers. A [steering policy](/catalog/steering-policy) references one or more allowlists; an author in the union of their usernames is admitted 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.

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 allowlists are managed under **Organization Settings → Actor Allowlists**.

## 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       | Allowlisted 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 allowlist does nothing on its own — it is referenced by a [steering policy's](/catalog/steering-policy) `allowlists` field. When a gated event arrives (a PR comment, review, issue-opened, PR-opened, or PR-labeled trigger), the policy admits the author if either:

* The author's repository association meets the policy's [tier](/catalog/steering-policy), **or**
* The author appears in the union of usernames across the policy's referenced allowlists, matched within the event's provider.

An allowlist is what makes a bot account or a trusted outside collaborator able to steer an agent under a tier they would otherwise fail.

## Examples

### Allowlist a bot and an outside contributor

```yaml theme={null}
name: trusted-actors
description: "Bots and outside collaborators allowed to steer agents"
entries:
  - provider: PROVIDER_GITHUB_OAUTH
    usernames:
      - dependabot[bot]
      - octocat
```

```bash theme={null}
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
```

### Listing actor allowlists

```bash theme={null}
murmur get actor-allowlist
```

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

### Reading a single actor allowlist

```bash theme={null}
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](/catalog/steering-policy) still names this allowlist. Update or delete the policy first. |

## Related

* [steering-policy](/catalog/steering-policy) — references actor allowlists to admit authors regardless of tier
* [service-profile](/catalog/service-profile) — the identity that automated agents commit under
* [Events](/concepts/events) — the webhook events steering gates
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources