refresh-visual-baselines workflow direct-push is rejected by the develop ruleset

[bpamiri]

What happened

Dispatching Actions → Refresh visual baselines (sites=guides, ref develop) on 2026-07-06 completed the rebuild + screenshot + --update steps successfully, then failed at Commit and push refreshed baselines:

remote: error: GH013: Repository rule violations found for refs/heads/develop.
remote: - Changes must be made through a pull request.
remote: - 3 of 3 required status checks are expected.
! [remote rejected]     HEAD -> develop (push declined due to repository rule violations)

Run: https://github.com/wheels-dev/wheels/actions/runs/28789467591

The workflow predates the develop branch ruleset — it commits the refreshed PNG(s) and pushes HEAD -> $BRANCH directly, which the ruleset now forbids for develop.

Fix

Convert the final step to the PR + auto-merge pattern already used elsewhere in this repo: push the commit to a chore/refresh-baseline-<sites>-<run_id> branch, gh pr create against the target branch, and gh pr merge --auto --squash --delete-branch.

Two known gotchas from prior conversions of this exact kind:

• The token needs pull-requests: write in addition to contents: write — missing scope fails silently.
• The PR title must be a valid conventional commit ≤100 chars (the Validate Commit Messages required check lints PR titles).

Workaround used meanwhile

Manual PR with the CI-rendered screenshot (#3282). Note for anyone doing the same: baselines must be Linux/CI-rendered — a locally captured macOS screenshot diffs against CI font rendering everywhere.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. (Caveat: this is a CI-workflow defect in .github/workflows/, which sits outside the framework runtime layers; the file and copy-source below are the authoritative targets.)

Fix sketch

The fix lives entirely in .github/workflows/refresh-visual-baselines.yml. Its final Commit and push refreshed baselines step runs git push origin "HEAD:$BRANCH", a direct push the develop ruleset now rejects (GH013: Changes must be made through a pull request). Convert that step to the PR + auto-merge pattern already proven in the sibling .github/workflows/refresh-packages-baseline.yml: push the commit to a chore/refresh-baseline-<sites>-<run_id> branch, gh pr create against the target branch, then gh pr merge --auto --squash --delete-branch. Two mechanical requirements the issue and the sibling workflow both confirm: add pull-requests: write to the job permissions: block (it currently only has contents: write), and keep the PR title a valid conventional-commit <=100 chars so the Validate Commit Messages required check passes (the existing chore(web): refresh visual baseline(s) (<sites>) subject already satisfies this).

Confidence: high

Clear what-happened/what-expected, a single unambiguous target file, and a working in-repo workflow (refresh-packages-baseline.yml) to copy the pattern from verbatim; no auto-downgrade rule applies (workflow YAML, not security/middleware/migration/deploy/DI/cross-engine code).

[wheels-bot]

Wheels Bot — Fix ready, but blocked from opening a PR (workflows permission)

A complete, validated fix for this issue is ready — but the bot cannot push it or open the PR itself, because the fix necessarily edits .github/workflows/refresh-visual-baselines.yml, and GitHub refuses to let the bot's GitHub App create or update workflow files without the workflows permission:

 ! [remote rejected] fix/bot-3283-... -> fix/bot-3283-...
   (refusing to allow a GitHub App to create or update workflow
    `.github/workflows/refresh-visual-baselines.yml` without `workflows` permission)

The committed branch lives only in this run's ephemeral checkout, so the full patch is embedded below for a human to apply.

What the fix does

Exactly the triage's recommended path — the sibling refresh-packages-baseline.yml PR pattern:

1. Replaces the final git push origin "HEAD:$BRANCH" (rejected by the develop ruleset with GH013: Changes must be made through a pull request) with a chore/refresh-baseline-* branch → gh pr create → gh pr merge --auto --squash --delete-branch flow.
2. Adds pull-requests: write to the job permissions: (the missing scope otherwise fails the gh pr calls silently).
3. Keeps the PR title a valid conventional commit ≤100 chars (chore(web): refresh visual baseline(s) (<sites>)) so the Validate Commit Messages required check passes.
4. Extracts the branch→commit→PR→auto-merge flow into tools/gh-open-refresh-baseline-pr.sh (injection-safe: all user-controllable values routed through env, never spliced into a shell string) so it is a reviewable, reusable, unit-pinned artifact the workflow simply invokes.

TDD — verified failing → passing

Static-content regression spec (matching the established BotResolveConflictsLoopSafeSpec pattern for CI-workflow fixes), run against the local Lucee 7 + SQLite server (/wheels/core/tests?directory=wheels.tests.specs.cli):

• Red (pre-fix working tree — direct push restored, helper neutralized): RefreshVisualBaselinesPrPushSpec → totalPass 0, totalFail 4. First failure:

  issue refresh-visual-baselines workflow direct-push is rejected by the develop ruleset #3283: refresh-visual-baselines.yml must NOT push the refreshed baseline commit straight to the dispatched branch (git push origin "HEAD:$BRANCH") — the develop ruleset rejects it with GH013. Route the commit through a PR + auto-merge instead.

• Green (post-fix): full cli package → 21 bundles, 131 pass, 0 fail, 0 error (the new spec contributes 4 passing tests; nothing regressed).

What a maintainer needs to do

A GitHub App / PAT with workflows: write (or a human push) is required. Either:

• If the branch fix/bot-3283-refresh-visual-baselines-workflow-direct-push-is-r reached origin, open a draft PR from it against develop titled fix(ci): route refreshed visual baselines through a PR instead of a direct push, or
• Apply the patch below (git am < patch or copy the files), then push and open that PR.

Note the title uses type ci (a valid conventional-commit type; ci is a type, not a scope).

Full patch (git am / git apply) — commit 8b79fdbcf, signed off

From 8b79fdbcf9e7b6e0a2b0e318ce0bfbc9fbb9dc82 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Mon, 6 Jul 2026 12:13:50 +0000
Subject: [PATCH] fix(ci): route refreshed visual baselines through a PR
 instead of a direct push

Refs #3283

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
---
diff --git a/.github/workflows/refresh-visual-baselines.yml b/.github/workflows/refresh-visual-baselines.yml
index 93969ac78..bdf2a0add 100644
--- a/.github/workflows/refresh-visual-baselines.yml
+++ b/.github/workflows/refresh-visual-baselines.yml
@@ -15,11 +15,13 @@ name: Refresh visual baselines
 #      - "Use workflow from": select the PR's source branch.
 #      - "Which baseline(s) to refresh": pick the affected site, or "all".
 #   4. The workflow rebuilds the sites, screenshots the canary page(s),
-#      writes the new PNG(s) into web/tests/visual-baselines/, and pushes
-#      the commit back to the same branch.
-#   5. That push retriggers the PR's CI; `visual-regression` should now pass.
-#      (You can also click "Re-run failed jobs" on the original PR run if
-#      you'd rather not wait for a full CI re-run.)
+#      writes the new PNG(s) into web/tests/visual-baselines/, and opens a
+#      `chore/refresh-baseline-*` PR against the dispatched branch with
+#      auto-merge enabled. (Direct pushes are rejected by the develop branch
+#      ruleset — see #3283 — so the refresh always arrives as a PR.)
+#   5. Once that PR merges, its commit lands on the branch and retriggers CI;
+#      `visual-regression` should now pass. If auto-merge is disabled on the
+#      repo the PR is left open for a manual merge.
 #
 # Why this exists alongside refresh-packages-baseline.yml:
 #   - refresh-packages-baseline.yml fires automatically when the
@@ -70,6 +72,11 @@ jobs:
     timeout-minutes: 30
     permissions:
       contents: write
+      # Needed by tools/gh-open-refresh-baseline-pr.sh: the develop ruleset
+      # forbids the old direct push, so the refreshed baseline is delivered
+      # through `gh pr create` + `gh pr merge --auto`, which require this scope
+      # (a `contents: write`-only token fails the PR calls silently). See #3283.
+      pull-requests: write
     steps:
       - name: Checkout target branch
         uses: actions/checkout@v6
@@ -141,40 +148,21 @@ jobs:
             git diff --name-only -- web/tests/visual-baselines/
           fi
 
-      - name: Commit and push refreshed baselines
+      - name: Open refresh PR and enable auto-merge
         if: steps.changes.outputs.changed == 'true'
+        # The develop branch ruleset forbids a direct push ("Changes must be
+        # made through a pull request"), so instead of committing the refreshed
+        # PNG(s) straight back to the dispatched branch we route them through a
+        # throwaway `chore/refresh-baseline-*` branch, open a PR, and enable
+        # auto-merge. The branch/commit/PR/auto-merge flow lives in
+        # tools/gh-open-refresh-baseline-pr.sh (shared, reviewable, unit-pinned
+        # by RefreshVisualBaselinesPrPushSpec). See #3283.
         env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SITES: ${{ inputs.sites }}
-          BRANCH: ${{ github.ref_name }}
-        run: |
-          set -euo pipefail
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add web/tests/visual-baselines/
-
-          # Build the commit message in a temp file so the heredoc body stays
-          # readable inside the YAML and the SITES value is never spliced into
-          # a shell-expanded string. SITES is constrained to the choice list
-          # above, but writing through a file keeps that contract obvious.
-          #
-          # Branch name lives on its own line so long names (e.g. bot-generated
-          # fix/bot-NNNN-<slug>) can't push the body past the 100-char
-          # body-max-line-length enforced by commitlint.
-          commit_msg_file="$(mktemp)"
-          {
-            printf '%s\n\n' "chore(web): refresh visual baseline(s) ($SITES)"
-            printf '%s\n' "Manually triggered baseline refresh via"
-            printf '%s\n' ".github/workflows/refresh-visual-baselines.yml"
-            printf '%s\n\n' "on branch $BRANCH."
-            printf '%s\n' "Run when an intentional content/layout change makes the visual-regression"
-            printf '%s\n' "check fail. The new PNG(s) under web/tests/visual-baselines/ are now the"
-            printf '%s\n' "expected rendering; re-run the failing visual-regression job to flip the"
-            printf '%s\n' "check green."
-          } > "$commit_msg_file"
-
-          git commit -F "$commit_msg_file"
-          rm -f "$commit_msg_file"
-          git push origin "HEAD:$BRANCH"
+          TARGET_BRANCH: ${{ github.ref_name }}
+          RUN_ID: ${{ github.run_id }}
+        run: bash tools/gh-open-refresh-baseline-pr.sh
 
       - name: Write step summary
         if: always()
@@ -189,14 +177,16 @@ jobs:
             echo "- **Target branch:** \`$BRANCH\`"
             echo "- **Sites requested:** \`$SITES\`"
             if [ "$CHANGED" = "true" ]; then
-              echo "- **Result:** Baseline(s) committed and pushed."
+              echo "- **Result:** Refresh PR opened against \`$BRANCH\` (auto-merge enabled)."
               echo
               echo "### Next step"
               echo
-              echo "The push to \`$BRANCH\` will retrigger CI automatically — the"
-              echo "\`visual-regression\` check on the next run should pass. If you'd rather"
-              echo "not wait for a full CI cycle, open the failing run on the PR and click"
-              echo "**Re-run failed jobs**."
+              echo "A \`chore/refresh-baseline-*\` PR carries the refreshed baseline(s) — the"
+              echo "develop branch ruleset requires changes to arrive via a pull request (see"
+              echo "#3283). It auto-merges once the required checks pass; when its commit lands"
+              echo "on \`$BRANCH\` it retriggers CI and \`visual-regression\` should pass. If"
+              echo "auto-merge is disabled on the repo, merge the PR manually. See the job log"
+              echo "for the PR link."
             elif [ "$CHANGED" = "false" ]; then
               echo "- **Result:** No baseline drift detected — nothing to commit."
               echo
diff --git a/changelog.d/3283-refresh-baselines-pr-push.fixed.md b/changelog.d/3283-refresh-baselines-pr-push.fixed.md
new file mode 100644
index 000000000..12102ec2f
--- /dev/null
+++ b/changelog.d/3283-refresh-baselines-pr-push.fixed.md
@@ -0,0 +1 @@
+- The **Refresh visual baselines** workflow (`.github/workflows/refresh-visual-baselines.yml`) no longer pushes the refreshed PNG(s) directly to the dispatched branch, which the `develop` branch ruleset rejected with `GH013: Changes must be made through a pull request`. It now routes the refresh through a `chore/refresh-baseline-*` PR with auto-merge (via the new `tools/gh-open-refresh-baseline-pr.sh` helper) and grants the job `pull-requests: write` (#3283)
diff --git a/tools/gh-open-refresh-baseline-pr.sh b/tools/gh-open-refresh-baseline-pr.sh
new file mode 100644
index 000000000..1746bdfaf
--- /dev/null
+++ b/tools/gh-open-refresh-baseline-pr.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Open a PR carrying a refreshed visual-regression baseline, then enable
+# auto-merge — so the change lands WITHOUT a direct push to a ruleset-protected
+# branch.
+#
+# Extracted from .github/workflows/refresh-visual-baselines.yml for issue #3283:
+# that workflow's final step pushed the refreshed PNG(s) straight to the
+# dispatched branch, which the `develop` branch ruleset now rejects:
+#
+#   remote: error: GH013: Repository rule violations found for refs/heads/develop.
+#   remote: - Changes must be made through a pull request.
+#
+# This mirrors the PR flow already used by
+# .github/workflows/refresh-packages-baseline.yml, and additionally enables
+# GitHub auto-merge so the refresh lands unattended once the required checks pass.
+#
+# Contract:
+#   - CWD is the repository root.
+#   - The working tree already holds the refreshed, UNSTAGED baseline file(s).
+#
+# Inputs (all via env, never spliced into an eval'd string — this preserves the
+# workflow's Actions-injection-safe posture; see the workflow's security note):
+#   SITES         which baseline(s) were refreshed (used in the title/body/branch)
+#   TARGET_BRANCH branch the PR merges into (github.ref_name)
+#   RUN_ID        github.run_id — makes the throwaway branch name unique
+#   ADD_PATHS     git pathspec(s) to stage (default: web/tests/visual-baselines/)
+#   GH_TOKEN      token with BOTH contents:write and pull-requests:write
+#
+# SITES is constrained to the workflow's `choice` input list and RUN_ID is a
+# numeric run id, so both are safe to interpolate into the branch name and the
+# --title/--body arguments (each reaches git/gh as a single argv element, never
+# a shell-expanded command string).
+
+set -euo pipefail
+
+: "${SITES:?SITES is required}"
+: "${TARGET_BRANCH:?TARGET_BRANCH is required}"
+: "${RUN_ID:?RUN_ID is required}"
+ADD_PATHS="${ADD_PATHS:-web/tests/visual-baselines/}"
+
+branch="chore/refresh-baseline-${SITES}-${RUN_ID}"
+
+git config user.name "github-actions[bot]"
+git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+git checkout -b "$branch"
+# Word-split ADD_PATHS on purpose so callers can pass multiple pathspecs; the
+# value is workflow-controlled, never user input.
+# shellcheck disable=SC2086
+git add -- $ADD_PATHS
+
+# Build the commit message in a temp file so the heredoc body stays readable and
+# no value is spliced into a shell-expanded string. The subject matches the old
+# direct-push commit and stays a valid conventional commit <=100 chars, which the
+# "Validate Commit Messages" required check lints against the PR title. The
+# branch name lives on its own body line so a long TARGET_BRANCH can't push a
+# body line past commitlint's 100-char body-max-line-length.
+commit_msg_file="$(mktemp)"
+{
+  printf '%s\n\n' "chore(web): refresh visual baseline(s) ($SITES)"
+  printf '%s\n' "Manually triggered baseline refresh via"
+  printf '%s\n' ".github/workflows/refresh-visual-baselines.yml"
+  printf '%s\n\n' "targeting branch $TARGET_BRANCH."
+  printf '%s\n' "Run when an intentional content/layout change makes the visual-regression"
+  printf '%s\n' "check fail. The new PNG(s) under web/tests/visual-baselines/ are now the"
+  printf '%s\n' "expected rendering."
+} > "$commit_msg_file"
+
+git commit -F "$commit_msg_file"
+rm -f "$commit_msg_file"
+
+git push -u origin "$branch"
+
+pr_body_file="$(mktemp)"
+{
+  printf '%s\n\n' "## Summary"
+  printf '%s\n\n' "Refreshes the visual-regression baseline(s) for \`$SITES\` so the \`visual-regression\` check reflects the intended rendering."
+  printf '%s\n\n' "Opened automatically by \`.github/workflows/refresh-visual-baselines.yml\` (run \`$RUN_ID\`), which routes the refreshed PNG(s) through a PR instead of a direct push — the \`$TARGET_BRANCH\` branch ruleset requires changes to arrive via a pull request."
+  printf '%s\n' "## Test plan"
+  printf '%s\n' "- [ ] \`visual-regression\` job passes on this PR"
+  printf '%s\n' "- [ ] The baseline diff contains only the intended content/layout change (not font/rendering drift)"
+} > "$pr_body_file"
+
+# gh prints the new PR's URL on stdout; capture it so the auto-merge call
+# targets exactly this PR.
+pr_url="$(gh pr create \
+  --base "$TARGET_BRANCH" \
+  --head "$branch" \
+  --title "chore(web): refresh visual baseline(s) ($SITES)" \
+  --body-file "$pr_body_file")"
+
+rm -f "$pr_body_file"
+
+echo "Opened refresh PR: $pr_url"
+
+# Enable auto-merge so the PR lands once the required checks pass — no human
+# round-trip. If the repository has auto-merge disabled, don't fail the whole
+# refresh job: the PR is already open for a human to merge manually.
+if gh pr merge "$pr_url" --auto --squash --delete-branch; then
+  echo "Auto-merge enabled — the PR will land once required checks pass."
+else
+  echo "Could not enable auto-merge (is it disabled on this repo?); PR left open for manual merge: $pr_url"
+fi
diff --git a/vendor/wheels/tests/specs/cli/RefreshVisualBaselinesPrPushSpec.cfc b/vendor/wheels/tests/specs/cli/RefreshVisualBaselinesPrPushSpec.cfc
new file mode 100644
index 000000000..caea24f10
--- /dev/null
+++ b/vendor/wheels/tests/specs/cli/RefreshVisualBaselinesPrPushSpec.cfc
@@ -0,0 +1,115 @@
+component extends="wheels.WheelsTest" {
+
+	// Regression for issue ##3283.
+	//
+	// The final "Commit and push refreshed baselines" step in
+	// .github/workflows/refresh-visual-baselines.yml pushed the refreshed PNG(s)
+	// straight back to the dispatched branch with `git push origin "HEAD:$BRANCH"`.
+	// Once the `develop` branch ruleset started requiring "Changes must be made
+	// through a pull request", that direct push is rejected with
+	// `GH013: Repository rule violations found` and the workflow fails after doing
+	// all the expensive rebuild + screenshot work.
+	//
+	// The fix converts the final step to the PR + auto-merge pattern already used
+	// by the sibling .github/workflows/refresh-packages-baseline.yml: commit onto a
+	// throwaway `chore/refresh-baseline-*` branch, `gh pr create` against the
+	// target branch, and `gh pr merge --auto --squash --delete-branch`. That path
+	// also needs `pull-requests: write` on the job (a direct-push-only job only
+	// has `contents: write`, and the missing scope fails silently), and the PR
+	// title must stay a valid conventional commit <=100 chars so the
+	// "Validate Commit Messages" required check passes.
+	//
+	// The branch/commit/PR/auto-merge flow was extracted into
+	// tools/gh-open-refresh-baseline-pr.sh so it is a real, reviewable
+	// implementation artifact; the workflow now invokes it. Because the step's
+	// behaviour (git + gh side effects against a real checkout) cannot be
+	// exercised in a unit test, this spec pins the invariant with a static check
+	// of the workflow and the helper it calls.
+
+	function run() {
+
+		describe("refresh-visual-baselines.yml pushes through a PR, not a direct push (issue ##3283)", () => {
+
+			// expandPath("/wheels") resolves to vendor/wheels via the configured
+			// Lucee mapping; the repo root is two levels above.
+			var repoRoot = expandPath("/wheels/../..");
+			var workflow = repoRoot & "/.github/workflows/refresh-visual-baselines.yml";
+			var helper = repoRoot & "/tools/gh-open-refresh-baseline-pr.sh";
+
+			it("no longer pushes the refreshed baseline commit directly to the dispatched branch", () => {
+				expect(fileExists(workflow)).toBeTrue("Missing file: " & workflow);
+				var wfSrc = fileRead(workflow);
+
+				// The classic direct push the develop ruleset rejects:
+				//   git push origin "HEAD:$BRANCH"
+				// Any `git push ... HEAD:<target>` reproduces the GH013 rejection.
+				var directPush = reFindNoCase("git[[:space:]]+push[^\n]*HEAD:", wfSrc);
+				expect(directPush == 0).toBeTrue(
+					"issue ##3283: refresh-visual-baselines.yml must NOT push the refreshed "
+					& "baseline commit straight to the dispatched branch (`git push origin "
+					& """HEAD:$BRANCH""`) — the develop ruleset rejects it with GH013. Route the "
+					& "commit through a PR + auto-merge instead."
+				);
+			});
+
+			it("grants the job pull-requests: write so gh pr create/merge can operate", () => {
+				var wfSrc = fileRead(workflow);
+				expect(reFindNoCase("pull-requests:[[:space:]]*write", wfSrc) > 0).toBeTrue(
+					"issue ##3283: opening and auto-merging the refresh PR needs "
+					& "`pull-requests: write` in the job `permissions:` block. Without it the "
+					& "`gh pr create` / `gh pr merge` calls fail silently on the default "
+					& "`contents: write`-only token."
+				);
+			});
+
+			it("opens a PR and auto-merges it (matching refresh-packages-baseline.yml)", () => {
+				var wfSrc = fileRead(workflow);
+
+				// The flow may live inline in the workflow or in a helper the workflow
+				// invokes; assert on the combined text so the spec is not brittle
+				// about where the logic is hosted.
+				var combined = wfSrc;
+				if (fileExists(helper)) {
+					combined = combined & chr(10) & fileRead(helper);
+				}
+
+				expect(reFindNoCase("gh[[:space:]]+pr[[:space:]]+create", combined) > 0).toBeTrue(
+					"issue ##3283: the refreshed baseline(s) must be delivered via `gh pr create` "
+					& "against the target branch, not a direct push."
+				);
+				expect(reFindNoCase("gh[[:space:]]+pr[[:space:]]+merge[^\n]*--auto", combined) > 0).toBeTrue(
+					"issue ##3283: the refresh PR must enable auto-merge (`gh pr merge --auto`) so "
+					& "it lands without a human round-trip once the required checks pass."
+				);
+			});
+
+			it("delegates to the tools/ helper that implements the PR + auto-merge flow", () => {
+				expect(fileExists(helper)).toBeTrue(
+					"Missing helper: " & helper & " — the branch/commit/PR/auto-merge flow should "
+					& "live in a reviewable, reusable script the workflow calls."
+				);
+				var helperSrc = fileRead(helper);
+
+				// The helper commits onto a throwaway branch and pushes THAT branch
+				// (never HEAD:<target>), then opens the PR.
+				expect(reFindNoCase("git[[:space:]]+push[^\n]*HEAD:", helperSrc) == 0).toBeTrue(
+					"issue ##3283: the helper must push its own throwaway branch, never "
+					& "`git push ... HEAD:<target>` back to the protected branch."
+				);
+				expect(reFindNoCase("gh[[:space:]]+pr[[:space:]]+create", helperSrc) > 0).toBeTrue(
+					"The helper should open the refresh PR with `gh pr create`."
+				);
+
+				// The workflow must actually call the helper.
+				var wfSrc = fileRead(workflow);
+				expect(reFindNoCase("gh-open-refresh-baseline-pr\.sh", wfSrc) > 0).toBeTrue(
+					"issue ##3283: refresh-visual-baselines.yml must invoke "
+					& "tools/gh-open-refresh-baseline-pr.sh to open the refresh PR."
+				);
+			});
+
+		});
+
+	}
+
+}
-- 
2.54.0

A human review is required before merge. This is a bot limitation, not a code problem — the change itself is complete and green; it just needs a workflows-scoped push.