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/fixed-workflows-blocker-verified.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An agent's "the App cannot push `.github/workflows/`" is checked before it parks anything. On projectbluefin/testsuite#1059 and #1073, scanner (ISSUES_PRS_MERGE, whose token asks for the Workflows permission) parked a workflow fix the same day the App pushed `e2e.yml` in #1089, and the issues showed "Blocked · App lacks workflows permission" for four days. Now the relay refuses that park when the parking lane's tier pushes workflows and the App installation grants `workflows: write` (read at most every five minutes), and hands a contributor-tier park to the workflows lane only when the installation is not known to lack the permission. The blocker ledger records a workflows blocker only when no lane can push workflow files on that repository or the item is a fork PR (a fork branch takes no workflow push from the App), and a re-check that runs with the un-park sweep releases existing ones and routes them to the workflows lane. Merger- and trusted-tier kicks now say their token can push `.github/workflows/**`. A park that quotes GitHub's own rejection of the push still stands, and that evidence is kept across later unquoted re-reports; a contributor-tier lane's quote is not treated as evidence about the App.
9 changes: 9 additions & 0 deletions src/cmd/hive/github_client_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (
"github.com/hivecommons/hive/pkg/attention"
"github.com/hivecommons/hive/pkg/authorkind"
"github.com/hivecommons/hive/pkg/beads"
itemblocker "github.com/hivecommons/hive/pkg/blocker"
"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/github"
Expand Down Expand Up @@ -157,6 +158,14 @@ func (b *boot) applyGitHubClientConfigHooks(client *github.Client) {
// to the lane that can, instead of the owner (issue_workflows_handoff.go).
// Live predicate over the shared config, like the scope funcs above.
client.SetWorkflowsLaneFunc(b.cfg.WorkflowsLaneFor)
// A lane whose own token asks for the Workflows permission is refused a
// workflow-only park when the installation grants it, and the blocker
// ledger records "App lacks workflows" only when the hive cannot push
// them (projectbluefin/testsuite#1059). The ledger is process-wide, so a
// rebuilt client re-installs its check.
client.SetWorkflowsSelfPushFunc(b.cfg.AgentPushesWorkflows)
itemblocker.Shared().SetCapabilityCheck(client.CapabilityAvailable)
itemblocker.Shared().SetProofCheck(client.WorkflowsRejectionProves)
client.SetReporterConfirmationEnabledFunc(func() bool {
return b.cfg.Issues.ReporterConfirmationEnabled()
})
Expand Down
9 changes: 9 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -1499,6 +1499,15 @@ func runIssueUnparkSweepIfDue(ctx context.Context, ghClient *github.Client, cfg
if lastRun != nil {
*lastRun = now
}
// Capability blockers recorded before the hive could check them, or
// before the permission was granted, are re-checked at the same cadence
// (and on the first pass after start), so a false "App lacks workflows
// permission" clears itself (projectbluefin/testsuite#1059).
if released, err := ghClient.SweepWorkflowsBlockers(ctx); err != nil {
logger.Warn("workflows blocker re-check: labelling released items failed", "released", len(released), "error", err)
} else if len(released) > 0 {
logger.Info("workflows blocker re-check released items", "released", len(released))
}
// `/hive approve` on a PR is answered with what the merge lane will do
// with it (hivecommons/hive#13087); the engine here only reads policy.
approveOpts := automerge.Options{
Expand Down
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -382,7 +382,7 @@ A `blocked` issue with neither (a human-applied label) keeps the bare pill. This

#### Blocked pill — capability gaps

**Blocked pill — capability gaps** ([#15099](https://github.com/hivecommons/hive/issues/15099)). An issue parked because the hive *cannot* act — the scanner reported "the App token cannot push `.github/workflows/*` (no `workflows` permission); needs a human" — is a blocker, not a question, so its row does not read *Needs human decision*: the pill reads **Blocked · App lacks workflows permission** and the same popover says in plain words *Hive can't do this one: the GitHub App has no `workflows` permission, so it cannot push changes to .github/workflows/\*.* followed by the ways out: *Grant the App workflows permission* (opens the App settings page; the hive re-tries on its own once it sees the permission), *Re-check permissions* (probes the installation now and releases every item blocked on it), *Prepare the patch for a person to push* (disabled with its reason until a human-authorised push identity exists), *Mark partially addressed and close*, *Keep waiting*. *Let hive decide* stays in the list but disabled with the sentence that explains why — a direction decision cannot grant a permission — instead of being greyed silently; running it anyway returns *no-effect* with the same words and never applies `approved-direction`. The loop that motivated this (un-park → sweep re-parks with the same text → "I tried let hive decide and it still needs human") is guarded: when the same needs-human reason comes back after a delegated un-park, the row is parked with a blocker and *Let hive decide* is disabled on it until the reason changes. The blocker comes from the agent's `<!-- hive:blocker kind=… -->` marker or, failing that, from the prose of the needs-human report (`pkg/blocker`), and ⚙ → Security shows the fleet view: *GitHub App permissions: missing `workflows` · N items blocked* with the settings link (`/api/status.capabilities`).
**Blocked pill — capability gaps** ([#15099](https://github.com/hivecommons/hive/issues/15099)). An issue parked because the hive *cannot* act — the scanner reported "the App token cannot push `.github/workflows/*` (no `workflows` permission); needs a human" — is a blocker, not a question, so its row does not read *Needs human decision*: the pill reads **Blocked · App lacks workflows permission** and the same popover says in plain words *Hive can't do this one: the GitHub App has no `workflows` permission, so it cannot push changes to .github/workflows/\*.* followed by the ways out: *Grant the App workflows permission* (opens the App settings page; the hive re-tries on its own once it sees the permission), *Re-check permissions* (probes the installation now and releases every item blocked on it), *Prepare the patch for a person to push* (disabled with its reason until a human-authorised push identity exists), *Mark partially addressed and close*, *Keep waiting*. *Let hive decide* stays in the list but disabled with the sentence that explains why — a direction decision cannot grant a permission — instead of being greyed silently; running it anyway returns *no-effect* with the same words and never applies `approved-direction`. The loop that motivated this (un-park → sweep re-parks with the same text → "I tried let hive decide and it still needs human") is guarded: when the same needs-human reason comes back after a delegated un-park, the row is parked with a blocker and *Let hive decide* is disabled on it until the reason changes. The blocker comes from the agent's `<!-- hive:blocker kind=… -->` marker or, failing that, from the prose of the needs-human report (`pkg/blocker`). A workflows blocker is recorded only when the hive cannot push workflow files for that item: when the App installation grants `workflows: write`, an enabled lane whose token asks for it serves the repository and the item is an issue or a same-repository PR, the report is kept as a plain reason and no pill is drawn. A fork PR keeps the blocker, because a fork branch takes no workflow-file push from the App whatever it is granted. The same check runs with the issue un-park sweep (on start, then every five minutes) on blockers already recorded: a released one gets `hive/workflows-lane`, so the issue goes to that lane once its park is answered. ⚙ → Security shows the fleet view: *GitHub App permissions: missing `workflows` · N items blocked* with the settings link (`/api/status.capabilities`).

#### New row (`000-new`, the pre-stage state)

Expand Down
18 changes: 17 additions & 1 deletion src/docs/hive-open-issue.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,23 @@ repository (a lane scoped to other repositories with `repos:` is never chosen),
the watcher adds `hive/workflows-lane` instead of the park label, appends a
"Handed to `<lane>`" note and no owner-step marker, and the scheduler routes the
issue to that lane. On `issue` the new issue is created at
`stage/010-actionable` with the label.
`stage/010-actionable` with the label. The hand-off is skipped (the park
stands) when the App installation is known to lack `workflows: write`.

A lane that can push workflow files itself is refused the park instead. When
the parking lane runs at the trusted or merger tier (ISSUES_PRS_MERGE), whose
token asks for the Workflows permission, and the App installation grants
`workflows: write` (read at most every five minutes), the watcher parks
nothing, adds no label, and appends a "Not parked: `<lane>`'s token can push
`.github/workflows/`" note: the issue stays with that lane to push the change.
If the installation lacks the permission, or cannot be read, the park stands. It
also stands when the park quotes GitHub's own rejection of the push ("refusing to
allow a GitHub App to create or update workflow … without `workflows`
permission"): that is evidence, and the blocker it records is never released by
the scheduled re-check. The quote counts as evidence only from a lane whose own
token asks for the permission (or from a report with no `— hive:` trailer, such
as a person pasting the error); a contributor-tier lane's quote shows only that
its own token lacks it, so that blocker stays releasable.

#### Withdrawing your own park

Expand Down
4 changes: 2 additions & 2 deletions src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -382,9 +382,9 @@ Not added when the same sweep is applying `needs-human`.

**Applies to:** Issues. **Kind:** Routing.

Workflow hand-off. An ISSUES_AND_PRS lane's token is minted at the `contributor` tier, which has no Workflows permission, so it cannot push a change under `.github/workflows/`. When such a lane parks a workflow-only change (`hive-open-issue issue|comment --needs-decision` whose text says it cannot push the workflow file, with no lettered options for the owner) and an enabled lane that serves the repository runs at ISSUES_PRS_MERGE (one scoped to other repositories with `repos:` is never chosen), the relay does not park the issue: it adds this label, posts the lane's exact replacement with a "Handed to `<lane>`" note, and the scheduler sends the issue to that lane rather than back to the one that filed it. With no such lane, or when the ISSUES_PRS_MERGE lane itself could not push, the park goes to the owner as before.
Workflow hand-off. An ISSUES_AND_PRS lane's token is minted at the `contributor` tier, which has no Workflows permission, so it cannot push a change under `.github/workflows/`. When such a lane parks a workflow-only change (`hive-open-issue issue|comment --needs-decision` whose text says it cannot push the workflow file, with no lettered options for the owner) and an enabled lane that serves the repository runs at ISSUES_PRS_MERGE (one scoped to other repositories with `repos:` is never chosen), the relay does not park the issue: it adds this label, posts the lane's exact replacement with a "Handed to `<lane>`" note, and the scheduler sends the issue to that lane rather than back to the one that filed it. With no such lane, or when the App installation is known to lack `workflows: write`, the park goes to the owner as before. An ISSUES_PRS_MERGE lane's own workflow-only park is refused, with no label, when the installation grants `workflows: write`: its token can push the change. The scheduled blocker re-check also adds this label to an issue whose "App lacks workflows permission" blocker it releases.

**Who applies it:** Hive (issue-request relay).
**Who applies it:** Hive (issue-request relay, blocker re-check).

**Checked by:** Scheduler kick assembly. **When:** Every kick build.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:5345-5355`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5350-5360`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes → refactors/docs → tests).
Expand Down
22 changes: 20 additions & 2 deletions src/pkg/blocker/blocker.go
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,24 @@ type Blocker struct {
// "loop-guard".
Source string `json:"source,omitempty"`
Since time.Time `json:"since,omitempty"`
// Proven: the report quotes GitHub's own refusal of the push
// (QuotesWorkflowsRejection), so it is evidence, not a claim, and no
// capability check refutes it.
Proven bool `json:"proven,omitempty"`
}

// workflowsRejectionRE is GitHub's refusal of a workflow-file push, as it
// reads for an App, an OAuth App or a token: "refusing to allow a GitHub App
// to create or update workflow `.github/workflows/x.yml` without `workflows`
// permission".
var workflowsRejectionRE = regexp.MustCompile("(?i)refusing to allow an? (GitHub App|OAuth App|Personal Access Token|integration)[^.\n]{0,40}? to (create or update|create|update) workflow")

// QuotesWorkflowsRejection reports whether text quotes GitHub's own refusal
// of a workflow-file push. A lane told its token can push workflow files
// parks again with that error when a push still bounces; the quote is what
// separates that from an unverified "the App cannot push workflows".
func QuotesWorkflowsRejection(text string) bool {
return workflowsRejectionRE.MatchString(text)
}

const (
Expand Down Expand Up @@ -210,10 +228,10 @@ func Infer(prose string) (Kind, bool) {
// sentence the kind was inferred from.
func Detect(text string, at time.Time) (Blocker, bool) {
if k, ok := ParseMarker(text); ok {
return Blocker{Kind: k, Detail: ReasonSentence(text), Source: SourceMarker, Since: at}, true
return Blocker{Kind: k, Detail: ReasonSentence(text), Source: SourceMarker, Since: at, Proven: k == CapabilityWorkflowsPermission && QuotesWorkflowsRejection(text)}, true
}
if k, ok := Infer(text); ok {
return Blocker{Kind: k, Detail: ReasonSentence(text), Source: SourceInferred, Since: at}, true
return Blocker{Kind: k, Detail: ReasonSentence(text), Source: SourceInferred, Since: at, Proven: k == CapabilityWorkflowsPermission && QuotesWorkflowsRejection(text)}, true
}
return Blocker{}, false
}
Expand Down
98 changes: 98 additions & 0 deletions src/pkg/blocker/ledger.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,50 @@ type Ledger struct {
entries map[string]Entry
now func() time.Time
loaded bool
// capabilityCheck refutes a capability report (SetCapabilityCheck).
capabilityCheck func(repo string, number int, k Kind) bool
// proofCheck confirms a quoted rejection proves the gap (SetProofCheck).
proofCheck func(text string) bool
}

// SetProofCheck installs the check Observe asks before it marks a quoted
// GitHub rejection as proof (Blocker.Proven): true when the quote came from a
// reporter whose own token asks for the permission. A contributor-tier lane
// quoting GitHub's refusal shows only that its own token lacks `workflows`,
// not that the App does, so its blocker stays refutable. Nil, the default,
// trusts every quote.
func (l *Ledger) SetProofCheck(fn func(text string) bool) {
l.mu.Lock()
defer l.mu.Unlock()
l.proofCheck = fn
}

func (l *Ledger) proofHolds(text string) bool {
l.mu.Lock()
fn := l.proofCheck
l.mu.Unlock()
return fn == nil || fn(text)
}

// SetCapabilityCheck installs the check Observe asks before it records a
// capability blocker: true means the hive verified it holds that capability
// for that item (for workflows: the installation grants `workflows: write`,
// a lane whose token asks for it serves the repo, and the item is not a fork
// PR), so an agent's "the App cannot push workflow files" is not recorded
// as a blocker (projectbluefin/testsuite#1059). Nil, the default, records
// every report.
func (l *Ledger) SetCapabilityCheck(fn func(repo string, number int, k Kind) bool) {
l.mu.Lock()
defer l.mu.Unlock()
l.capabilityCheck = fn
}

// capabilityHeld runs the check outside the ledger lock: it may read GitHub.
func (l *Ledger) capabilityHeld(repo string, number int, k Kind) bool {
l.mu.Lock()
fn := l.capabilityCheck
l.mu.Unlock()
return fn != nil && k.IsCapability() && fn(repo, number, k)
}

// NewLedger returns a ledger backed by path (loaded lazily; a missing or
Expand Down Expand Up @@ -140,6 +184,14 @@ func (l *Ledger) Observe(repo string, number int, text string, at time.Time) (En
}
return l.RecordReason(repo, number, NormalizeReason(text), at), true
}
if b.Proven && !l.proofHolds(text) {
b.Proven = false
}
if !b.Proven && l.capabilityHeld(repo, number, b.Kind) {
// The hive holds the capability the report says is missing: keep the
// reason for the loop guard, park nothing on it.
return l.RecordReason(repo, number, NormalizeReason(text), at), true
}
return l.Record(repo, number, b, NormalizeReason(text)), true
}

Expand All @@ -165,6 +217,12 @@ func (l *Ledger) Record(repo string, number int, b Blocker, reason string) Entry
if e.Blocker != nil && e.Blocker.Kind == b.Kind && !e.Blocker.Since.IsZero() && e.Blocker.Since.Before(b.Since) {
b.Since = e.Blocker.Since
}
// Evidence outlives a later unquoted re-report of the same kind, which
// lands here whenever the capability check could not refute it (an
// unreadable installation): Proven must not drop with it.
if e.Blocker != nil && e.Blocker.Kind == b.Kind && e.Blocker.Proven {
b.Proven = true
}
e.Blocker = &b
e.Reason = reason
e.ReportedAt = observedAt
Expand Down Expand Up @@ -278,6 +336,46 @@ func (l *Ledger) ClearKind(k Kind) int {
return n
}

// RecheckCapabilities lifts every capability blocker that held(repo, number, kind)
// now refutes and returns the released entries as they were. It is the
// scheduled form of the dashboard's Re-check permissions, per item rather
// than per kind, so a blocker on a repo no capable lane serves stays, and so
// does one whose report quoted GitHub's rejection (Blocker.Proven). held
// runs outside the ledger lock; a blocker that changed kind meanwhile is kept.
func (l *Ledger) RecheckCapabilities(held func(repo string, number int, k Kind) bool) []Entry {
if held == nil {
return nil
}
var refuted []Entry
for _, e := range l.Blockers() {
if e.Blocker.Kind.IsCapability() && !e.Blocker.Proven && held(e.Repo, e.Number, e.Blocker.Kind) {
refuted = append(refuted, e)
}
}
if len(refuted) == 0 {
return nil
}
l.mu.Lock()
defer l.mu.Unlock()
var released []Entry
for _, was := range refuted {
k := Key(was.Repo, was.Number)
e, ok := l.entries[k]
if !ok || e.Blocker == nil || e.Blocker.Kind != was.Blocker.Kind || !e.Blocker.Since.Equal(was.Blocker.Since) {
continue
}
e.Blocker = nil
e.Reapplied = false
e.ClearedAt = l.now()
l.entries[k] = e
released = append(released, was)
}
if len(released) > 0 {
_ = l.save()
}
return released
}

// Blockers lists every current blocker, sorted by item key.
func (l *Ledger) Blockers() []Entry {
l.mu.Lock()
Expand Down
Loading
Loading