> ## 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.

# group

> Catalog resource that collects users into a named set so tenant-bindings can grant permissions to every member at once instead of listing each one.

A [group](/catalog/group) is a catalog resource that collects users into a named set. [Tenant-bindings](/catalog/tenant-binding) reference groups to grant [permissions](/security/permissions) to every member at once — instead of listing individual users in each binding, you manage membership in one place.

Exactly one source type must be set: `static`, `github_admin`, or `all_tenant_members`.

## Fields

| Name          | Type   | Required | Description                                                                                                               |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | yes      | Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. Names prefixed `murmur-` are reserved for platform builtins. |
| `description` | string | no       | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                                    |
| `source`      | oneof  | yes      | How membership is determined. Exactly one of `static`, `github_admin`, or `all_tenant_members`.                           |

## Source: `static`

A hand-managed list of GitHub usernames.

| Name             | Type      | Required | Description                                                                     |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------- |
| `static.members` | string\[] | yes      | GitHub usernames in this group. At least one member is required. No duplicates. |

## Source: `github_admin`

Resolves to the owners of the GitHub organization linked to the tenant. No additional fields.

| Name           | Type   | Required | Description                                                         |
| -------------- | ------ | -------- | ------------------------------------------------------------------- |
| `github_admin` | object | yes      | Empty object. Membership is resolved automatically from org owners. |

## Source: `all_tenant_members`

Resolves to every authenticated member of the tenant. Reserved for platform builtins.

| Name                 | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `all_tenant_members` | object | yes      | Empty object. Membership includes all tenant members. |

<Warning>
  `all_tenant_members` is reserved for platform-managed groups. Tenant-authored groups use `static` or `github_admin`.
</Warning>

## Examples

### Static group

```yaml theme={null}
name: platform-team
description: "Core platform engineers"
static:
  members:
    - alice
    - bob
    - carol
```

```bash theme={null}
cat <<'EOF' | murmur set group platform-team
name: platform-team
description: "Core platform engineers"
static:
  members:
    - alice
    - bob
    - carol
EOF
```

### GitHub admin group

```yaml theme={null}
name: org-admins
description: "GitHub organization owners"
github_admin: {}
```

```bash theme={null}
cat <<'EOF' | murmur set group org-admins
name: org-admins
description: "GitHub organization owners"
github_admin: {}
EOF
```

### Listing groups

```bash theme={null}
murmur get group
```

```
NAME             DESCRIPTION
platform-team    Core platform engineers
org-admins       GitHub organization owners
```

### Reading a single group

```bash theme={null}
murmur get group platform-team
```

## 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 a valid DNS label — lowercase letters, digits, and hyphens. Must start with a letter.                             |
| `INVALID_ARGUMENT`    | `description exceeds 1024 byte limit`                                    | Shorten the `description` to 1024 bytes or fewer.                                                                     |
| `INVALID_ARGUMENT`    | `group source is required (static, github_admin, or all_tenant_members)` | Set exactly one of `static`, `github_admin`, or `all_tenant_members`.                                                 |
| `INVALID_ARGUMENT`    | `static group must have at least one member`                             | Add at least one username to `static.members`.                                                                        |
| `INVALID_ARGUMENT`    | `static.members[N] must be non-empty`                                    | A member entry is an empty string. Provide a GitHub username.                                                         |
| `INVALID_ARGUMENT`    | `static.members[N]: duplicate member "username"`                         | Remove the duplicate username from `static.members`.                                                                  |
| `FAILED_PRECONDITION` | `cannot delete group "name": referenced by tenant-binding: binding-name` | Remove the [tenant-binding](/catalog/tenant-binding) that references this [group](/catalog/group) before deleting it. |

## Related

* [Role](/catalog/role) — named permission bundle that a [tenant-binding](/catalog/tenant-binding) can reference
* [Tenant-binding](/catalog/tenant-binding) — grants [permissions](/security/permissions) to [groups](/catalog/group) and users
* [Permissions](/security/permissions) — guide to the permission model
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources