Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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/security-pin-only-commit-provenance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The `auto_merge.human_merge_pin_only` exception now verifies the commits behind the head, not only the PR author login: every commit must be authored by a `trusted_authors` login, committed by GitHub itself (`web-flow`) or a `trusted_authors` login, and carry a GitHub-verified signature (which binds to the committer, not the author), and the list must end at the current head. Before, anyone with write access could push a pin-shaped commit onto a trusted author's branch (a `dependabot/...` branch keeps `dependabot[bot]` as PR author) and have the sweep or `/approve` waive the human-merge-path hold on it. Unsigned or foreign commits, an unreadable or empty commit list, or a list that does not end at the head now hold the PR as before; the commit list is read only once the diff already qualifies, so refused PRs cost no extra API call.
30 changes: 25 additions & 5 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,9 +180,26 @@ only after a lane's human-merge-path gate, so queued PRs inherit the exception.
does not hold a PR on its human-merge-path matches when the repo has an enabled
entry, the PR author is in `trusted_authors` (case-insensitive login match),
GitHub's reported changed-file count is present and equals the fetched list,
and the classifier accepts the diff. The check reuses the file list the path
gate already fetches, so it costs no extra API call; a repo without an enabled
entry behaves exactly as before. `/hive approve` applies the same check, so its
the classifier accepts the diff, and every commit behind the head is a
trusted author's: the PR's commit list must end at the current head and each
commit must have an author login in `trusted_authors`, a committer login that
is either GitHub's own `web-flow` or in `trusted_authors`, **and** a signature
GitHub reports as verified. The PR author login only records who opened the
PR; any principal with write access can push onto that branch afterwards, and
a locally crafted commit can carry a bot's author email. GitHub verifies a
signature against the committer's email only, so a verified signature proves
the committer, not the author; a write-access principal with their own signing
key could otherwise sign a commit authored as a bot. Requiring the committer to
be `web-flow` (GitHub created and signed the commit, so GitHub set its author)
or a trusted login (a human trusted author signing locally) is what ties the
commit to the listed identity, since a spoofed committer email is not on the
signer's account and fails verification. Dependabot and Renovate commits are
web-flow committed and signed; a human trusted author must commit and sign as
themselves. A commit list that cannot be fetched, is empty, is longer than
GitHub serves, or does not end at the head holds the PR. The diff check reuses the file list the
path gate already fetches, so a PR the classifier refuses costs no extra API
call; the commit list is read only once the diff qualifies. A repo without an
enabled entry behaves exactly as before. `/hive approve` applies the same check, so its
reply never contradicts the lane. Any other outcome holds the PR as before.
The exception only prevents a new path hold: a PR that already carries `hold`
stays held until a person (or the #16269 release integration) clears it.
Expand Down Expand Up @@ -210,8 +227,11 @@ permission/credential/signing text and non-pin edits fail closed.

This classifier proves **syntax only**, not authenticated identity, exact-head
binding, file-list completeness, semantic interpretation or review of upstream
references. The sweep supplies the author (GitHub's PR author login) and
file-list completeness itself; the relay integration remains #16265;
references. The sweep supplies the author (GitHub's PR author login), the
verified-commit provenance of the head and file-list completeness itself; it
does not yet anchor a replaced action SHA to the upstream action's own refs
(GitHub resolves `uses:` SHAs across the fork network; the open second item
of #16399); the relay integration remains #16265;
attribution and safe hold release are tracked in #16269. None of the
schema or classifier APIs grants permission to merge or clears a hold. Native
required checks and producer bindings, freshness, current reviews, substantive
Expand Down
4 changes: 2 additions & 2 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through
| `project.label_driven_supersede_park_actors` | `[]` (off) | Automation logins (for example a lifecycle bot running as `github-actions[bot]`) whose park labels a later trusted acceptance supersedes on label-driven repos: Hive removes the label, says so in the release comment, and releases the issue ([#13605](https://github.com/hivecommons/hive/issues/13605)). Park labels added by people, by unlisted bots, or by a listed bot after the acceptance still block; `hold` is never superseded. Per-repo override: `project.repo_policies[].label_driven_supersede_park_actors`. |
| `auto_merge.allow_unprotected_base` | Deprecated no-op. | Accepted so older configs keep loading. `hive-merge` now merges into any protected or unprotected branch the App can write, subject to the CI-evidence gate and GitHub's own merge rules. |
| `auto_merge.no_ci_ok` | Empty by default. | Explicit repo list whose zero-CI merge-request verdict may pass; failing or pending CI evidence is still enforced. |
| `auto_merge.human_merge_pin_only` | Unset (off); enforced by the automerge sweep lanes and `/approve` (#16266), **not yet by the `hive-merge` relay** (#16265). | Per-repo schema for `enabled`, `paths`, `kinds` (`action-sha`, `image-digest`, `version-pin`) and `trusted_authors`. Enabled entries require all three lists. The sweep does not place a human-merge-path hold on a PR whose author is in `trusted_authors` and whose complete diff (every changed file, guarded or not) is pin replacements; it never clears an existing hold. See [hive-merge.md](../hive-merge.md) for grammar, restrictions and outstanding integration/deployment requirements (#16242). |
| `auto_merge.human_merge_pin_only` | Unset (off); enforced by the automerge sweep lanes and `/approve` (#16266), **not yet by the `hive-merge` relay** (#16265). | Per-repo schema for `enabled`, `paths`, `kinds` (`action-sha`, `image-digest`, `version-pin`) and `trusted_authors`. Enabled entries require all three lists. The sweep does not place a human-merge-path hold on a PR whose author is in `trusted_authors`, whose complete diff (every changed file, guarded or not) is pin replacements, and whose every commit is authored by a `trusted_authors` login with a GitHub-verified signature; it never clears an existing hold. See [hive-merge.md](../hive-merge.md) for grammar, restrictions and outstanding integration/deployment requirements (#16242). |
| `auto_merge.human_merge_paths` | Unset (off). | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge. Applies to every merge lane (App self-merge, trusted-author, label-queued, merge-request relay) whatever the intent tier; a matching PR is held with one comment, and an incomplete changed-file list fails closed. Details in the sweep key table below. |
| `auto_merge.human_merge_title_prefixes` | `["⚠️", "⚠"]` | Title prefixes (after trimming) that mark a PR as a breaking change a person must merge. Every auto-merge lane and the merge train skip the PR; the tracker parks it at 090 *Ready for human merge · human merge*. Set to `[]` to disable. |
| `auto_merge.human_merge_labels` | `["needs-owner-merge"]` | Labels (case-insensitive) that mark a PR a person must merge; same effect as the title prefixes. Set to `[]` to disable. |
Expand Down Expand Up @@ -527,7 +527,7 @@ auto_merge:
| `enabled` | Absent/false preserves the existing human-merge-path gate. |
| `paths` | Explicit allowed paths within the protected path matches, not a replacement for `human_merge_paths`. Required when enabled. |
| `kinds` | Explicit subset of `action-sha`, `image-digest`, `version-pin`; unknown kinds rejected. Required when enabled. |
| `trusted_authors` | Explicit authenticated author allowlist; required when enabled. Not permission to trust arbitrary bot-looking logins. |
| `trusted_authors` | Explicit author allowlist; required when enabled. Matched against the PR author login and against the author login of every commit behind the head; each commit must also be committed by GitHub (`web-flow`) or by a trusted login and carry a GitHub-verified signature, since GitHub verifies the committer, not the author (web-flow-committed bot commits qualify; human authors must commit and sign as themselves). Not permission to trust arbitrary bot-looking logins. |

Edit the controller's active `hive.yaml` seed, not the consumer image repo.
The config file watcher loads the seed plus dashboard overlay after a debounced
Expand Down
9 changes: 6 additions & 3 deletions src/pkg/config/automerge_pin_only.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,12 @@ import (

// PinOnlyException is policy wired in Engine.SetHumanMergePinOnly and
// enforced by the automerge sweep and /approve gates via humanMergePinOnlyExempt
// (#16266). It proves trusted PR author, complete file list, and SHA-bound merge,
// but not upstream review (separate gates handle that). The hive-merge relay does
// not yet apply it (#16265).
// (#16266). It proves trusted PR author, complete file list, SHA-bound merge,
// and commit provenance: every commit behind the head must have a trusted
// author login, a committer that is GitHub itself (web-flow) or a trusted
// login, and a GitHub-verified signature (#16399). It does not prove upstream
// review (separate gates handle that). The hive-merge relay does not yet apply
// it (#16265).
type PinOnlyException struct {
Enabled bool `yaml:"enabled" json:"enabled"`
Paths []string `yaml:"paths" json:"paths"`
Expand Down
128 changes: 110 additions & 18 deletions src/pkg/github/automerge/automerge_human_paths.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,15 @@ package automerge

import (
"context"
"fmt"
"strings"

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/config"
hgithub "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/intent"
"github.com/hivecommons/hive/pkg/stageengine/prstage"
"github.com/hivecommons/hive/pkg/stagelabels"
)

// Skip reasons reported by the human-merge-path gate (#11038).
Expand Down Expand Up @@ -76,16 +78,20 @@ func (c *Engine) currentHumanMergePinOnly(repo string) (config.PinOnlyException,
}

// humanMergePinOnlyExempt reports whether the opt-in pin-only exception
// waives the human-merge-path matches of pr. It needs no API call: files is
// the complete list the caller already fetched for the path check. It returns
// (false, "") when the repo has no enabled exception, and (false, reason) when
// the exception is configured but this PR does not qualify.
// waives the human-merge-path matches of pr. files is the complete list the
// caller already fetched for the path check, so a PR the classifier refuses
// costs no further API call. It returns (false, "") when the repo has no
// enabled exception, and (false, reason) when the exception is configured but
// this PR does not qualify.
//
// The classifier receives the FULL changed-file list, so a pin bump that also
// edits any other file (even an unguarded changelog or doc) is not pin-only
// and stays held (#16326). The sweep lanes and /approve share this helper so
// and stays held (#16326). Once the diff is accepted, every commit behind the
// head must itself be provably the trusted author's: the PR author login only
// says who opened the PR, and any principal with write access can push onto
// that branch afterwards. The sweep lanes and /approve share this helper so
// they never disagree.
func (c *Engine) humanMergePinOnlyExempt(owner, repo string, pr *gh.PullRequest, files []intent.ChangedFile, matches []string) (bool, string) {
func (c *Engine) humanMergePinOnlyExempt(ctx context.Context, owner, repo string, pr *gh.PullRequest, files []intent.ChangedFile, matches []string) (bool, string) {
if len(matches) == 0 || pr == nil {
return false, ""
}
Expand All @@ -94,22 +100,108 @@ func (c *Engine) humanMergePinOnlyExempt(owner, repo string, pr *gh.PullRequest,
return false, ""
}
author := strings.TrimSpace(hgithub.SafeGetLogin(pr.GetUser()))
trusted := false
for _, login := range policy.TrustedAuthors {
if author != "" && strings.EqualFold(strings.TrimSpace(login), author) {
trusted = true
break
}
}
if !trusted {
if !pinOnlyTrustedLogin(policy, author) {
return false, "PR author is not in trusted_authors"
}
// ListChangedFiles already refuses a list shorter than GitHub's count;
// the exception additionally requires that count to be present and exact.
if reported := pr.GetChangedFiles(); reported <= 0 || reported != len(files) {
return false, "complete changed-file list not proven"
}
return intent.ClassifyPinOnly(files, matches, policy.Spec())
if ok, why := intent.ClassifyPinOnly(files, matches, policy.Spec()); !ok {
return false, why
}
if why := c.pinOnlyCommitsTrusted(ctx, owner, repo, pr, policy); why != "" {
return false, why
}
return true, "all changes are approved pin replacements by verified trusted-author commits"
}

func pinOnlyTrustedLogin(policy config.PinOnlyException, login string) bool {
login = strings.TrimSpace(login)
if login == "" {
return false
}
for _, trusted := range policy.TrustedAuthors {
if strings.EqualFold(strings.TrimSpace(trusted), login) {
return true
}
}
return false
}

// pinOnlyCommitsMaxPages bounds the commit listing; GitHub serves at most 250
// commits for a PR, and a pin bump has one or two.
const pinOnlyCommitsMaxPages = 3

// pinOnlyCommitsTrusted returns "" when every commit of pr is attributed to a
// trusted author, was committed by a trusted login or by GitHub itself
// (web-flow), carries a signature GitHub verified, and the current head is
// the newest listed commit. GitHub verifies a signature against the
// committer's email only, so a verified commit proves the committer, not the
// author: a write-access principal with their own signing key can craft a
// commit whose author is a bot's noreply address and sign it as themselves
// (see pr_merge_state.go on verification reasons). Requiring the committer to
// be web-flow (GitHub-created and GitHub-signed, so GitHub set the author) or
// a trusted login (a human trusted author signing locally) closes that; a
// spoofed committer email fails verification because it is not on the
// signer's account. Any listing error, an empty or truncated list, or a head
// not in the list fails closed with a reason.
func (c *Engine) pinOnlyCommitsTrusted(ctx context.Context, owner, repo string, pr *gh.PullRequest, policy config.PinOnlyException) string {
head := pr.GetHead().GetSHA()
if head == "" {
return "PR head SHA unknown"
}
ctx = hgithub.WithRESTCaller(ctx, "hive:automerge_pin_only")
opts := &gh.ListOptions{PerPage: 100}
var all []*gh.RepositoryCommit
for page := 0; ; page++ {
if page == pinOnlyCommitsMaxPages {
return "PR commit list too long to verify"
}
commits, resp, err := c.gh.PullRequests.ListCommits(ctx, owner, repo, pr.GetNumber(), opts)
if err != nil {
return fmt.Sprintf("PR commits could not be listed: %v", err)
}
all = append(all, commits...)
if resp == nil || resp.NextPage == 0 {
break
}
opts.Page = resp.NextPage
}
if len(all) == 0 {
return "PR has no commits to verify"
}
if all[len(all)-1].GetSHA() != head {
return "PR commit list does not end at the current head"
}
for _, rc := range all {
sha := rc.GetSHA()
if sha == "" {
return "PR commit without a SHA"
}
if login := hgithub.SafeGetLogin(rc.GetAuthor()); !pinOnlyTrustedLogin(policy, login) {
return fmt.Sprintf("commit %s author %q is not in trusted_authors", stagelabels.ShortSHA(sha), login)
}
if committer := hgithub.SafeGetLogin(rc.GetCommitter()); !pinOnlyTrustedCommitter(policy, committer) {
return fmt.Sprintf("commit %s committer %q is neither GitHub nor in trusted_authors", stagelabels.ShortSHA(sha), committer)
}
if !rc.GetCommit().GetVerification().GetVerified() {
return fmt.Sprintf("commit %s has no GitHub-verified signature", stagelabels.ShortSHA(sha))
}
}
return ""
}

// pinOnlyWebFlowLogin is the login GitHub attaches as committer to commits it
// creates and signs itself (web UI, Apps such as Dependabot and Renovate).
const pinOnlyWebFlowLogin = "web-flow"

// pinOnlyTrustedCommitter accepts GitHub's own committer identity or a
// trusted author committing (and signing) locally; the signature check then
// binds to this identity.
func pinOnlyTrustedCommitter(policy config.PinOnlyException, login string) bool {
return strings.EqualFold(strings.TrimSpace(login), pinOnlyWebFlowLogin) || pinOnlyTrustedLogin(policy, login)
}

// humanMergePathGate refuses a PR that touches a path a person must merge.
Expand All @@ -124,8 +216,8 @@ func (c *Engine) humanMergePinOnlyExempt(owner, repo string, pr *gh.PullRequest,
// `hold`, posts the single marker-stamped comment (not reposted on later
// ticks) and returns autoMergeReasonHumanMergePath, unless the repo's enabled
// auto_merge.human_merge_pin_only exception qualifies the PR (trusted author,
// complete list, every changed line a pin replacement), which needs no extra
// API call and returns ("", nil).
// complete list, every changed line a pin replacement, every commit a
// verified trusted-author commit) and returns ("", nil).
func (c *Engine) humanMergePathGate(ctx context.Context, displayRepo, owner, repo string, pr *gh.PullRequest) (string, error) {
patterns := c.currentHumanMergePaths(owner + "/" + repo)
if len(patterns) == 0 {
Expand All @@ -140,7 +232,7 @@ func (c *Engine) humanMergePathGate(ctx context.Context, displayRepo, owner, rep
if len(matches) == 0 {
return "", nil
}
exempt, why := c.humanMergePinOnlyExempt(owner, repo, pr, files, matches)
exempt, why := c.humanMergePinOnlyExempt(ctx, owner, repo, pr, files, matches)
if exempt {
c.info("automerge sweep admitted pin-only change on human-merge paths", "repo", displayRepo, "pr", number, "paths", matches, "config", humanMergePinOnlyConfigKey, "reason", why)
return "", nil
Expand Down
Loading
Loading