fix: pass explicit commit-message to wrangler (snapshot.yml + web-deploy.yml)

[bpamiri]

Summary

Run 25641189988 (snapshot for PR #2549's merge) succeeded on the BE pipeline core but failed on the parallel deploy-api-snapshot job. Cloudflare API rejected the deploy:

ERROR: A request to the Cloudflare API (.../pages/.../deployments) failed.
  Invalid commit message, it must be a valid UTF-8 string. [code: 8000111]

While diagnosing, I discovered web-deploy.yml has the same wrangler invocation with the same omission. That workflow runs on every push to develop/main across 5 sites. If v4.0.0 GA's tag commit body has non-ASCII characters (very likely in release notes), all 5 deploys would fail tomorrow.

Fixing both in this PR.

Root cause

When --commit-message is omitted, wrangler auto-derives the message from the latest git commit. PR #2549's auto-generated GitHub merge commit body contained em-dashes (—) and arrows (→) — valid UTF-8 but Cloudflare's API rejects them anyway. CF's error says "UTF-8" but the actual rule appears stricter (possibly ASCII-only).

This wasn't caught by prior snapshot deploys because earlier PR merge messages happened to be plain ASCII.

Fix (applied to both workflows)

Pass --commit-message explicitly with an ASCII-only string composed of controlled values:

snapshot.yml (deploy-api-snapshot job):

--commit-message="snapshot deploy: ${VERSION}-snapshot (run ${GITHUB_RUN_ID})"

web-deploy.yml (5-site matrix deploy):

--commit-message="deploy ${SITE} from ${DEPLOY_BRANCH} (run ${GITHUB_RUN_ID})"

No user-content flows into the API call. Bonus: every deploy is now self-describing in CF Pages's deployment list.

Test plan

• CI green (commitlint, etc.)
• After merge: next develop snapshot's deploy-api-snapshot succeeds and updates api.wheels.dev
• Tomorrow's v4.0.0 GA: web-deploy.yml deploys all 5 sites cleanly (guides, blog, api, landing, packages)

Why this matters for Tuesday GA

Without the web-deploy.yml fix, tomorrow's v4.0.0 tag would likely fail to deploy ANY of the 5 sites if the release notes commit body has typical em-dash/arrow content. Merging this PR before Tuesday is a meaningful pre-GA derisking.

Refs

• Failed run: https://github.com/wheels-dev/wheels/actions/runs/25641189988
• Triggering PR: docs: add release channels page; link from installing.mdx #2549 (docs PR with em-dashes / arrows in commit body)

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: PR #2550 is a well-targeted one-liner fix for a real CI failure. The root cause diagnosis is accurate (Cloudflare's API rejects non-ASCII characters in auto-derived commit messages from wrangler), and the chosen fix — passing a controlled ASCII-only --commit-message — is correct and safe. One commit-type convention nit and one follow-up item to note, but neither blocks merge.

---

Correctness

The fix is sound. Walking through it:

1. VERSION=$(jq -r '.version' ../wheels.json) — the working-directory: web context makes ../wheels.json the right path (the preceding "Generate snapshot markdown" step, which runs without a working-directory, uses wheels.json directly from the repo root; both resolve to the same file). No path confusion.

2. The resulting message "snapshot deploy: ${VERSION}-snapshot (run ${GITHUB_RUN_ID})" will always be ASCII-only: VERSION is a semver string read from a repo-controlled file, and GITHUB_RUN_ID is a numeric string provided by GitHub Actions. No user content flows into the Cloudflare API call.

3. One minor robustness concern: if jq cannot read ../wheels.json or the .version key is absent, it returns the literal string null, yielding "snapshot deploy: null-snapshot (run …)". This would still satisfy Cloudflare's ASCII requirement (the deploy wouldn't fail), but the CF Pages history entry would be misleading. Given that the "Generate snapshot markdown" step immediately before this one already reads the same file successfully, this is a purely theoretical edge case and not a blocker.

---

Commits

Nit — The commit type is fix:, but CLAUDE.md § "Common scope choices by file path" states:

.github/workflows/... | type ci, no scope (e.g. ci: pin softprops…)

The canonical form would be:

ci: pass explicit commit-message to wrangler in deploy-api-snapshot

commitlint won't hard-reject fix: (it is in the allowed-types list), so this won't break CI, but it's out of convention for workflow-only changes. Worth a quick git commit --amend before merging.

---

Docs

The PR body mentions auditing web-deploy.yml for the same gap. Looking at .github/workflows/web-deploy.yml lines 66-69:

pnpm dlx wrangler@4.78.0 pages deploy "sites/${SITE}/dist" \
  --project-name="wheels-${SITE}" \
  --branch="${DEPLOY_BRANCH}" \
  --commit-hash="${GITHUB_SHA}"

Same pattern — no --commit-message. A release tag fired on a commit whose message contains em-dashes or arrows (possible with merge commits) would hit the same CF rejection. The author flagged this as a follow-up, which is the right call given the v4.0.0 GA timeline. Recommend opening a follow-up issue so it doesn't get lost.

---

Security

No concerns. Both interpolated values (${VERSION}, ${GITHUB_RUN_ID}) are controlled — one from a repo file, one from the Actions runtime. The comment block in the diff correctly documents this: "Both ${VERSION} (read from wheels.json) and ${GITHUB_RUN_ID} are controlled values."

---

Overall the fix is correct and the self-describing commit message is a net improvement for observability in CF Pages. Only the fix: → ci: type swap and the web-deploy.yml follow-up issue creation are worth doing before or shortly after merge.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: PR #2550 now covers both workflows (snapshot.yml + web-deploy.yml). The second commit addresses the gap called out in the previous review. The fix is correct in both locations. The only remaining item is the same commit-type convention nit: both commits use fix: for workflow-only changes where ci: is the project standard. Verdict: comment (convention nit only, nothing blocking).

---

Correctness

Both changes are sound.

snapshot.yml — unchanged from the first commit; analysis stands. VERSION is read from ../wheels.json (correct relative path under working-directory: web), GITHUB_RUN_ID is a numeric Actions-runtime value. The resulting message is guaranteed ASCII-only.

web-deploy.yml — new in this PR update. Three interpolated values:

• SITE comes from matrix.site, a controlled matrix list (api, guides, blog, landing, packages). Safe.
• DEPLOY_BRANCH comes from github.head_ref || github.ref_name. This value was already being passed as-is to --branch="${DEPLOY_BRANCH}" before this PR, so any non-ASCII branch name would have caused a Cloudflare failure on that argument already. This PR introduces no new exposure.
• GITHUB_RUN_ID is a numeric string from the Actions runtime. Safe.

One theoretical edge: if DEPLOY_BRANCH contained a non-ASCII character, it would now appear in --commit-message as well as in --branch. Since Cloudflare already received it on --branch prior to this change, this is not a regression introduced here. Not a blocker.

---

Commits

Convention nit - both commits use type fix:, but CLAUDE.md "Common scope choices by file path" states:

.github/workflows/... maps to type ci, no scope (e.g. ci: pin softprops...)

The canonical forms would be:

ci: pass explicit commit-message to wrangler in deploy-api-snapshot
ci: pass explicit commit-message to wrangler in web-deploy.yml too

commitlint allows fix: (it is in the allowed-types list) so CI will not reject these, but the convention for pure workflow changes is ci:. Worth an amend + force-push before merge if the author wants to clean this up; not a blocker.

---

Follow-up item resolved

The previous Reviewer A comment (for commit d8da07a27) flagged the missing --commit-message in web-deploy.yml as a follow-up risk ahead of v4.0.0 GA. This second commit addresses it. No open follow-up items remain from that review.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is accurate on the core finding (fix is correct, commit type should be ci:) but was written against commit d8da07a27 before a second commit (1791670b1) was pushed adding the web-deploy.yml fix. One false positive and two downstream nits follow from that timing gap. The fixes are functionally complete at the current head; converging approve with the notes below for the human to act on.

Sycophancy

None detected. A correctly identified the root cause, walked through the variable sources, and flagged a real convention issue without inflating the verdict.

False positives

• A's "Docs" section warns that web-deploy.yml still lacks --commit-message and recommends opening a follow-up issue before GA. This was accurate when A reviewed (d8da07a27) but is stale at current HEAD: the second commit (1791670b1, pushed after A's review) already applies the identical fix to web-deploy.yml. No follow-up issue is needed — the PR as merged covers both workflows.

Missed issues

• Second commit not reviewed. A's review covered only snapshot.yml. The web-deploy.yml changes in 1791670b1 were not in scope. One mild concern there: --commit-message="deploy ${SITE} from ${DEPLOY_BRANCH} (run ${GITHUB_RUN_ID})" uses ${DEPLOY_BRANCH}, which derives from ${{ github.head_ref || github.ref_name }}. Unlike ${VERSION} (semver from a repo-controlled file) and ${GITHUB_RUN_ID} (numeric), branch names can technically contain non-ASCII characters, creating a slight inconsistency with the comment's claim of "a controlled ASCII string." Practical risk is very low given Wheels branch naming is ASCII-only in practice, and the fix is still a major improvement over letting wrangler auto-derive from merge commit bodies. Worth a code-comment clarification but not a blocker.

• git commit --amend suggestion doesn't apply. A recommends amending the first commit from fix: to ci:. The PR now has two commits, both using fix:. Amending only one would leave the second unconverted. The correct remediation is an interactive rebase (git rebase -i) converting both, or squashing into a single ci: pass explicit commit-message to wrangler (snapshot.yml + web-deploy.yml).

Verdict alignment

A used COMMENTED state while saying the amend is worth doing "before merging" — REQUEST_CHANGES would be more precise for a stated pre-merge requirement, but COMMENTED is defensible since fix: is commitlint-valid and won't block CI.

Convergence

A and I agree: both fixes are correct and complete, and the one outstanding item is the commit type on both commits (fix: -> ci:). A already surfaced this; I've corrected that it applies to both commits and that --amend alone isn't sufficient. No blocking issues remain. The human can squash/rebase to ci: before merging or accept the minor style deviation — either is safe to ship.

[wheels-bot]

Wheels Bot - Reviewer B (round 1)

A's review is accurate and well-evidenced. The only substantive finding (commit type convention) is real, and A correctly labeled it non-blocking. Aligned with A; marking converged-changes so the commit messages can be cleaned up before merge.

Sycophancy

None detected. A issued a COMMENTED verdict with a concrete nit rather than a bare LGTM, and explicitly called the nit non-blocking. That framing is appropriate.

False positives

None detected.

• ../wheels.json path claim -- A asserts that working-directory: web on the Deploy to Cloudflare Pages step makes ../wheels.json the correct path to the repo root. Verified: the step does carry working-directory: web, so ../wheels.json is correct. A's path reasoning holds.
• Commit-type nit (fix: to ci:) -- verified against CLAUDE.md section Common scope choices by file path: .github/workflows/... maps to type ci, no scope. Both commits (d8da07a and 1791670) use fix:. A's claim is accurate.

Missed issues

None of substance. A's DEPLOY_BRANCH analysis is technically sound -- Cloudflare may validate --branch and --commit-message under different rules, but since GitHub branch names are ASCII-safe in all realistic CI scenarios, this is not a missed issue. A noted the jq null fallback in the first review and correctly carried it forward.

Verdict alignment

A's comment verdict is consistent with a single non-blocking convention nit and otherwise-sound code. Appropriate.

Convergence

Aligned. The code changes are correct in both workflows; the only finding is the fix: to ci: commit-type swap, which A correctly identifies as a convention matter that commitlint won't hard-reject. Joint recommendation: amend both commit messages to ci: type before merge. Marking converged-changes to trigger cleanup.

[wheels-bot]

Wheels Bot — Address Review held for human review

The converged consensus from Reviewer A and Reviewer B has exactly one actionable finding: retype both commits on this PR from fix: to ci: to match CLAUDE.md's convention for .github/workflows/... changes. Both reviewers explicitly classified this as non-blocking (commitlint allows fix:).

This finding cannot be addressed by a forward-only commit on the existing branch:

• It requires rewriting both existing commit messages (d8da07a2 and 1791670b), which means git commit --amend + git rebase -i + a force-push.
• The wheels-bot shared rails forbid history-rewriting operations (git push --force, git reset --hard, git rebase -i, history-mutating subcommands) — the address-review flow is designed to add a new commit, not retype prior ones.
• This PR is on peter/fix-wrangler-commit-message rather than a fix/bot-* branch, so the address-review path's branch-scope assumptions don't cleanly apply either.

Recommendation for the human: either

1. Locally amend/rebase both commits to ci: type and force-push (the reviewers' joint recommendation), or
2. Squash-merge with a ci: subject line — the PR's final commit message on develop is what shows up in history, and commitlint runs per-commit on the PR head but not on the squashed merge result.
3. Or accept the fix: type as-is — both reviewers agreed it's non-blocking and CI will not reject it.

The code changes themselves are correct in both files (snapshot.yml + web-deploy.yml) per both reviewers; only the commit message convention is outstanding.