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/added-repo-policy-sentinel-fence-overrides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Sentinel's sensitive-path list and the contributor lane's workflow fence scope can be set per repository.** Two opt-in hive.yaml keys under `project.repo_policies`, `sentinel_sensitive_paths` and `workflow_fence_scope`, replace `sentinel.sensitive_paths` and `auto_merge.contributor_lane.workflow_fence_scope` for one repository, so an operator can loosen (or tighten) them where the maintainers agreed without changing repositories that belong to someone else. A repository without the key behaves exactly as before, and a later change to the hive-wide value does not reach a repository that has its own. An explicit empty sensitive-path list matches nothing, as the hive-wide key does; `human_merge_paths` scope still keeps the full fence for a repository with no `human_merge_paths` entry. An invalid override stops the config from loading, and the running hive treats one that gets through as unset. Settings → Security → Suspicious Activity and Settings → Features → Auto Merge list the overrides (read-only), `settings_read` returns them, and the admin MCP `sentinel.settings` preview names every repository with its own list, what that list leaves out, and refuses a stale confirm if an override changed. See [hive-merge.md](src/docs/hive-merge.md#contributor-lane-auto-merge).
13 changes: 13 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -1396,6 +1396,19 @@ func sentinelSweepOptions(cfg *config.Config, ghClient *github.Client, dashSrv *
}
dashSrv.AuditLogRecord("system", action, detail, "", event.Repo, event.Number)
},
// Per-repo sensitive paths (project.repo_policies[].sentinel_sensitive_paths).
SensitivePathsForRepo: sentinelRepoSensitivePathsFunc(cfg),
}
}

// sentinelRepoSensitivePathsFunc resolves Sentinel's sensitive-path globs for
// one "owner/repo": its project.repo_policies[].sentinel_sensitive_paths
// override, else the hive-wide sentinel.sensitive_paths (or the shipped
// defaults).
func sentinelRepoSensitivePathsFunc(cfg *config.Config) func(repo string) []string {
return func(repo string) []string {
paths, _ := cfg.RepoSentinelSensitivePaths(repo)
return paths
}
}

Expand Down
11 changes: 11 additions & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -114,10 +114,21 @@ func contributorLanePolicyFunc(cfg *config.Config) func() automerge.ContributorL
ApproveHeldRunsForRegistryTrusted: p.EffectiveApproveHeldRunsForRegistryTrusted(),
OwnerApprovalReleasesWorkflowFence: p.EffectiveOwnerApprovalReleasesWorkflowFence(),
WorkflowFenceScope: p.EffectiveWorkflowFenceScope(),
WorkflowFenceScopeForRepo: repoWorkflowFenceScopeFunc(cfg),
}
}
}

// repoWorkflowFenceScopeFunc resolves the contributor lane's workflow fence
// scope for one "owner/repo": its project.repo_policies[].workflow_fence_scope
// override, else the hive-wide auto_merge.contributor_lane.workflow_fence_scope.
func repoWorkflowFenceScopeFunc(cfg *config.Config) func(repo string) string {
return func(repo string) string {
scope, _ := cfg.RepoWorkflowFenceScope(repo)
return scope
}
}

// stageLabelPolicyFunc reads governor.labels.stage live so a config reload
// turns the stage reconciler on/off and re-times dwell without a restart.
func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy {
Expand Down
7 changes: 6 additions & 1 deletion src/docs/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -752,7 +752,12 @@ other role.
`needs_decision`, `needs_spec`), and `reporter_trust` (`enabled`,
`trusted_associations`, `trusted_logins`, `untrusted_require_labels`).
- `sentinel.settings` changes Sentinel's `sensitive_paths`,
`disabled_behaviors`, `exempt_logins` and `trusted_authors_block`.
`disabled_behaviors`, `exempt_logins` and `trusted_authors_block`. A
repository with its own list
(`project.repo_policies[].sentinel_sensitive_paths`, set in hive.yaml)
keeps it: the preview names those repositories and the hive-wide globs
their lists leave out, and does not change them. A per-repository list
added or changed after the preview refuses the confirm.

Each list takes a change, not a new list: `{"add": [...], "remove": [...]}`,
or `{"clear": true}` to empty it first. For example, to turn reporter trust on
Expand Down
24 changes: 24 additions & 0 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -1116,6 +1116,30 @@ A PR merges through this tier only when all of the following hold:
content rules (permission widening, secret exposure, CI-gate weakening,
remote code execution) still read every workflow patch (see
[Suspicious-activity alerts](operator-reference/sweeps-and-operations.md#suspicious-activity-alerts-sentinel)).

Both keys can be set for one repository instead of the whole hive, for
example when some repositories belong to maintainers who have not agreed
to the looser setting. Under `project.repo_policies`,
`workflow_fence_scope` replaces the hive-wide scope and
`sentinel_sensitive_paths` replaces the hive-wide Sentinel list, for that
repository only. Either can be stricter or looser than the hive-wide
value, and a later change to the hive-wide value does not reach a
repository that has its own. A repository with `human_merge_paths` scope
but no `human_merge_paths` entry still keeps the full fence. An invalid
value stops the config from loading, and the running hive ignores one
that gets through and uses the hive-wide value. The overrides are set in
hive.yaml; Settings and `settings_read` list them.

```yaml
project:
repo_policies:
- repo: website
workflow_fence_scope: human_merge_paths
sentinel_sensitive_paths: # replaces sentinel.sensitive_paths for this repository
- OWNERS
- CODEOWNERS
- .github/workflows/release*.yml
```
- The diff does not delete a test file or remove 25+ test lines while
deleting at least 3× what it adds (`contributor-lane:tests-removed`).
- Required CI is green on the current head, using the same merge-CI gate as
Expand Down
4 changes: 3 additions & 1 deletion src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,8 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through
| `project.repo_policies[].release_version_source` | Unset (version-file check disabled). | Optional repository-relative text file, for example `VERSION`, read at the proposed release target. Its trimmed value must match the proposed tag; a single leading `v` is ignored on either value. Invalid paths, unreadable content, and mismatches refuse the release while leaving the issue parked. Only used with `release_on_approve: true`. |
| `project.repo_policies[].companion_repos` | Unset (no companions). | List of sibling repositories (`name` in the project org, or `org/name`) that this repo's tooling expects checked out beside it under the agent workspace root — for example a docs/website repo a spec tool registers at `<workspace>/<org>/<sibling>/…`. Contributor task prompts and resident-agent kicks carry a shallow-clone plan for each companion at `<workspace root>/<org>/<sibling>` (`$HIVE_WORKSPACE_DIR` for contributor agents, `$HOME/workspace` for resident agents), and agents are told that a tool reporting one of those paths missing means *clone it*, never park the issue. Self-references and malformed entries are dropped. See [running-at-level-6.md](../running-at-level-6.md#needless-parks). |
| `project.repo_policies[].max_open_held_prs` | Unset (no cap) for every repo. | Per-repo cap on open hive PRs still waiting on a human ([#13645](https://github.com/hivecommons/hive/issues/13645)). `0` means the default of `12`; a positive number is the cap. At the cap `hive-open-pr` refuses new PRs in that repo and PR-opening agents are told "repo at capacity: review or close existing PRs first". Needs GitHub App auth: under a PAT the cap cannot be enforced and the governor warns once ([#13739](https://github.com/hivecommons/hive/issues/13739)). See [Open held PR cap](v6-controls.md#open-held-pr-cap-max_open_held_prs). |
| `project.repo_policies[].sentinel_sensitive_paths` | Unset: inherits `sentinel.sensitive_paths`. | This repository's own Sentinel sensitive-path list. It replaces the hive-wide list for this repository's pull requests only, so it can be stricter or looser, and a later change to `sentinel.sensitive_paths` does not reach it. An explicit empty list (`[]`) matches nothing, as the hive-wide key does. A blank pattern is rejected when the config loads. Set in hive.yaml; Settings → Security → Suspicious Activity and the admin MCP `sentinel.settings` preview name every repository with its own list. See [Suspicious-activity alerts](sweeps-and-operations.md#suspicious-activity-alerts-sentinel). |
| `project.repo_policies[].workflow_fence_scope` | Unset: inherits `auto_merge.contributor_lane.workflow_fence_scope`. | This repository's own contributor-lane workflow fence scope, `all` or `human_merge_paths`. It can be stricter or looser than the hive-wide value, and a later change to the hive-wide value does not reach it. `human_merge_paths` still keeps the full fence when the repository has no `auto_merge.human_merge_paths` entry. Any other value is rejected when the config loads. Set in hive.yaml; Settings → Features → Auto Merge lists the overrides under **Workflow fence scope**, and `settings_read` section `auto_merge` returns them as `contributor_lane.workflow_fence_scope_repos`. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `project.label_driven_approval_labels` | `["triage/accepted"]` | Labels whose trusted addition approves an issue on every label-driven repo without its own list. Ignored by repos without `label_driven: true`. Dashboard: Settings → Repos → "Default approval labels". |
| `project.label_driven_trust_org_members` | `true` | Whether a public member of the repo's owning org who applies an approval label is trusted (Prow's own rule). Dashboard: Settings → Repos → "trust public org members". |
| `project.label_driven_trusted_bots` | `["kubestellar-prow[bot]"]` | Bot logins whose label additions count as a trusted triager (Prow command bots relaying `/triage accepted`). `github-actions[bot]` is not in the default because it is the shared identity of every workflow in the repo, including ones triggered by untrusted events; operators whose Prow emulation runs as `github-actions[bot]` must add it explicitly per deployment. Dashboard: Settings → Repos → "Trusted bots". |
Expand Down Expand Up @@ -557,7 +559,7 @@ advanced into the merge path.
| `auto_merge.contributor_tier.auto_promote_after_merged` | `5` | Clean merged PRs (no revert, no sentinel label, not undone by a later merged revert) after which the contributor lane treats an author as `trusted` without an operator grant, unless the registry marks them `revoked`. Negative disables the ratchet. |
| `auto_merge.contributor_lane.approve_held_runs_for_registry_trusted` | `true` | When the registry path admitted the PR author and the lane stops at `required-check-missing:<ctx>` (or at `ci-unverified` with every `pull_request` run on the head held), approve the head's `action_required` workflow runs once per hive process (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`; only fork `pull_request` runs and Actions-bot runs, the ones GitHub accepts; a 403 is not retried until the head changes or the App gains Actions write), post one `hive:contributor-held-runs-approved` audit comment and log `contributor-lane approved held runs`. Never acts for claim-marker, auto-promoted or association admissions, sentinel/exclude-labelled PRs, or diffs touching `.github/workflows/**`. Needs the App's **Actions: Read and write** permission. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.owner_approval_releases_workflow_fence` | `true` | A hive owner / trusted merger's explicit approval on the **current** head — a GitHub `APPROVED` review on that commit, or a `/hive decision approve` (typed on the PR by the merger, or from the dashboard) bound to it — releases the contributor lane's `contributor-lane:workflow-path` fence (never for a head that also removes tests, which stays `contributor-lane:tests-removed`), so the lane merges a PR editing `.github/workflows/**` / `.github/actions/**` itself once CI, soak and the other gates are clear. The same approval answers a `requires_human` reviewer verdict on that head (a typed one is recorded as the decision, logging `typed approval recorded as the answer to the reviewer's requires_human question`); `/hive approve` answers the verdict but never releases the fence, so on the owner's own PR, where GitHub refuses the self-review, `/hive decision approve` is the one command for both ([Danathar/zfs-aurora-complex#254](https://github.com/Danathar/zfs-aurora-complex/pull/254)). Logs `workflow-path fence released by owner approval`, leaves one `hive:workflow-approval` audit comment per head, which says whether the verdict is answered; approval on an older head does not count, except across the hive's own base refresh: when only GitHub-verified App merges of the base branch (at most five) separate the approved head from the current one and the PR's three-dot diff is unchanged, the approval carries over and the lane logs `workflow-path fence approval carried over hive base refresh`. Any contributor push re-arms the fence. An unmarked approval binds to the PR `updated_at` pinned on the hive's first sweep of the head, not to the push, so one typed between the push and that sweep is judged stale and must be typed again ([#14754](https://github.com/hivecommons/hive/issues/14754)). Needs the App's **Workflows: Read and write**; without it the merge is refused, the PR is marked `hive:unauthorized` (`merge-workflow-path`) and parks at 090 for a person's click. `false` keeps every workflow-path PR a person's merge ([#14664](https://github.com/hivecommons/hive/issues/14664)). See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.workflow_fence_scope` | `all` | Which CI workflow / action edits trip the `contributor-lane:workflow-path` fence. `all` fences every edit under `.github/workflows/**` or `.github/actions/**`. `human_merge_paths` fences only a workflow / action file that also matches the repository's `auto_merge.human_merge_paths` (the human-merge hold's matcher), so routine workflow edits go through review, CI and soak without an owner's approval. Fails closed: a repository with no `human_merge_paths` entry keeps the full fence, a renamed workflow / action file always trips it, and a head GitHub refused to merge for want of the App's **Workflows: Read and write** is marked `hive:unauthorized` (`merge-workflow-path`) and stays fenced. The tests-removed fence, Sentinel, the human-merge hold, the held-run approval guard (never for any workflow edit) and adoption's refusal to publish workflow edits upstream are unchanged. Sentinel's default `sensitive_path` list still labels such PRs `sentinel-alert`. Any other value is rejected on save and read as `all`. Owner-only through `PUT /api/config/auto-merge`; Settings → Features → Auto Merge → Contributor-lane auto-merge → **Workflow fence scope**. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.workflow_fence_scope` | `all` | Which CI workflow / action edits trip the `contributor-lane:workflow-path` fence. `all` fences every edit under `.github/workflows/**` or `.github/actions/**`. `human_merge_paths` fences only a workflow / action file that also matches the repository's `auto_merge.human_merge_paths` (the human-merge hold's matcher), so routine workflow edits go through review, CI and soak without an owner's approval. Fails closed: a repository with no `human_merge_paths` entry keeps the full fence, a renamed workflow / action file always trips it, and a head GitHub refused to merge for want of the App's **Workflows: Read and write** is marked `hive:unauthorized` (`merge-workflow-path`) and stays fenced. The tests-removed fence, Sentinel, the human-merge hold, the held-run approval guard (never for any workflow edit) and adoption's refusal to publish workflow edits upstream are unchanged. Sentinel's default `sensitive_path` list still labels such PRs `sentinel-alert`. Any other value is rejected on save and read as `all`. Owner-only through `PUT /api/config/auto-merge`; Settings → Features → Auto Merge → Contributor-lane auto-merge → **Workflow fence scope**. A repository can set its own value with `project.repo_policies[].workflow_fence_scope`. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.repos` | empty = all watched repos | Optional repo allow-list for the contributor-lane tier (bare name or `owner/repo`). |
| `auto_merge.contributor_lane.exclude_labels` | `hold`, `do-not-merge`, `needs-human`, `blocked`, `needs-rebase` | Labels that keep a PR out of contributor-lane auto-merge (`do-not-merge/*` always excluded). |

Expand Down
1 change: 1 addition & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -774,6 +774,7 @@ push re-arms it.
| `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. A PR the hive opens to supersede an adopted contributor PR (body line `Supersedes #N (…; original commits by @login preserved).`) is judged by the adopted PR's author, not by the App: its code is that author's, so an untrusted author's flagged head gets the label on the App's PR too. A maintainer who removed the label from the adopted PR at the same head is not asked again; any later head is judged afresh. |
| `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. |
| `project.repo_policies[].sentinel_sensitive_paths` | unset = `sentinel.sensitive_paths` | One repository's own sensitive-path list. It replaces the hive-wide list for that repository's pull requests only, stricter or looser, and a change to `sentinel.sensitive_paths` does not reach it. `[]` matches nothing. Set in hive.yaml. Like any Sentinel setting, it applies to heads Sentinel evaluates after the change. |
| `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. |
| `sentinel.repos` | empty = all watched repos | Optional `owner/repo` allow-list. |
Expand Down
Loading
Loading