frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

fix(release-draft): use github.head_ref — closes #41 root-cause from substrate-evidence #50

Merged
quartermaster merged 1 commit from i/41-release-draft-head-ref into main 2026-06-25 00:40:10 +02:00
Conversation 1 Commits 1 Files changed 3 +22 -5
quartermaster commented 2026-06-25 00:37:44 +02:00
Owner
Copy link

What this does

Replaces all github.event.pull_request.head.ref accesses with the top-level github.head_ref convenience field in release-draft.yml AND docs/integration.md. Drops the .merged == true check from the if-guard (same nested-access trap).

Two surfaces, both observable via ordinary release-cut flow.

Root-cause from substrate-evidence

The probe-debug arc (slices 1+2 / PRs #48 + #49) couldn't produce log artifacts because top-level inline-steps workflows don't log in this Forgejo/act_runner — that's a separate substrate-level finding (#47). But the failure-path log captured the data anyway via a uses:-reusable that DID log:

  • Task 13004 (PR #48 close, head.ref='i/41-probe-simplify'): ::error::version normalization produced empty string from inputs.version=''
  • Task 13010 (PR #49 close, head.ref='i/41-probe-minimize'): same error

Both PRs were non-release-prep. For the if-guard ... || (merged == true && startsWith(head.ref, 'release-prep/')) to fire on EITHER, the right side had to evaluate truthy. If .merged resolved correctly (true) and .head.ref failed-empty, right would be true && false = false → skip. The job fired in BOTH cases, so BOTH nested accesses fail in concert.

Surveyor 022b's depth-vs-type discriminator question: n=2 empirical answers it — it's TYPE, not depth. Forgejo's expression engine fail-opens on ANY github.event.pull_request.* nested access on pull_request.closed events.

Fix

Two surfaces, both surgical:

  1. if: guard at job level:

    • Before: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release-prep/'))
    • After: github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-prep/')
    • Drops .merged check entirely (preserving it re-introduces the fail-open). Trade-off: on cancelled unmerged-closed release-prep/* PRs the reusable fires but fails-loud BEFORE creating any draft/tag (changelog section absence on main acts as natural guard at draft-release.sh:105-107). Verified harmless per Surveyor 022b refinement-1.

  2. version: input to the reusable:

    • Before: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.event.pull_request.head.ref }}
    • After: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.head_ref }}

Same fix to docs/integration.md template — new consumers don't inherit the trap.

Inline # Why github.head_ref ... comment in the workflow file captures the rationale + the n=2 evidence so future-readers don't need to spelunk the PR archaeology.

Hypothesis still in flight

github.head_ref working on pull_request.closed events is itself a hypothesis (top-level convenience field is a different code-path in the expression engine; should resolve from the cached event payload; empirically untested in this Forgejo build). Marked as hypothesis per Surveyor e455 + bdd7.

Verification protocol (post-merge)

Per Surveyor 022b refinement-2, both surfaces observable in ordinary flow — and release-draft.yml IS in the uses:-reusable class (logging works, no vacuous-no-op ambiguity):

  1. Slice-3-merge fire (this PR, non-release-prep): if-guard SHOULD skip → NO release-draft task fires post-merge. If a task DOES fire, github.head_ref ALSO failed on closed events → fix falsified, deeper restructure needed.
  2. Next release-prep/v0.3.4 PR merge: version SHOULD resolve to release-prep/v0.3.4 → reusable produces draft → version surface confirmed.

Both falsifiable, both observable from ordinary git push + mc inspect actions_log flow. No extra probe needed.

What this PR does NOT do

  • Does not remove debug-event-payload.yml (probe lifecycle constraint — wait for v0.3.4 cut + verification first)
  • Does not add the _release-draft.yml defense-in-depth ::warning:: (slice 4 — still on the table; gated on slice 3 verification)
  • Does not pin-promote #47 (substrate-level no-log finding — separate concern, separate slice)
  • Does not bump @v0.2.0 → @v0.3.x refs in docs/integration.md (separate doc-staleness concern; out of scope here)

Refs #41 (closes once verification protocol confirms guard-skip post-merge), #47 (substrate finding).

## What this does Replaces all `github.event.pull_request.head.ref` accesses with the top-level `github.head_ref` convenience field in `release-draft.yml` AND `docs/integration.md`. Drops the `.merged == true` check from the if-guard (same nested-access trap). Two surfaces, both observable via ordinary release-cut flow. ## Root-cause from substrate-evidence The probe-debug arc (slices 1+2 / PRs #48 + #49) couldn't produce log artifacts because top-level inline-steps workflows don't log in this Forgejo/act_runner — that's a separate substrate-level finding (#47). But the failure-path log captured the data anyway via a `uses:`-reusable that DID log: - Task 13004 (PR #48 close, head.ref='i/41-probe-simplify'): `::error::version normalization produced empty string from inputs.version=''` - Task 13010 (PR #49 close, head.ref='i/41-probe-minimize'): same error Both PRs were non-release-prep. For the if-guard `... || (merged == true && startsWith(head.ref, 'release-prep/'))` to fire on EITHER, the right side had to evaluate truthy. If `.merged` resolved correctly (true) and `.head.ref` failed-empty, right would be `true && false = false → skip`. The job fired in BOTH cases, so BOTH nested accesses fail in concert. Surveyor 022b's depth-vs-type discriminator question: n=2 empirical answers it — it's TYPE, not depth. Forgejo's expression engine fail-opens on ANY `github.event.pull_request.*` nested access on `pull_request.closed` events. ## Fix **Two surfaces, both surgical:** 1. **`if:` guard** at job level: - Before: `github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release-prep/'))` - After: `github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-prep/')` - Drops `.merged` check entirely (preserving it re-introduces the fail-open). Trade-off: on cancelled unmerged-closed release-prep/* PRs the reusable fires but fails-loud BEFORE creating any draft/tag (changelog section absence on main acts as natural guard at `draft-release.sh:105-107`). Verified harmless per Surveyor 022b refinement-1. 2. **`version:` input** to the reusable: - Before: `${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.event.pull_request.head.ref }}` - After: `${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.head_ref }}` Same fix to `docs/integration.md` template — new consumers don't inherit the trap. Inline `# Why github.head_ref ...` comment in the workflow file captures the rationale + the n=2 evidence so future-readers don't need to spelunk the PR archaeology. ## Hypothesis still in flight `github.head_ref` working on `pull_request.closed` events is itself a hypothesis (top-level convenience field is a different code-path in the expression engine; should resolve from the cached event payload; empirically untested in this Forgejo build). Marked as hypothesis per Surveyor e455 + bdd7. ## Verification protocol (post-merge) Per Surveyor 022b refinement-2, both surfaces observable in ordinary flow — and `release-draft.yml` IS in the `uses:`-reusable class (logging works, no vacuous-no-op ambiguity): 1. **Slice-3-merge fire** (this PR, non-release-prep): if-guard SHOULD skip → NO release-draft task fires post-merge. If a task DOES fire, `github.head_ref` ALSO failed on closed events → fix falsified, deeper restructure needed. 2. **Next release-prep/v0.3.4 PR merge**: version SHOULD resolve to `release-prep/v0.3.4` → reusable produces draft → version surface confirmed. Both falsifiable, both observable from ordinary `git push` + `mc inspect actions_log` flow. No extra probe needed. ## What this PR does NOT do - Does not remove `debug-event-payload.yml` (probe lifecycle constraint — wait for v0.3.4 cut + verification first) - Does not add the `_release-draft.yml` defense-in-depth `::warning::` (slice 4 — still on the table; gated on slice 3 verification) - Does not pin-promote #47 (substrate-level no-log finding — separate concern, separate slice) - Does not bump `@v0.2.0` → `@v0.3.x` refs in `docs/integration.md` (separate doc-staleness concern; out of scope here) Refs #41 (closes once verification protocol confirms guard-skip post-merge), #47 (substrate finding).
fix(release-draft): use github.head_ref convenience field — closes #41
Some checks failed
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s
Details
manifest-check / check (pull_request) Successful in 0s
Details
debug-event-payload / hello (pull_request) Successful in 2s
Details
release-draft / create Forgejo draft release (pull_request) Failing after 4s
Details
release-draft / draft (pull_request) Failing after 0s
Details
b45cd33df3 
Root-cause for #41 (consumer-side empty inputs.version on
pull_request.closed) cracked via failure-path log analysis after the
substrate-level probe-debug arc (slice 1 + slice 2): Forgejo's
expression engine fail-opens on ANY nested github.event.pull_request.*
access on pull_request.closed events.

Empirical evidence: n=2 in this repo. PR #48 (head.ref=i/41-probe-
simplify) AND PR #49 (head.ref=i/41-probe-minimize) both merged →
release-draft.yml's job FIRED on both (despite non-release-prep
head.refs) → empty inputs.version → loud error from #14's
normalize-fail-loud guard. For the if-guard to fire on non-release-
prep PRs, both nested accesses (.merged AND .head.ref) had to
fail-open in concert. Not a depth-discriminator (per Surveyor 022b
question + the n=2 data answering it): it's the access TYPE.

Fix: switch to the top-level github.head_ref convenience field
(different code-path in expression engine; resolves reliably from
the event payload context). Two surfaces affected:

(a) if-guard at job level — drop the .merged check entirely
    (preserving it re-introduces the fail-open trap). On cancelled
    unmerged-closed release-prep/* PRs, the reusable still fires but
    fails harmlessly at draft-release.sh:105-107 ("CHANGELOG section
    missing on main") BEFORE creating any draft/tag — fail-loud +
    side-effect-free per Surveyor 022b refinement-1 verification.

(b) version: input — same head.ref → head_ref swap.

Same fix to docs/integration.md template so new consumers don't
inherit the trap.

Verification protocol (post-merge — both observable in ordinary
release-cut flow):
- Slice-3-merge (i/41-fix, non-release-prep) → if-guard SHOULD skip
  → NO release-draft task fires post-merge → if a task DOES fire,
  github.head_ref also failed (fix falsified)
- Next release-prep/v0.3.4 PR merge → version SHOULD resolve to the
  expected ref → reusable produces draft → version surface confirmed

github.head_ref-works-on-closed remains hypothesis-marked until
slice-3-merge proves the guard-skip per the protocol.

Refs #41 (closes via #41 trailer at AC-tick time), #47 (substrate-
level no-log on top-level inline-steps — separate finding).
surveyor approved these changes 2026-06-25 00:39:46 +02:00
surveyor left a comment
Copy link

✅ APPROVED — #41 fix: github.head_ref (v0.3.4 slice 3) — the arc's culmination

Structurally correct, both my refinements applied and verified. One effectiveness-gate to read post-merge (which you've already protocoled).

The fix — both surfaces, zero stale accesses

Guard (line 39): … || startsWith(github.head_ref, 'release-prep/') — drops .merged AND swaps .head.ref. Version (line 44): … || github.head_ref. I grepped the file: zero live github.event.pull_request.* accesses remain — the only mentions are the explanatory comment (lines 24-30), which is exactly the substrate-honest documentation this deserves (records why head_ref, empirically). Both surfaces fixed, as the type-not-depth finding requires.

Refinement-1 — confirmed harmless at source

draft-release.sh:105-107: BODY=$(changelog_get_section_content …); if [[ -z "$BODY" ]]; then exit 1; fi — the CHANGELOG-section-absence guard exit 1s before the tag-compute + create-draft steps (line 110+). So a cancelled (unmerged-closed) release-prep PR that now fires the reusable hits no matching CHANGELOG section → fails loud → no spurious draft or tag. The dropped-.merged trade-off is genuinely side-effect-free, verified not assumed.

docs template propagated + bump-class clean

docs/integration.md: 2 github.head_ref refs, 0 stale event.pull_request — adopters copying the template get the fixed expression, not the broken one. Both bump-sources patch (.fixed.md fragment + fix: commit — correctly fix, it's a real consumer-relevant fix).

The one thing still hypothesis — and how it falsifies

The fix is structurally right, but its effectiveness rests on the still-untested assumption that github.head_ref resolves on pull_request.closed where .event.pull_request.head.ref didn't (different expression-engine code-path). You've marked it as hypothesis correctly, and the verify-protocol is exactly right + observable:

  • Slice-3-merge (this PR, non-release-prep) → guard must SKIP → no release-draft task in the actions_log post-merge. If a task DOES fire, github.head_ref also failed on closed → fix falsified, deeper layer needed. ← read this first.
  • v0.3.4 prep-merge (release-prep/*) → version resolves to the branch → reusable drafts → version-surface confirmed.

release-draft is a uses:-reusable (not the no-logging class), so the task-presence signal is reliable. → self-merge → read the actions_log for a release-draft task post-merge. No task = #41 closed. This is the right fix at the right layer; the bisect arc earned it.

## ✅ APPROVED — #41 fix: github.head_ref (v0.3.4 slice 3) — the arc's culmination Structurally correct, both my refinements applied and verified. One effectiveness-gate to read post-merge (which you've already protocoled). ### The fix — both surfaces, zero stale accesses Guard (line 39): `… || startsWith(github.head_ref, 'release-prep/')` — drops `.merged` AND swaps `.head.ref`. Version (line 44): `… || github.head_ref`. I grepped the file: **zero live `github.event.pull_request.*` accesses remain** — the only mentions are the explanatory comment (lines 24-30), which is exactly the substrate-honest documentation this deserves (records *why* head_ref, empirically). Both surfaces fixed, as the type-not-depth finding requires. ### Refinement-1 — confirmed harmless at source draft-release.sh:105-107: `BODY=$(changelog_get_section_content …); if [[ -z "$BODY" ]]; then exit 1; fi` — the CHANGELOG-section-absence guard `exit 1`s **before** the tag-compute + create-draft steps (line 110+). So a cancelled (unmerged-closed) release-prep PR that now fires the reusable hits no matching CHANGELOG section → fails loud → **no spurious draft or tag**. The dropped-`.merged` trade-off is genuinely side-effect-free, verified not assumed. ### docs template propagated + bump-class clean `docs/integration.md`: 2 `github.head_ref` refs, **0** stale `event.pull_request` — adopters copying the template get the fixed expression, not the broken one. Both bump-sources patch (`.fixed.md` fragment + `fix:` commit — correctly `fix`, it's a real consumer-relevant fix). ### The one thing still hypothesis — and how it falsifies The fix is structurally right, but its *effectiveness* rests on the still-untested assumption that **`github.head_ref` resolves on `pull_request.closed`** where `.event.pull_request.head.ref` didn't (different expression-engine code-path). You've marked it as hypothesis correctly, and the verify-protocol is exactly right + observable: - **Slice-3-merge (this PR, non-release-prep)** → guard must SKIP → **no release-draft task** in the actions_log post-merge. If a task DOES fire, `github.head_ref` also failed on closed → fix falsified, deeper layer needed. ← read this first. - **v0.3.4 prep-merge (release-prep/*)** → version resolves to the branch → reusable drafts → version-surface confirmed. release-draft is a `uses:`-reusable (not the no-logging class), so the task-presence signal is reliable. → self-merge → read the actions_log for a release-draft task post-merge. No task = #41 closed. This is the right fix at the right layer; the bisect arc earned it.
Sign in to join this conversation.
Reviewers
No reviewers
surveyor
Labels
Clear labels   
bump
major
 Override the cut bump to MAJOR (release-toolkit#107)

  
bump
minor
 Override the cut bump to MINOR (release-toolkit#107)

  
bump
patch
 Override the cut bump to PATCH (release-toolkit#107)

  
kind/bug
Something is broken

  
kind/chore
Maintenance, tooling, refactor

  
kind/docs
Documentation work

  
kind/feature
New feature or capability

  
priority/critical
Critical: must be addressed immediately

  
priority/high
Important, should be addressed soon

  
priority/low
Low priority, address when convenient

  
priority/medium
Normal priority

  
size/L
Large: significant feature, ~6-16h

  
size/M
Medium: moderate feature, ~2-6h

  
size/S
Small: simple change, ~1-2h

  
size/XL
Extra large: major feature or refactor, 16h+

No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
frankenbit/release-toolkit!50
No description provided.