install_awf_binary.sh fails permanently when pinned gh-aw-firewall release does not exist (404); v0.25.21–v0.25.39 are missing

[IEvangelist]

Bug Report — install_awf_binary.sh cannot recover when pinned gh-aw-firewall release does not exist (404)

Summary

Compiled workflows (*.lock.yml) embed a specific gh-aw-firewall (awf) version via GH_AW_INFO_AWF_VERSION and pass it to install_awf_binary.sh. If that release no longer exists on github/gh-aw-firewall, the install step fails with curl: (22) The requested URL returned error: 404 and the workflow aborts before the agent runs — producing a downstream failure comment with no useful context.

This bug is currently affecting every previously‑compiled pr-docs-check workflow in microsoft/aspire that pinned awf v0.25.28: 15 distinct workflow runs over the past ~12 days have failed at this step.

Reproduction

1. Compile any workflow with a version of gh-aw that pinned awf v0.25.28 (e.g., gh-aw v0.71.x and earlier — pre‑v0.72.0).
2. Trigger the workflow.
3. The Install awf binary step runs:

   bash "${RUNNER_TEMP}/gh-aw/actions/install_awf_binary.sh" v0.25.28
   Installing awf with checksum verification (version: v0.25.28, os: Linux, arch: x86_64)
   Downloading checksums from 'https://github.com/github/gh-aw-firewall/releases/download/v0.25.28/checksums.txt'...
   curl: (22) The requested URL returned error: 404
   ##[error]Process completed with exit code 22.
   

4. The agent step never runs. The failure handler posts an extremely terse comment to the existing failure issue (no diagnostics).

Root cause

github/gh-aw-firewall has a release gap: tags v0.25.21 through v0.25.39 do not exist on the releases endpoint:

$ gh api repos/github/gh-aw-firewall/releases --jq '.[].tag_name' | sort -V
… v0.25.18, v0.25.19, v0.25.20, v0.25.40, v0.25.41, v0.25.42 …

It looks like one or more releases in that range were deleted (or never published after a version bump in the gh-aw compiler). Any compiled workflow that captured a tag in the gap is now permanently broken until either:

• the workflow is recompiled against a newer gh-aw (manual action by every user), or
• the missing releases are re‑published.

install_awf_binary.sh has no fallback path: it set -e exits as soon as the checksum download 404s.

Affected runs (microsoft/aspire pr-docs-check, all pinned awf v0.25.28)

15 runs in the last ~12 days:

Run	Date (UTC)
25467588686	2026‑05‑06
25476576962	2026‑05‑07
25480215464	2026‑05‑07
25503081313	2026‑05‑07
25506161577	2026‑05‑07
25699326056	2026‑05‑11
25699293489	2026‑05‑11
25699559470	2026‑05‑11
25826083607	2026‑05‑13
25831283389	2026‑05‑13
25879145495	2026‑05‑14
25879025905	2026‑05‑14
25883720698	2026‑05‑14
25885698482	2026‑05‑14
25996129485	2026‑05‑17

All 15 surface as the same generic failure comment on microsoft/aspire#16138 because of the failure‑issue aggregation bug already filed as #33060.

Suggested fixes (any one or combination)

1. Re‑publish the missing releases (v0.25.21–v0.25.39) on github/gh-aw-firewall so existing compiled workflows can install. This is the cheapest fix and unblocks every existing compiled workflow.
2. Make install_awf_binary.sh fallback to a known-good version when the pinned tag 404s. The script could:
   • Probe releases/latest and use that if the pinned version 404s, or
   • Have a hard‑coded minimum/maximum fallback list.
3. Validate the pinned version exists at compile time in gh-aw so we never embed a missing tag into a .lock.yml.
4. Improve the failure surface: when install_awf_binary.sh fails (or any pre‑agent step fails), the downstream failure handler should include the underlying error (curl: (22) ...) rather than emitting a bare "Agent job failed." comment.

Workaround for affected users

Recompile workflows against gh-aw v0.72.0 or newer:

gh extension upgrade github/gh-aw
gh aw compile
git commit -am "Recompile workflows for newer awf"

(But this needs to be done by every consumer; the fundamental gap in published releases is what makes the problem widespread.)

Environment

• gh-aw compiled at: v0.71.x (pre‑v0.72.0)
• awf pinned: v0.25.28
• Runner: ubuntu-latest / ubuntu24.04
• Failure handler: actions/setup/js/handle_agent_failure.cjs
• Install script: actions/setup/sh/install_awf_binary.sh

[pelikhan]

@salmanmkc we need upgrade policy for awf as well (gh-aw-firewall)