Skip to main content
A steering policy names who may steer agents through external events, including pull request comments and reviews and issue-opened, PR-opened, or PR-labeled flight triggers. It combines a minimum author-association tier (how closely the author is tied to the repository) with allowlists of named users who may steer regardless of tier. It also supports denylists of users who may never steer; denylists override both the tier and allowlists. An event whose author fails the policy is recorded on the agent’s timeline as BLOCKED. It produces no follow-up, checklist task, wake, or flight spawn. A steering policy controls who may initiate agent work from outside, not what the agent may do once it is working. In the dashboard, steering policies are managed under Organization Settings → Agent configuration → Steering Policies.

​
Fields

​
Tiers

The tier field sets the minimum GitHub author association that may steer. The tiers below run from broadest to narrowest: COLLABORATORS admits everyone MEMBERS does, plus repository collaborators.

​
Denylists

An actor list is a named set of usernames with no polarity of its own. The referencing field decides: naming the list under allowlists admits its actors, while naming it under denylists refuses them. This lets you keep the tier open for everyone with repository access while blocking a noisy machine account, such as a preview bot that comments on every push. Matching is identical in both directions: provider-scoped (a GitHub login is matched in PROVIDER_GITHUB_OAUTH) and case-insensitive against the event author’s login, unioned across every list the field names. A list may be named by allowlists or denylists, never both. Because deny would silently win, the server rejects a policy that names the same list in both fields. To subtract an actor from a list you otherwise admit, name a second, narrower list on denylists:
Denying an actor blocks steering only. The platform still records what the actor did. A denied preview bot’s links are still harvested into the agent’s artifacts, and its PR activity still appears in the dashboard, but the comment never wakes an agent. A denylist block appears in the event delivery log with the reason steering_denylist_denied, which distinguishes it from a tier or allowlist miss.

​
Precedence

  1. An agent’s own owner always steers it. A denylist never locks a developer out of their own agent: revoking a person’s authority is a role change, not a steering policy.
  2. Denylists beat everything else. A denied author is blocked even when the tier admits them and even when an allowlist (this policy’s own, or another applicable policy’s) names them.
  3. Tier, then allowlists. An author no denylist names is admitted by the tier or, failing that, by an allowlist.
When both a repo policy and a service-profile policy apply, an actor denied by either is denied.

​
How a policy is selected

A steering policy is chosen for each event based on its repository. For service-profile agents, the owning profile can also select a policy:
  • Per repository: repo-config.steering_policy names a policy explicitly. When unset, the platform selects by repository visibility: public repos use murmur-public-steering-policy, private repos use murmur-private-steering-policy. Both are platform builtins.
  • Per service profile: service-profile.steering_policy names a policy for agents running under that identity.
When both a repo policy and a profile policy apply, the author must pass both. In effect, the narrower policy wins. A developer can always steer an agent they own directly.

​
Events delivered by GitHub Actions

Repositories that deliver events through the GitHub Actions workflow created by murmur install-repo prove which repository sent an event, but not who wrote it. The author, association, and labels in those events come from the workflow run, not from GitHub, so Murmur shows the author on the timeline without treating them as a verified person:
  • Only STEERING_TIER_OPEN admits these events. No other tier, no allowlist, and no ownership of the agent can admit an author Murmur cannot verify.
  • Denylists cannot match them either, because the author could name anyone.
  • The repository visibility that selects the default policy comes from GitHub’s signed workflow token, so public repositories use murmur-public-steering-policy and their comments do not steer agents.
Install the GitHub App to steer agents from public repositories by author. App events are signed by GitHub, so their authors are verified.

​
Examples

​
Require organization membership

​
Allowlist-only, with trusted actors

Turn the tier check off and admit only the users named in an actor allowlist.

​
Everyone on a private repo, except a preview bot

STEERING_TIER_OPEN admits any author, so this shape fits a private repository, where everyone who can comment was already granted access by the organization, and subtracts the machine accounts that must never steer. On a public repository, where anyone on GitHub can comment, pair denylists with a restrictive tier (STEERING_TIER_COLLABORATORS or narrower) instead. First the actor list naming the bots:
Then the policy that denies it:
Select it for the repository whose events it should gate. murmur patch updates just the one field, preserving any repo-config settings the repository already has (murmur set would replace the whole resource):

​
Members, plus an allowlist of outside contributors

​
Listing steering policies

The list prints one name per line.

​
Reading a single steering policy

​
Errors

  • actor-allowlist: the named actor lists a policy admits (allowlists) or refuses (denylists)
  • service-profile: references a steering policy for agents under that identity
  • repo-config: references a steering policy per repository
  • Events: the webhook events steering gates
  • murmur set: CLI command for creating and updating catalog resources
  • murmur get: CLI command for reading catalog resources