vole
Clone
Read only, no credentials:
https://rodent.software/git/vole.git
Write over SSH with a registered key:
git clone ssh://git@0.0.0.0:2222/vole.git
A free and open-source forge that lives in your Git repo.
Filter workflow events by mentions and assignment
727df38613897e6ffd56e1df05a2f674174bf547 · Keenan Nemetz · 8d ago · parent eb07ff56
Filter workflow events by mentions and assignment Add mentioned, replied-to, assigned-to, and author filters to issue, comment, and change-request triggers. Move the role vocabulary into core/role so author.role is validated without importing the access store, and pin mentions, reply authors, and assignee changes in the event payload.
docs/reference/workflow-reference.md +100−4
| @@ -26,6 +26,8 @@ Unknown keys are rejected. A workflow is validated when it is pushed and again b | |||
| 26 | 26 | | Maximum display name | 80 bytes | | |
| 27 | 27 | | Maximum description | 500 bytes | | |
| 28 | 28 | | Maximum path filters | 20 per list | | |
| 29 | | Maximum accounts per event filter | 10 per list | | ||
| 30 | | Maximum mentions read from one body | 32 | | ||
| 29 | 31 | | Maximum schedules | 5 | | |
| 30 | 32 | | Maximum manual inputs | 10 | | |
| 31 | 33 | | Maximum event payload | 64 KiB | | |
| @@ -47,6 +49,14 @@ Unknown keys are rejected. A workflow is validated when it is pushed and again b | |||
| 47 | 49 | | `on.change-request` | mapping or empty | no | none | Change-request actions that trigger the workflow. | | |
| 48 | 50 | | `on.issue` | mapping or empty | no | none | Issue actions that trigger the workflow. | | |
| 49 | 51 | | `on.comment` | mapping or empty | no | none | Comment actions that trigger the workflow. | | |
| 52 | | `on.change-request.mentioned` | string or list | no | none | Body must mention one of these accounts. | | ||
| 53 | | `on.change-request.author` | mapping, string or list | no | none | Sender name allowlist and/or minimum role. | | ||
| 54 | | `on.issue.mentioned` | string or list | no | none | Body must mention one of these accounts. | | ||
| 55 | | `on.issue.assigned-to` | string or list | no | none | This event must assign one of these accounts. | | ||
| 56 | | `on.issue.author` | mapping, string or list | no | none | Sender name allowlist and/or minimum role. | | ||
| 57 | | `on.comment.mentioned` | string or list | no | none | Body must mention one of these accounts. | | ||
| 58 | | `on.comment.replied-to` | string or list | no | none | Parent comment must be by one of these accounts. | | ||
| 59 | | `on.comment.author` | mapping, string or list | no | none | Sender name allowlist and/or minimum role. | | ||
| 50 | 60 | | `on.schedule` | list of mappings | no | none | Cron schedules, in UTC. | | |
| 51 | 61 | | `on.workflow-dispatch` | mapping or empty | no | none | A manual run, optionally with typed inputs. | | |
| 52 | 62 | | `jobs` | mapping | yes | — | One or more jobs, keyed by job ID. | | |
| @@ -203,8 +213,10 @@ on: | |||
| 203 | 213 | types: [opened, closed] | |
| 204 | 214 | ``` | |
| 205 | 215 | ||
| 206 | Actions are `opened`, `edited`, `closed`, and `reopened`. The default is `[opened]`. | ||
| 207 | An empty value means the default. | ||
| 216 | Actions are `opened`, `edited`, `assigned`, `closed`, and `reopened`. The default is `[opened]`. | ||
| 217 | An empty value means the default. `assigned` is queued when an edit adds an | ||
| 218 | assignee. An issue opened with an assignee already set queues `opened`, and its | ||
| 219 | `assignees_added` list makes that an assignment for `assigned-to`. | ||
| 208 | 220 | ||
| 209 | 221 | ### `on.comment` | |
| 210 | 222 | ||
| @@ -220,6 +232,88 @@ on: | |||
| 220 | 232 | Actions are `created`, `edited`, and `deleted`. The default is `[created]`. An | |
| 221 | 233 | empty value means the default. | |
| 222 | 234 | ||
| 235 | ### Event filters | ||
| 236 | |||
| 237 | `on.change-request`, `on.issue`, and `on.comment` accept filter fields beside | ||
| 238 | `types`. They select within the event's action list; they do not change which | ||
| 239 | actions the trigger has to declare. | ||
| 240 | |||
| 241 | ```yaml | ||
| 242 | on: | ||
| 243 | issue: | ||
| 244 | types: [opened, assigned] | ||
| 245 | assigned-to: [coding-agent] | ||
| 246 | comment: | ||
| 247 | types: [created] | ||
| 248 | mentioned: [coding-agent] | ||
| 249 | replied-to: [coding-agent] | ||
| 250 | author: | ||
| 251 | name: [keenan] | ||
| 252 | role: maintain | ||
| 253 | ``` | ||
| 254 | |||
| 255 | | Field | Availability | Meaning | | ||
| 256 | |---|---|---| | ||
| 257 | | `mentioned` | change request, issue, comment | The event body names one of these accounts. | | ||
| 258 | | `replied-to` | comment | The comment answers a comment written by one of these accounts. | | ||
| 259 | | `assigned-to` | issue | This event added one of these accounts as an assignee, including assignees set when the issue was opened. | | ||
| 260 | | `author.name` | change request, issue, comment | The account that caused the event is one of these. | | ||
| 261 | | `author.role` | change request, issue, comment | The account that caused the event holds at least this repository role. | | ||
| 262 | |||
| 263 | The account filters (`mentioned`, `replied-to`, `assigned-to`, and `author.name`) | ||
| 264 | take one account or a list of accounts, at most 10. Names follow the account-name | ||
| 265 | rule: 2–32 characters, lowercase letters, digits, `-` and `_`. A leading `@` is | ||
| 266 | accepted and removed. An explicitly empty list is rejected because a filter that | ||
| 267 | can never match has no visible symptom. | ||
| 268 | |||
| 269 | `author` may also be written as one account or a list, which is shorthand for | ||
| 270 | `author.name`: | ||
| 271 | |||
| 272 | ```yaml | ||
| 273 | author: keenan | ||
| 274 | author: [keenan, wilbur] | ||
| 275 | ``` | ||
| 276 | |||
| 277 | `author.name`, `author.role`, and `assigned-to` must match when present. | ||
| 278 | `mentioned` and `replied-to` are alternatives: a comment qualifies if it mentions | ||
| 279 | an account or answers an account, so a workflow that should run for either can | ||
| 280 | declare both. A comment is never treated as addressed to its own author, which | ||
| 281 | keeps an agent's reply from waking itself. | ||
| 282 | |||
| 283 | `author.role` is the ACL filter. Its value is one role — `read`, `contribute`, | ||
| 284 | `maintain`, or `admin` — and it means "at least this role" for the effective | ||
| 285 | repository role of the account that caused the event. A `maintain` filter admits | ||
| 286 | maintainers and admins and refuses contributors and readers. `none` is rejected | ||
| 287 | because it would filter nothing. Use it when the rule is a capability rather than | ||
| 288 | a list of names: | ||
| 289 | |||
| 290 | ```yaml | ||
| 291 | on: | ||
| 292 | comment: | ||
| 293 | types: [created] | ||
| 294 | mentioned: [coding-agent] | ||
| 295 | author: | ||
| 296 | role: maintain | ||
| 297 | ``` | ||
| 298 | |||
| 299 | The role is resolved when the event is queued, from the repository's access rules | ||
| 300 | and the instance-wide role attached to them. Changing the rules later does not | ||
| 301 | change a run that is already queued. | ||
| 302 | |||
| 303 | `author.role` is a policy gate on the recorded sender, not a substitute for | ||
| 304 | authentication. Contributors reach the metadata branch through the browser, which | ||
| 305 | records their session account, and writing that branch directly already requires | ||
| 306 | maintain. An above-maintain role is therefore not protection against a malicious | ||
| 307 | maintainer with direct push access. | ||
| 308 | |||
| 309 | The mention syntax is `@name`. Mentions inside inline code or a fenced code block | ||
| 310 | are ignored, as is the `@` in an email address or a URL. A body contributes at | ||
| 311 | most 32 distinct mentions to the event. | ||
| 312 | |||
| 313 | A filter is evaluated when the event is queued. `author` names the person whose | ||
| 314 | write caused the event: the comment author, the issue author or editor, or the | ||
| 315 | maintainer who assigned the issue. | ||
| 316 | |||
| 223 | 317 | ### `on.schedule` | |
| 224 | 318 | ||
| 225 | 319 | Cron schedules in UTC. A schedule queues the workflow at the default branch tip. | |
| @@ -286,8 +380,10 @@ program, never by interpolating it into a shell command. Common fields are | |||
| 286 | 380 | `event`, `action`, `repository`, `ref`, `branch`, `commit`, `sender`, and for a | |
| 287 | 381 | change request `base_sha`, `head_sha`, and `changed_files`. The entity is under | |
| 288 | 382 | `issue`, `change_request`, or `comment`; a manual run puts its resolved values | |
| 289 | under `inputs`. Long bodies are clipped at 16 KiB and the payload marks that with | ||
| 290 | `body_truncated`. | ||
| 383 | under `inputs`. An issue or change request carries `mentions` in its entity. An | ||
| 384 | issue also carries `assignees_added` and `assignees_removed`. A comment carries | ||
| 385 | `mentions`, `reply_to_author`, and `reply_to`. Long bodies are clipped at 16 KiB | ||
| 386 | and the payload marks that with `body_truncated`. | ||
| 291 | 387 | ||
| 292 | 388 | These variables are set by the runner and cannot be replaced by a workflow's | |
| 293 | 389 | `env:`, the same rule as `CI` and `HOME`. | |