fix(build-jupyter-cache): make container-mode failure alerting actually work (#83)

[mmcky]

Closes the alerting half of #83. Part 1 of that issue (sub-actions pinned @main) was already fixed; parts 2 and 3 are here.

Three bugs, one 14-line path

The path only runs once something else has already broken, which is why three independent defects accumulated on it unnoticed.

#	Bug	Why it was invisible
1	${{ github.action_path }} expands to the runner's path (/home/runner/work/_actions/...). Inside a job container: the action is mounted at /__w/_actions/..., so bash got a nonexistent path — No such file or directory, exit 127, before the script ran	The failing step was named "Create failure issue"; nobody reads that step on a run that already failed
2	Neither container image installs gh	Never reached — bash never got as far as executing the file
3	gh issue create --label validates labels client-side and fails when they don't exist. No consumer has build-failure or automated	Would have bitten even on a hosted runner with gh present

Bug 3 is new — it isn't in #83, and it means the alerting was broken on every runner type, not just in containers.

actions/github-script (REST, already the house pattern in both preview actions) kills all three: no CLI, no action_path, and the API creates missing labels implicitly.

A correction to the folk fix, so nobody "fixes" the wrong thing later: $GITHUB_ACTION_PATH does not have bug 1. Env values are rewritten by StepHost.TranslateToContainerPath before docker exec, so the env-var form arrives correctly as /__w/.... preview-netlify and preview-cloudflare use exactly that form and are correct as written — verified live, canary run 30971787039 executed bash "$GITHUB_ACTION_PATH/../scripts/detect-changed-lectures.sh" inside container: quantecon-build and it worked.

The second silent-failure class

Composite steps carry an implicit success() in a plain if:. So once any earlier step failed — including the alerting step itself — Fail if builds failed silently skipped, and the job's only error was whatever incidental step happened to break.

In lecture-dp run 26381283100 the visible red was the exit-127 from "Create failure issue", while the actual build failure never surfaced at all. Both steps are now always() && ….

Alerting can no longer no-op

A new step asserts an issue was genuinely filed and fails the job with an explicit error otherwise, exposing the URL as a new failure-issue-url output. The defect class here was silence, so the postcondition is asserted rather than trusted — this also survives someone later adding continue-on-error to the alert step.

⚠️ Consumers need issues: write while create-issue-on-failure is true. templates/cache.yml and the canary already declare it. A missing permission is now a loud failure whose message names the fix, instead of silence — that is the intended behaviour change, and the README example now shows the permissions block (it previously had none at all).

upload-failure-reports

New input, default true, passed to the three inner build-lectures calls. #83 says no report was uploaded; more precisely it was reachable only buried inside the full _build artifact — hundreds of MB including .jupyter_cache — and not at all when upload-artifact was off, while the issue body said "download the build artifact for detailed execution reports" and named nothing.

The body now names the artifacts actually produced and gives per-builder reproduce commands matching build-lectures' real flags (the old text printed jb build <dir> --builder jupyter, which is simply wrong — that builder is --builder=custom --custom-builder=jupyter -n).

The default deliberately differs from build-lectures' own false: that action is driven by a human watching a PR; this one runs unattended, typically weekly.

Evidence this was real, not theoretical

The canary repo's cache.yml (container mode, create-issue-on-failure: true) failed eight consecutive weeks, 2026-02-22 → 2026-04-12, filing zero issues — while linkcheck.yml, which uses a REST-API action rather than gh, filed a report every one of those weeks. Same repo, same period, same token.

Verification

• The github-script logic was run against mocked octokit for all three paths: create, dedupe-comment, and a 403 producing an actionable error before rethrowing. Artifact names and reproduce commands were checked against build-lectures' actual case statement.
• New harness job bjc-fail-guard: a failing cache build must fail the step, report html-status=failure, and save no cache over the last good one. That failure path had no coverage at all.
• Issue filing stays out of the PR harness deliberately — it needs issues: write and would file real issues in this repo on every run. That assertion belongs to the canary, which runs container-mode against @v0.

Still open on #83

Setup environment has no continue-on-error, so if it fails the composite aborts before verify-builds runs, all-passed is empty, and the alert guard's == 'false' is never true. Container-pull failures and image-tag rot therefore still alert nobody. Worth its own issue rather than widening this one.

Refs #83

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR hardens build-jupyter-cache’s failure path so container-mode failures reliably surface (via REST-based issue filing) and can’t silently no-op, while also improving debuggability by surfacing per-builder execution reports.

Changes:

• Replaced the failure-issue bash/gh path with an actions/github-script (Octokit/REST) implementation and added a postcondition check that fails loudly if alerting didn’t actually file an issue.
• Ensured failure-path steps run under always() so the real build failure is not masked/skipped after earlier step failures.
• Added upload-failure-reports input (default true) and a CI harness job to assert failure-path contract (fails the step, correct status outputs, no cache overwrite).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
CHANGELOG.md	Documents the failure-alerting fixes, new input, and new CI harness coverage.
build-jupyter-cache/scripts/create-failure-issue.sh	Removes the old gh-based issue creation script.
build-jupyter-cache/README.md	Updates inputs/outputs docs and clarifies required issues: write permission and artifact/debug guidance.
build-jupyter-cache/action.yml	Implements REST-based issue filing, adds verification guard, propagates upload-failure-reports, and makes failure steps always()-safe.
.github/workflows/test-actions.yml	Adds bjc-fail-guard harness job asserting the failure-path contract.