.stackat.yml / option

commands

Limits who may use the commands that change something: /stackpaw pr, ignore (and track) and reevaluate. By default, everyone with a role in the repository may use them.

What it does#

List, per command, who may use it:

Each list holds any mix of:

• people: "@alice";
• teams of the repository's own organisation: "@acme/platform-team";
• GitHub repository roles: admin, maintain, write, triage, read. A role means that role or higher: write lets in write, maintain and admin.

Write @ entries in quotes: in YAML a value cannot start with @ unquoted.

The rules:

• A command the settings do not mention keeps the default: everyone with a role in the repository. Feedback (wrong, missed, note) and 👍 / 👎 cannot be limited.
• People listed by @login, and active members of a listed team, may use the command even without a role in the repository: your organisation named them.
• A role counts only for people who have one. On a public repository everyone can read, so read never lets a stranger in.
• Anyone else with a role gets one reply on the issue and nothing is done. People without a role are still ignored silently. See Commands for the reply.
• Nothing broken lets more people in. An entry that cannot be read is left out. A list that cannot be read lets nobody use that command until it is fixed, and so does an empty list, on purpose.

Teams need the Members permission#

A team entry is checked by asking GitHub whether the person is an active member of the team, which needs the app's organisation permission Members: read-only. If your installation has not been granted it, team entries never match, and the dashboard's Settings tab shows "commands.pr: team rules need the app's Members (read) permission". People and roles work without it. A team of another organisation never matches and is reported too.

If GitHub does not answer about the settings, a person's role or a team, the command waits for the next scan instead of being decided on a guess.

Type and values#

Organisation and repository#

Per command: a repository's list for a command replaces the organisation's list for that command. The commands the repository does not mention keep the organisation's list.

commands:
  pr: ["@acme/platform-team"]
  ignore: ["@acme/security"]

commands:
  pr: ["@acme/payments", maintain]   # replaces the organisation's pr list here
                                     # ignore still follows the organisation: @acme/security

Problems you may see#

.stackat.yml: commands.pr: 'alice' is not an @login, an @organisation/team or a role (admin, maintain, write, triage, read)
.stackat.yml: commands.pr must be a list of @people, @organisation/teams or roles (admin, maintain, write, triage, read); nobody can use it until it is fixed
.stackat.yml: commands must be a mapping of pr, ignore, reevaluate to a list of @people, @organisation/teams or roles (admin, maintain, write, triage, read); nobody can use those commands until it is fixed
.stackat.yml: commands.track: who may track is set under `ignore`, which covers both
.stackat.yml: commands.wrong: feedback stays open to everyone with a role in the repository
.stackat.yml: commands.merge: not a command that can be restricted (pr, ignore, reevaluate)
.stackat.yml: commands.pr: only the first 50 entries are used
.stackat.yml: commands.pr: @other-org/devs belong to another organisation than the repository, so they never match
.stackat.yml: commands.pr: team rules need the app's Members (read) permission

Warning: pr: with nothing after it is a list that cannot be read, so nobody can use /stackpaw pr. And a whole file that is not valid YAML but has a commands: key locks pr, ignore/track and reevaluate for everyone until it is fixed. A commands: key with every line under it commented out is simply not set.

Examples#

Pull requests only for the platform team and maintainers#

commands:
  pr: ["@acme/platform-team", maintain]

Only security may close an issue with ignore#

Stops anyone else silencing a vulnerability issue with /stackpaw ignore.

commands:
  ignore: ["@acme/security", "@dana"]

Every command limited#

commands:
  pr: ["@alice", "@bob", maintain]
  ignore: [admin]
  reevaluate: [write]