Built-in GitHub labels for promoting and demoting object integrity
- Dominant language
- Go
- Stars
- 5.1k
- Forks
- 541
- Avg merge
- 5h 46m
- Merged PRs (30d)
- 760
Description
## Summary
Introduce a set of well-known GitHub labels that automatically promote or demote the integrity of issues, pull requests, and discussions without requiring explicit `approval-labels` configuration in the workflow policy.
## Motivation
Today, workflow authors can configure `approval-labels` in their policy to promote specific items to `approved` integrity. This works, but it requires every workflow author to independently discover and configure the feature. A set of built-in labels would provide:
1. **Zero-config moderation** — Maintainers can immediately control what agents see by applying a label in the GitHub UI, without touching workflow configuration.
2. **Consistent vocabulary** — A shared set of labels across the ecosystem means maintainers learn one set of conventions that works everywhere.
3. **Bidirectional control** — Both promotion (raise integrity) and demotion (lower integrity) from labels, complementing the existing reaction-based mechanism.
## Proposed Built-in Labels
### Promotion labels (raise integrity to `approved`)
| Label | Effect |
|-------|--------|
| `agent-approved` | Promote item to `approved` integrity |
| `agent-safe` | Promote item to `approved` integrity |
### Demotion labels (cap integrity at a lower level)
| Label | Effect |
|-------|--------|
| `agent-blocked` | Cap integrity at `none` (effectively hide from agent) |
| `agent-unsafe` | Cap integrity at `none` |
| `agent-ignore` | Cap integrity at `none` |
## Semantics
- **Demotion overrides promotion**: If both a promotion and demotion label are present, demotion wins (same precedence rule as disapproval reactions overriding endorsement).
- **Demotion overrides author association**: An `agent-blocked` label on an issue from a `COLLABORATOR` would still cap it at `none`.
- **Blocked users still take precedence**: Content from `blocked-users` remains unconditionally denied regardless of labels.
- **Labels are additive to policy**: Built-in labels work alongside any `approval-labels` configured in the policy. Policy-configured labels and built-in labels compose naturally.
## Interaction with existing features
| Feature | Interaction |
|---------|-------------|
| `approval-labels` (policy) | Built-in labels extend the set; policy labels remain supported |
| `endorsement-reactions` | Reactions and labels compose; demotion label overrides endorsement reaction |
| `disapproval-reactions` | Both apply; whichever produces the lower integrity wins |
| `blocked-users` | Blocked users always win over any label |
| `trusted-users` / `trusted-bots` | Demotion label can override trusted-user elevation |
## Implementation notes
- The built-in label set should be defined in the guard (`rust-guard/src/labels/helpers.rs`) alongside the existing `has_approval_label` check.
- A new `has_demotion_label` helper would check for built-in demotion labels.
- Evaluation order in `apply_all_adjustments`: author_association → trusted users → approval labels → **built-in promotion labels** → endorsement reactions → **built-in demotion labels** → disapproval reactions → blocked users.
- The built-in labels should be recognizable in the GitHub UI — consider auto-creating them via the workflow or documenting them for maintainers.
## Open questions
- Should the exact label names be configurable (with these as defaults), or strictly fixed?
- Should there be a `merged`-level promotion label, or is `approved` sufficient?
- Should demotion labels support configurable cap levels (e.g., `agent-demote-unapproved`) or just always cap at `none`?
- Should the feature be opt-in (enabled by a policy flag) or always-on when integrity filtering is active?
Contributor guide
Assessment
This issue has not been assessed yet.