github-role catalog resource

A GitHub role controls what an agent 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

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, murmur set, and murmur 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:

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.
Otherwise, the github_role of the identity the agent runs as: your user record, or the service profile the agent runs as.
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:

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

runtime-role: what an agent may do in Murmur
Repository confinement
Service profiles

Getting started

Core concepts

Integrations

Guides

github-role catalog resource

Synopsis

Builtin GitHub roles

Selecting a GitHub role

Fields

Example

​Synopsis

​Builtin GitHub roles

​Selecting a GitHub role

​Fields

​Example

​Related

Synopsis

Builtin GitHub roles

Selecting a GitHub role

Fields

Example

Related