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-workflow-fence-scope.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **The contributor lane's workflow fence can be limited to release-critical workflows.** A new owner-only setting, `auto_merge.contributor_lane.workflow_fence_scope` (Settings → Features → Auto Merge → Contributor-lane auto-merge → **Workflow fence scope**), chooses which CI workflow / action edits wait for an owner's approval of the current head. `all`, the default, keeps today's behaviour: every edit under `.github/workflows/**` or `.github/actions/**` does. `human_merge_paths` fences only a file that also matches the repository's `auto_merge.human_merge_paths`, so routine edits such as pin bumps and permission tightening go through review, CI and soak instead of needing a fresh Approve after every push. It fails closed: a repository with no `human_merge_paths` entry keeps the full fence, a renamed workflow file always trips it, and a merge GitHub refuses for want of the App's Workflows permission parks the head for a person. The tests-removed fence, Sentinel, the human-merge hold, the guard that never approves held fork CI runs for a workflow edit, and adoption's refusal to publish workflow edits upstream are unchanged. The stage notes, the merge asks and `/hive approve` replies all read the same scoped fence as the lane. Sentinel's default `sensitive_path` list still labels these PRs `sentinel-alert`; see [hive-merge.md](src/docs/hive-merge.md#contributor-lane-auto-merge).
1 change: 1 addition & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ func contributorLanePolicyFunc(cfg *config.Config) func() automerge.ContributorL
AutoPromotionScope: p.EffectiveAutoPromotionScope(),
ApproveHeldRunsForRegistryTrusted: p.EffectiveApproveHeldRunsForRegistryTrusted(),
OwnerApprovalReleasesWorkflowFence: p.EffectiveOwnerApprovalReleasesWorkflowFence(),
WorkflowFenceScope: p.EffectiveWorkflowFenceScope(),
}
}
}
Expand Down
43 changes: 41 additions & 2 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -1075,6 +1075,44 @@ A PR merges through this tier only when all of the following hold:
head, and the approved head parks at `090-ready-for-human-merge` for a
person's **Merge** click as before. With the toggle off, or with no
approval, a workflow-path PR is never merged by the hive.

Which edits trip this fence is `workflow_fence_scope` (default `all`).
With `all`, every file under `.github/workflows/**` or
`.github/actions/**` does. With `human_merge_paths`, only a workflow or
action file that also matches the repository's
`auto_merge.human_merge_paths` does, read with the same matcher as the
human-merge hold. Any other workflow edit, such as a pin bump or a
tightened `permissions:` block, needs no owner approval: it goes through
review, CI, soak and every other gate here like any other change. The
scoped fence fails closed:
- a repository with no `human_merge_paths` entry keeps the full fence;
- a renamed workflow or action file always trips it, because GitHub's
file list names only the new path;
- when GitHub refuses the merge for want of the App's **Workflows: Read
and write**, the head is marked `hive:unauthorized`
(`merge-workflow-path`) and stays fenced for a person's merge, as an
owner-released head does.

A listed file still gets the human-merge hold as well. List every
reusable workflow and local action your release workflows call, not only
the top-level files: an edit to an unlisted one merges after review.
Three things ignore the scope:
- the tests-removed fence below;
- held fork CI runs, which the lane never approves for any workflow edit
(`approve_held_runs_for_registry_trusted`);
- adoption, which never publishes any workflow edit as an upstream
branch.

Sentinel is separate. Its `sensitive_path` behaviour flags
`.github/workflows/**` and `.github/actions/**` by default and labels a
contributor's PR `sentinel-alert`, which blocks this lane until a person
clears it (`contributor-lane:sentinel-blocked`). For routine workflow
edits to merge without a person, `sentinel.sensitive_paths` must also
leave those globs out. That key replaces the whole default list, so copy
the defaults and drop only the workflow and action globs; Sentinel's
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)).
- 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 Expand Up @@ -1139,14 +1177,15 @@ auto_merge:
auto_promotion_scope: hive # count clean merged PRs across every hive repo (repo = this repository only)
approve_held_runs_for_registry_trusted: true # approve action_required runs once per head for registry-admitted authors
owner_approval_releases_workflow_fence: true # a trusted merger's approval on the current head lets the lane merge .github/workflows/** PRs
workflow_fence_scope: all # human_merge_paths = fence only workflow / action files listed in auto_merge.human_merge_paths
contributor_tier:
auto_promote_after_merged: 5 # clean merged PRs before the lane trusts an author on its own; negative disables
```

The block is editable from **Settings → Features → Auto Merge →
Contributor-lane auto-merge** (enable switch, soak minutes, reviewer-verdict
switch, required tiers, auto-promotion scope, excluded labels, repository
allow-list) through the
switch, required tiers, auto-promotion scope, workflow fence scope,
excluded labels, repository allow-list) through the
same owner-only `GET/PUT /api/config/auto-merge` overlay.

**Operator workflow.** To let a known contributor's relay PRs merge
Expand Down
7 changes: 6 additions & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -1051,7 +1051,12 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human-
note says the hive adopted it to repair CI and why it still will not
merge it (for `workflow-path` with the owner-approval release on, the
085 note instead asks for a trusted merger's approval on the current
head, which releases the fence, [#14664](https://github.com/hivecommons/hive/issues/14664)).
head, which releases the fence, [#14664](https://github.com/hivecommons/hive/issues/14664);
with `auto_merge.contributor_lane.workflow_fence_scope:
human_merge_paths`, an edit to a workflow file the repository does not
list there is no merge fence, so the adoption comment does not say the
merge stays manual and the lane merges the green head after review).
Supersession still refuses every workflow edit, whatever the scope.
- **supersede** (and the `dco-rehome`, `signoff-rehome` and
`in-place-stalled` second takeovers): the App PR's body opens with
`<!-- hive:carried-fence reason=<contributor-lane:…> from=#<n> -->`
Expand Down
1 change: 1 addition & 0 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,6 +557,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.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
33 changes: 33 additions & 0 deletions src/pkg/config/automerge_trusted_bot_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,39 @@ func TestContributorLaneAutoMergeConfigOwnerApprovalReleasesWorkflowFence(t *tes
}
}

// workflow_fence_scope defaults to all (today's full fence), accepts
// human_merge_paths in any case, and rejects anything else; a rejected value
// still reads as all, so it never narrows the fence.
func TestContributorLaneAutoMergeConfigWorkflowFenceScope(t *testing.T) {
var cfg ContributorLaneAutoMergeConfig
if got := cfg.EffectiveWorkflowFenceScope(); got != ContributorLaneWorkflowFenceScopeAll {
t.Fatalf("default workflow_fence_scope = %q, want all", got)
}
cfg.WorkflowFenceScope = " Human_Merge_Paths "
if err := cfg.Validate(); err != nil {
t.Fatalf("human_merge_paths scope should validate: %v", err)
}
if got := cfg.EffectiveWorkflowFenceScope(); got != ContributorLaneWorkflowFenceScopeHumanMergePaths {
t.Fatalf("workflow_fence_scope = %q, want human_merge_paths (trimmed, lower-cased)", got)
}
cfg.WorkflowFenceScope = "release_only"
if err := cfg.Validate(); err == nil || !strings.Contains(err.Error(), "workflow_fence_scope") {
t.Fatalf("invalid scope must fail validation, got %v", err)
}
if got := cfg.EffectiveWorkflowFenceScope(); got != ContributorLaneWorkflowFenceScopeAll {
t.Fatalf("unknown workflow_fence_scope = %q, want all (never narrows the fence)", got)
}
var parsed struct {
ContributorLane ContributorLaneAutoMergeConfig `yaml:"contributor_lane"`
}
if err := yaml.Unmarshal([]byte("contributor_lane:\n workflow_fence_scope: human_merge_paths\n"), &parsed); err != nil {
t.Fatal(err)
}
if got := parsed.ContributorLane.EffectiveWorkflowFenceScope(); got != ContributorLaneWorkflowFenceScopeHumanMergePaths {
t.Fatalf("yaml workflow_fence_scope = %q, want human_merge_paths", got)
}
}

func TestContributorTierAutoMergeConfigAutoPromoteDefault(t *testing.T) {
var cfg ContributorTierAutoMergeConfig
if got := cfg.EffectiveAutoPromoteAfterMerged(); got != DefaultContributorTierAutoPromoteAfterMerged {
Expand Down
43 changes: 43 additions & 0 deletions src/pkg/config/review_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -892,6 +892,46 @@ type ContributorLaneAutoMergeConfig struct {
// the PR hive:unauthorized and parks it for a person's merge click.
// false keeps every workflow-path PR a person's merge.
OwnerApprovalReleasesWorkflowFence *bool `yaml:"owner_approval_releases_workflow_fence,omitempty" json:"owner_approval_releases_workflow_fence,omitempty"`
// WorkflowFenceScope picks which CI workflow / action edits trip the
// workflow-path fence. `all` (the default) fences every edit under
// `.github/workflows/**` or `.github/actions/**`. `human_merge_paths`
// fences only an edit to a file that also matches the repository's
// auto_merge.human_merge_paths, so routine workflow edits go through
// review, CI and soak like any other change; a repository with no
// human_merge_paths entry keeps the full fence. An unknown value is
// rejected by Validate and treated as `all`.
WorkflowFenceScope string `yaml:"workflow_fence_scope,omitempty" json:"workflow_fence_scope,omitempty"`
}

// Contributor-lane workflow fence scopes
// (auto_merge.contributor_lane.workflow_fence_scope).
const (
ContributorLaneWorkflowFenceScopeAll = "all"
ContributorLaneWorkflowFenceScopeHumanMergePaths = "human_merge_paths"
)

// ContributorLaneWorkflowFenceScopes lists the accepted workflow_fence_scope
// values.
var ContributorLaneWorkflowFenceScopes = []string{ContributorLaneWorkflowFenceScopeAll, ContributorLaneWorkflowFenceScopeHumanMergePaths}

// normalizedWorkflowFenceScope is workflow_fence_scope trimmed and
// lower-cased, with unset meaning `all`.
func (c ContributorLaneAutoMergeConfig) normalizedWorkflowFenceScope() string {
scope := strings.ToLower(strings.TrimSpace(c.WorkflowFenceScope))
if scope == "" {
return ContributorLaneWorkflowFenceScopeAll
}
return scope
}

// EffectiveWorkflowFenceScope returns the workflow fence scope the lane
// applies: `human_merge_paths` only when set to exactly that (any case),
// otherwise `all`, so an unknown value never narrows the fence.
func (c ContributorLaneAutoMergeConfig) EffectiveWorkflowFenceScope() string {
if c.normalizedWorkflowFenceScope() == ContributorLaneWorkflowFenceScopeHumanMergePaths {
return ContributorLaneWorkflowFenceScopeHumanMergePaths
}
return ContributorLaneWorkflowFenceScopeAll
}

// Contributor-lane auto-promotion scopes
Expand Down Expand Up @@ -1067,6 +1107,9 @@ func (c ContributorLaneAutoMergeConfig) Validate() error {
if scope := c.EffectiveAutoPromotionScope(); scope != ContributorLaneAutoPromotionScopeHive && scope != ContributorLaneAutoPromotionScopeRepo {
return fmt.Errorf("auto_merge.contributor_lane.auto_promotion_scope: %q is not valid (allowed: %s)", c.AutoPromotionScope, strings.Join(ContributorLaneAutoPromotionScopes, ", "))
}
if scope := c.normalizedWorkflowFenceScope(); scope != ContributorLaneWorkflowFenceScopeAll && scope != ContributorLaneWorkflowFenceScopeHumanMergePaths {
return fmt.Errorf("auto_merge.contributor_lane.workflow_fence_scope: %q is not valid (allowed: %s)", c.WorkflowFenceScope, strings.Join(ContributorLaneWorkflowFenceScopes, ", "))
}
return nil
}

Expand Down
17 changes: 17 additions & 0 deletions src/pkg/dashboard/api_config_automerge.go
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,7 @@ func (s *Server) handleAutoMergePut(w http.ResponseWriter, r *http.Request) {
AutoPromotionScope *string `json:"auto_promotion_scope"`
ApproveHeldRunsForRegistryTrusted *bool `json:"approve_held_runs_for_registry_trusted"`
OwnerApprovalReleasesWorkflowFence *bool `json:"owner_approval_releases_workflow_fence"`
WorkflowFenceScope *string `json:"workflow_fence_scope"`
} `json:"contributor_lane"`
}
if err := decodeBody(r, &body); err != nil {
Expand Down Expand Up @@ -274,6 +275,7 @@ func (s *Server) handleAutoMergePut(w http.ResponseWriter, r *http.Request) {
var contributorLaneLabels []string
var contributorLaneTiers []string
var contributorLaneScope string
var contributorLaneWorkflowFenceScope string
if body.ContributorLane != nil {
if body.ContributorLane.SoakMinutes != nil && *body.ContributorLane.SoakMinutes < 0 {
jsonError(w, "contributor_lane.soak_minutes must be 0 (default 30) or greater", http.StatusBadRequest)
Expand Down Expand Up @@ -308,6 +310,16 @@ func (s *Server) handleAutoMergePut(w http.ResponseWriter, r *http.Request) {
}
contributorLaneScope = scope.EffectiveAutoPromotionScope()
}
if body.ContributorLane.WorkflowFenceScope != nil {
// An unknown value is refused here; the lane reads anything but
// human_merge_paths as the full fence (EffectiveWorkflowFenceScope).
scope := config.ContributorLaneAutoMergeConfig{WorkflowFenceScope: *body.ContributorLane.WorkflowFenceScope}
if err := scope.Validate(); err != nil {
jsonError(w, "contributor_lane.workflow_fence_scope must be one of "+strings.Join(config.ContributorLaneWorkflowFenceScopes, ", "), http.StatusBadRequest)
return
}
contributorLaneWorkflowFenceScope = scope.EffectiveWorkflowFenceScope()
}
}

// --- apply ---
Expand Down Expand Up @@ -425,6 +437,9 @@ func (s *Server) handleAutoMergePut(w http.ResponseWriter, r *http.Request) {
if body.ContributorLane.AutoPromotionScope != nil {
cfg.AutoMerge.ContributorLane.AutoPromotionScope = contributorLaneScope
}
if body.ContributorLane.WorkflowFenceScope != nil {
cfg.AutoMerge.ContributorLane.WorkflowFenceScope = contributorLaneWorkflowFenceScope
}
}
syncAutoMergePolicyToGitHubClient(cfg, s.deps.GHClient)

Expand Down Expand Up @@ -554,6 +569,8 @@ func autoMergeSectionResponse(cfg *config.Config) map[string]interface{} {
"grantable_tiers": config.ContributorLaneGrantableTiers,
"approve_held_runs_for_registry_trusted": cl.EffectiveApproveHeldRunsForRegistryTrusted(),
"owner_approval_releases_workflow_fence": cl.EffectiveOwnerApprovalReleasesWorkflowFence(),
"workflow_fence_scope": cl.EffectiveWorkflowFenceScope(),
"workflow_fence_scopes": config.ContributorLaneWorkflowFenceScopes,
},
}
}
Expand Down
Loading
Loading