[clubanderson]

Fixes #13818

What

Banner Merge blocked for hivecommons/docs: fork PR workflow runs are awaiting maintainer approval… is about hivecommons/docs#428 — a same-repo PR opened daily by github-actions[bot] (GITHUB_TOKEN, peter-evans/create-pull-request). GitHub holds its four pull_request runs action_required; the opener workflow dispatches the same four workflows by workflow_dispatch on the same head, all success. The repo's approval policy is already first_time_contributors_new_to_github (the minimum), so the banner's advice cannot be followed.

• opaqueWorkflowRuns: an action_required run whose workflow already has a completed success run on the same head (any event) goes to heldButVerified — reported in the green reason as held run(s) … ignored, not counted as gating. The verdict is on the head through the twin's check runs.
• Without such a twin the reason distinguishes a fork PR from a same-repo PR opened by a bot token (pullRequestIsFromFork), and classifyMergeFailureForOperator maps the new wording to the same fork-run-approval alert key so the existing 5-minute revalidation clears both.

The hive still never calls the workflow-run approval API.

Tests

merge_ci_gate_test.go: held runs with successful workflow_dispatch twins → green with the ignored list; held run without a twin on a same-repo PR → red with the same-repo wording; fork PR wording preserved; pullRequestIsFromFork cases. No time.Sleep added.

Docs: hive-merge.md, changelog fragment.

Verified go build ./... && go vet ./pkg/github/ && go test ./pkg/github/.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Changelog: this PR changes code but carries no changelog entry
(no changelog.d/ fragment and no CHANGELOG.md edit).

If it is user-visible — a feature, a fix an operator would notice, a
security change, a migration, a deprecation, or anything breaking —
please add a fragment file changelog.d/<category>-<pr-or-slug>.md
containing exactly your entry (see changelog.d/README.md; the
category is one of added/changed/deprecated/fixed/security). Please
do not append to CHANGELOG.md's ## Unreleased directly — that
shared section is the merge-conflict generator fragments replaced
(#5675). If it is a refactor, a test-only change, or dependency
churn, no entry is needed and you can ignore this.

This is a reminder, not a gate; it never blocks a merge.

[github-actions]

Changelog fragment in the wrong directory

Fragments live in changelog.d/ at the repository root, not under src/. Files under src/changelog.d/ are never compiled into CHANGELOG.md, so the changelog-fragment-guard check fails. Move them and push:

git mv src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md changelog.d/fixed-13818-ci-gate-held-twin-runs.md
git commit -s -m "changelog: move fragment to repo-root changelog.d/"

See changelog.d/README.md (#5675, #11919). This comment is removed automatically once nothing is misplaced.

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

[hivecommons-hive]

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this repository have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

[hivecommons-hive]

Evidence bundle `#1382294cf9ff` sha256:d7e2a19e024a0c6c153f46f0fc1638792867518baaf3b5742b1758a18d75f15d — download from the dashboard or `hivectl review evidence #13822`.

[hivecommons-hive]

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at 94cf9ff.

[hivecommons-hive]

Logic looks correct to me; one concrete blocker — the changelog fragment is in the wrong directory, which is why changelog-fragment-guard is red.

Blocker (medium — CI):

• src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md — fragments live in repo-root changelog.d/ (310 files on v5); files under src/changelog.d/ are never compiled into CHANGELOG.md and the guard fails on them (job 120542887969: "Changelog fragment in the wrong directory"). git mv src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md changelog.d/ fixes the check. The filename itself is valid.

What I verified in the tree at 94cf9ff:

• merge_ci_gate.go:366-382 — succeeded is computed from the same latest slice (one run per workflow×event) and keyed by WorkflowID, so a pull_request run can only be waived by a success of the same workflow on the same head; TestMergeCIGate_HeldRunStillBlocksWhenOnlyOtherWorkflowSucceeded pins the negative case. Required check-run evaluation is untouched, so the twin's check runs still gate.
• merge_failure_alert.go:202-213 — the existing fork case matches on "fork pr workflow runs are awaiting…"; the new same-repo reason string (merge_ci_gate.go:491) does not contain that substring, so the new case is reachable and not shadowed. Reusing key fork-run-approval keeps the existing revalidation path.
• merge_ci_gate.go:481-484 — pullRequestIsFromFork returns false when head.repo is null (deleted fork). That yields the same-repo wording for a PR whose fork was deleted; such a PR cannot merge anyway, so this is cosmetic (info).

Note on the body: it lists "pullRequestIsFromFork cases" under Tests, but the five changed files contain only the three new TestMergeCIGate_* tests; the helper is exercised indirectly via …SameRepoRunNamesBotTokenCause and the pre-existing fork-alert test. Not a defect — just so the description matches.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

[hivecommons-hive]

The code looks correct to me; the one red check is the fragment's location, not the code.

Blocker (why changelog-fragment-guard is red): src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md is under src/. Fragments live at the repository root — src/changelog.d/README.md:1-6 says so and names this check. Fix: git mv src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md changelog.d/. (Same slip as #13821.)

What I verified in the tree (94cf9ff):

• src/pkg/github/merge_ci_gate.go:355-356 lists runs with HeadSHA: sha, so workflowsWithSuccessfulRun (:468-476) can only be satisfied by a twin on the same head — a workflow_dispatch success on an older commit cannot excuse a held pull_request run. The twin check is keyed on WorkflowID, so TestMergeCIGate_HeldRunStillBlocksWhenOnlyOtherWorkflowSucceeded correctly keeps a different workflow's success from counting.
• :372-383 the continue for held-but-verified runs skips the pending/actionRequired bookkeeping only; required-check evidence still comes from check runs, so a held run with no successful twin still lands in actionRequired and blocks (:244).
• pullRequestIsFromFork (:483-486) compares head/base repo full names case-insensitively and treats missing names as not-fork, which only changes the wording of the refusal, never whether it refuses.
• src/pkg/github/merge_failure_alert.go:201-213: the new same-repo pr workflow runs are awaiting maintainer approval case cannot be captured by the earlier fork pr workflow runs are awaiting maintainer approval case (different leading words), and reusing key fork-run-approval means the existing revalidation clears it the same way.
• Body matches the diff. For what it's worth, this is exactly the state of hivecommons/docs#428 right now: pull_request runs held, workflow_dispatch twins green.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88