Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-18453-sentinel-notice-status-card.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Sentinel: in `github.notifications.mode: quiet` (the default) the informational notice on a trusted author's PR (no label, merge not blocked) is now a `sentinel` section of the PR's `hive:status` card, edited in place, instead of a new comment per PR. A sentinel hold (`sentinel-alert` label, maintainer review required), including one from `sentinel.trusted_authors_block`, still posts its own comment, and `normal` mode is unchanged (#18453).
30 changes: 30 additions & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,6 +491,7 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | |
| `github.(*Client).closeSupersededPRDecision` | `status` | |
| `github.(*Client).fileReviewBacklog` | `status` | |
| `github.(*Client).foldSentinelNotice` | `status` | informational sentinel notice folded into the PR status card (quiet mode); a blocking alert is never folded |
| `github.(*Client).joinFleetReportIssue` | `status` | |
| `github.(*Client).markInProgressStarted` | `status` | |
| `github.(*Client).postUnblockedNote` | `status` | |
Expand Down Expand Up @@ -668,6 +669,35 @@ github:
reminder_interval: 24h # default 24h
```

### Sentinel notices in the PR status card

The sentinel (`pkg/github/sentinel_sweep.go`) has two kinds of result, and
only one of them asks a person to do anything
(hivecommons/hive#18453):

- **Actionable: a hold.** The author is untrusted, or
`sentinel.trusted_authors_block` is `true`. The hive adds the
`sentinel-alert` label and posts its `<!-- hive-sentinel --> <head>`
"Sentinel alert - maintainer review required" comment. This happens in
**every** mode, quiet included, because only a new comment notifies.
A security hold is never folded into the card.
- **Informational.** The author is trusted and the merge is not blocked. In
`github.notifications.mode: quiet` (the default) this is the `sentinel`
section of the PR's `hive:status` card, edited in place. A new head
rewrites that section, so the PR gets no notice comment at all. The card
is created only when the PR has none yet. The section is stamped
`<!-- hive-sentinel-notice <head> -->`. It never carries the
`<!-- hive-sentinel -->` marker, because the sweep reads that marker back
to tell which head it alerted on and whether a maintainer cleared it. When
the same PR is later put on hold, the hive posts the alert comment and
drops the stale informational section from the card. A PR that already
has a sentinel comment from before this change keeps it, rewritten in
place for the new head.

In `normal` mode the informational notice is still its own comment, as
before. Either way the finding is recorded for audit, the dashboard
Security tab and `/api/sentinel`.

### Hive-maintained Actions workflows that defer to the card

Some comments come from GitHub Actions workflows in this repository rather
Expand Down
12 changes: 10 additions & 2 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -587,6 +587,11 @@ post on issues and merged PRs as comments of their own:
- a contributor's **claim marker** (`<!-- hive:claim … -->`) posted by the
contribute hub — claim readers scan every hive comment body for the
marker, so the section is as authoritative as the comment was;
- the sentinel's **informational notice** for a trusted author's PR (no
label, merge not blocked), as a `sentinel` section stamped
`<!-- hive-sentinel-notice <head> -->`. A sentinel **hold**
(`sentinel-alert` label, maintainer review required) is never folded: it
always posts its own `<!-- hive-sentinel -->` comment (hivecommons/hive#18453);
- an agent's relayed **status notes**: `hive/awaiting-ci: …`, `Parking on
stage/045-needs-decision: …` and `Already fixed …`. Any other relayed
comment — a finding, a triage verdict with evidence, a question — is still
Expand Down Expand Up @@ -696,7 +701,10 @@ auto-merge lane (dashboard queue, self-authored App sweep, trusted bot authors,
or trusted authors). Trusted authors (the Hive App, configured trusted bots and
owner/trusted-author allow-list entries) default to an informational notice and
audit/dashboard finding only; no alert label is added unless the operator opts
into blocking them. A maintainer who removes the label keeps the PR clear until
into blocking them. In `github.notifications.mode: quiet` (the default) that
informational notice is a `sentinel` section of the PR's `hive:status` card,
edited in place, rather than a comment; an alert that needs a maintainer always
gets its own comment ([#18453](https://github.com/hivecommons/hive/issues/18453)). A maintainer who removes the label keeps the PR clear until
the author pushes again: the sweep reads the clearance back from the alert
comment it left for that head (alert comment present, label absent), so it
survives a hub restart or a second replica and nothing else needs to be posted.
Expand All @@ -723,7 +731,7 @@ push re-arms it.
|---|---|---|
| `sentinel.enabled` | **on** when unset | `false` disables the sweep entirely. |
| `sentinel.label` | `sentinel-alert` | Label added to untrusted flagged PRs (created red if missing). Neutral on purpose: it means "look closely", not "malicious". This configured label is also added to Hive's hold/exclude set and blocks Hive approval plus every auto-merge lane until a human removes it. |
| `sentinel.trusted_authors_block` | `false` | When `false`, trusted author findings are notice-only: comment, audit/dashboard record, no label, no approval/merge block. Set `true` to add the blocking label for trusted authors too. |
| `sentinel.trusted_authors_block` | `false` | When `false`, trusted author findings are notice-only: audit/dashboard record, no label, no approval/merge block. The notice is the `sentinel` section of the PR's `hive:status` card in `github.notifications.mode: quiet` (the default) and its own comment in `normal` mode. Set `true` to add the blocking label and post the alert comment for trusted authors too. |
| `sentinel.sensitive_paths` | shipped defaults (`sentinel.DefaultSensitivePaths`) | Glob list (same syntax as `intent.guardrail_path_patterns`; `**` crosses directories) that **replaces** the defaults when set. Defaults cover OWNERS/CODEOWNERS/MAINTAINERS, SECURITY.md, GOVERNANCE.md, `.github/workflows/**`, actions, dependabot, codeql, rulesets, CI config, Makefile/Justfile, pre-commit hooks, `policies/**`, `hive.yaml*`, `gh-wrapper*`, proxy rules, Dockerfiles, `install.sh`, dependency manifests and lockfiles, release workflows, `.env*`/key material, `deploy/**`, Terraform, Helm/k8s manifests. |
| `sentinel.disabled_behaviors` | empty | Rule names from the table above to switch off. Unknown names are rejected. |
| `sentinel.exempt_logins` | empty | GitHub logins never flagged (e.g. a release bot). Use sparingly. |
Expand Down
1 change: 1 addition & 0 deletions src/pkg/github/notification_write_sites.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ var notificationWriteSites = map[string]NotificationWriteSite{
"github.(*Client).closeIssueForMergedPRClaimWithIssue": {Class: NotificationClassStatus},
"github.(*Client).closeSupersededPRDecision": {Class: NotificationClassStatus},
"github.(*Client).fileReviewBacklog": {Class: NotificationClassStatus},
"github.(*Client).foldSentinelNotice": {Class: NotificationClassStatus},
"github.(*Client).joinFleetReportIssue": {Class: NotificationClassStatus},
"github.(*Client).markInProgressStarted": {Class: NotificationClassStatus},
"github.(*Client).postUnblockedNote": {Class: NotificationClassStatus},
Expand Down
116 changes: 116 additions & 0 deletions src/pkg/github/sentinel_status_card.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
package github

import (
"context"
"fmt"
"sort"
"strings"

"github.com/hivecommons/hive/pkg/sentinel"
)

// Sentinel notices in the status card (hivecommons/hive#18453).
//
// A sentinel result is one of two kinds:
//
// - actionable: the finding blocks (untrusted author, or
// sentinel.trusted_authors_block), so the alert label goes on and a
// maintainer has to review or clear it. That always gets its own
// `<!-- hive-sentinel -->` comment, in every notification mode, because
// a new comment is the only write that notifies anyone.
// - informational: the author is trusted and the merge is not blocked.
// Nobody has to act. In github.notifications.mode: quiet this becomes the
// `sentinel` section of the PR's hive:status card, edited in place, so a
// trusted author's PR is not emailed a notice per head. In normal mode it
// is still its own comment, as before.
//
// The card section carries SentinelNoticeCardMarker, never SentinelMarker:
// the sweep reads its own sentinel comment back (which head it alerted on,
// whether a maintainer cleared it), and a card that carried that marker
// would be read as the sentinel comment and could be rewritten into an
// alert that notifies nobody.
const (
// SentinelStatusKey is the hive:status section holding the
// informational sentinel notice in quiet mode.
SentinelStatusKey = "sentinel"
// SentinelNoticeCardMarker stamps the card section with the head it
// describes. It deliberately does not contain SentinelMarker.
SentinelNoticeCardMarker = "<!-- hive-sentinel-notice"
// sentinelCardMaxPaths bounds how many paths one rule lists in the card
// section; the full list stays on the dashboard and /api/sentinel.
sentinelCardMaxPaths = 5
)

// sentinelFoldsNotice reports whether an informational (non-blocking)
// sentinel notice goes into the status card rather than a comment of its
// own. It folds only in quiet mode, and only when the PR carries no earlier
// sentinel comment of the hive's: that comment is edited in place for the
// new head (no notification) so the PR never shows a stale notice next to
// the card.
func (c *Client) sentinelFoldsNotice(hasPriorComment bool) bool {
return c.notificationsQuiet() && !hasPriorComment
}

// foldSentinelNotice writes the informational notice for head as the
// sentinel section of repo#number's status card. The card is created only
// when the PR has none; every later write is an in-place edit.
func (c *Client) foldSentinelNotice(ctx context.Context, repo string, number int, head string, decision SentinelDecision, findings []sentinel.Finding) error {
created, err := c.UpsertPRStatusSection(ctx, repo, number, SentinelStatusKey, SentinelStatusSection(decision, head, findings))
if err != nil {
return fmt.Errorf("folding sentinel notice into status card: %w", err)
}
if !created {
c.noteCommentSuppressed()
}
return nil
}

// clearSentinelNoticeSection drops a stale informational section once the
// same PR is alerted on, so the card never says "merge is not blocked" next
// to an alert label. Removing a section never creates a card. Best effort:
// the alert comment has already been posted and is what matters.
func (c *Client) clearSentinelNoticeSection(ctx context.Context, repo string, number int) {
if !c.notificationsQuiet() {
return
}
if _, err := c.UpsertPRStatusSection(ctx, repo, number, SentinelStatusKey, ""); err != nil {
c.logger.Warn("sentinel: clearing informational status-card section failed", "repo", repo, "number", number, "error", err)
}
}

// SentinelStatusSection is the status-card text for an informational
// sentinel notice: one line naming the trust reason and head, then each
// matched rule with up to sentinelCardMaxPaths paths. It names no login, so
// it notifies nobody even before the writer neutralises mentions.
func SentinelStatusSection(decision SentinelDecision, head string, findings []sentinel.Finding) string {
reason := strings.TrimSpace(decision.TrustedReason)
if reason == "" {
reason = "trusted author"
}
var b strings.Builder
fmt.Fprintf(&b, "%s %s -->\n", SentinelNoticeCardMarker, head)
fmt.Fprintf(&b, "ℹ️ **Sentinel:** informational, author is trusted (%s), merge is not blocked. Head `%s` matched:\n", reason, shortSHA(head))
for _, f := range findings {
fmt.Fprintf(&b, "- `%s`: %s", f.Rule, f.Summary)
paths := append([]string(nil), f.Paths...)
sort.Strings(paths)
if len(paths) > 0 {
shown := paths
if len(shown) > sentinelCardMaxPaths {
shown = shown[:sentinelCardMaxPaths]
}
quoted := make([]string, 0, len(shown))
for _, p := range shown {
quoted = append(quoted, "`"+p+"`")
}
fmt.Fprintf(&b, " (%s", strings.Join(quoted, ", "))
if extra := len(paths) - len(shown); extra > 0 {
fmt.Fprintf(&b, ", +%d more", extra)
}
b.WriteString(")")
}
b.WriteString("\n")
}
fmt.Fprintf(&b, "\nNo `%s` label was added. The finding is recorded in the dashboard Security tab and `/api/sentinel`; set `%s.trusted_authors_block: true` to block trusted authors too.", decision.Label, SentinelConfigKey)
return b.String()
}
Loading
Loading