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

# github-role catalog resource

> Catalog resource that controls which GitHub operations an agent may perform with the GitHub credential it runs with.

A GitHub role controls what an [agent](https://docs.murmur.dev/concepts/agents.md) may do with the GitHub credential it runs with: pushing, opening pull requests, merging, re-running CI. The dashboard shows it as **Permissions → GitHub** on the agent.

Murmur's GitHub gateway checks the role on every GitHub request, so a change takes effect on the agent's next request. The credential still bounds the result: a role cannot reach a repository or permission the token itself lacks.

## Synopsis

```bash theme={null}
murmur get github-role [name]
murmur set github-role <name> < github-role.yaml
murmur rm github-role <name>
murmur github-role <slug> <name>
murmur github-role --clear <slug>
```

Manage this resource with [`murmur get`](https://docs.murmur.dev/cli/get), [`murmur set`](https://docs.murmur.dev/cli/set), and [`murmur rm`](https://docs.murmur.dev/cli/rm). Tenant admins define custom roles.

## Builtin GitHub roles

| Role | What the agent may do |
| - | - |
| `murmur-coding-agent` | The default. Read repositories; push code, including workflow files; open, edit, review, and comment on pull requests; manage issues, labels, and milestones; write commit statuses; read CI runs, checks, and deployments; re-run CI; create repositories. It cannot merge or approve pull requests, administer Actions, repositories, or organizations, or touch secrets, security alerts, or webhooks. |
| `murmur-read-only` | Every GitHub read. No mutation and no Git write of any kind. |
| `murmur-unrestricted` | Every GitHub operation, including merging and approving pull requests. Only the credential itself limits the agent. |

## Selecting a GitHub role

The role that governs a request is chosen in this order:

1. The agent's own role, when one is set. Run `murmur github-role <slug> <name>`, or choose a role from **Permissions → GitHub** in the dashboard. Run `murmur github-role --clear <slug>` to remove it. Changing it requires edit access to both the agent and the identity it runs as.
2. Otherwise, the `github_role` of the identity the agent runs as: your [user](https://docs.murmur.dev/catalog/user.md) record, or the [service profile](https://docs.murmur.dev/catalog/service-profile.md) the agent runs as.
3. Otherwise, `murmur-coding-agent`.

A typical setup keeps your own `github_role` at the default and sets a role that can merge pull requests only on your director.

## Fields

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Unique name. Names starting with `murmur-` are reserved for platform builtins. |
| `description` | string | no | Human-readable description. |
| `permissions` | object\[] | no | GitHub-native grants, each a resource name and a `READ` or `WRITE` level. Each resource may appear once, and `WRITE` includes `READ`. Resource `*` grants that level everywhere, including operations Murmur cannot classify. |
| `allowPullRequestMerge` | bool | no | Allows merging pull requests. Not implied by `pull_requests` or `contents` `WRITE`. |
| `allowPullRequestApproval` | bool | no | Allows approving pull requests. Not implied by `pull_requests` `WRITE`; review comments and requested changes do not need it. |
| `allowActionsRerun` | bool | no | Allows re-running a workflow run, its failed jobs, or one job, without Actions write access generally. Dispatching, cancelling, or deleting runs still needs `actions` `WRITE`. |
| `allowRepositoryCreate` | bool | no | Allows creating a repository, from scratch, from a template, or as a fork, without administration access generally. |

## Example

Derive a role that can also merge pull requests from the default:

```bash theme={null}
murmur get github-role murmur-coding-agent > merger.yaml
# Edit merger.yaml: rename it to merger and add allowPullRequestMerge: true.
murmur set github-role merger < merger.yaml
murmur github-role <slug> merger
```

## Related

* [runtime-role](https://docs.murmur.dev/catalog/runtime-role.md): what an agent may do in Murmur
* [Repository confinement](https://docs.murmur.dev/security/repository-confinement.md)
* [Service profiles](https://docs.murmur.dev/concepts/service-profiles.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.