github / github/gh-aw

Built-in GitHub labels for promoting and demoting object integrity

Open
#29,390 5 comments 1 reaction 2 assignees Claimed by @lpcox View on GitHub
enhancement security threat-detection
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.