GitHub quality checks#

Every PR and branch push executes the existing pnpm verify gate on Ubuntu. Static enforcement includes formatting, strict lint/types, CSS limits, unused-code checks, architecture checks and their regressions, builds, and built-consumer checks. Module and Chromium journeys also run, preserving the complete production gate for prototypes. Native Windows smoke is available through explicit manual dispatch, as accepted by the user on 2026-10-12 in CI coverage revision. Manual dispatch without the Windows input uses the full Linux gate too.

The workflow reads the pinned Node version and package manager from the repository, uses frozen dependencies, and caches only the OS-specific pnpm store keyed by the toolchain/manifests/lockfile. Linux CI installs full Chromium plus its headless shell: maintained suites retain the shell, while the native extension-owner suite uses Chromium's extension-capable channel. Both frozen dependency environments are installed, and the candidate lock participates in the OS-specific store cache key. FFmpeg remains available for failure videos. Linux installs OS dependencies; manual Windows smoke uses the runner's existing OS features. Local worktree setup retains full Chromium for headed browser use. Failure diagnostics are retained for seven days. Actions are pinned to reviewed commit IDs, permissions are read-only, and there are no path filters, release steps, or privileged pull_request_target execution.

Cloudflare Pages dev builds#

Every branch push automatically builds and deploys a preview alongside the quality checks. The preview job has no verification dependencies: it installs frozen dependencies and runs the build, without waiting for lint, types or tests. The preview uses pnpm build:preview, building only the examples' workspace dependencies and static output. It excludes the Vite+ comparison, extension builds and separate PR-preview application; dependency downloads use the same pinned pnpm store cache as verification. Package declarations are still generated by the selected builds. A failed build blocks that preview; failing quality checks do not. Preview branches use the preview- prefix, including preview-main, so unchecked builds never select the production branch. These previews are for visual/manual checks, not evidence that verification passed. Pull-request events only run verification and never publish.

After the complete Linux verification and aggregate gate succeed, every push to main also deploys the verified dist/examples/ artifact to production. The deployment job downloads that artifact from the same workflow run; it does not rebuild a different revision. Pull requests run checks without publishing or receiving Cloudflare credentials. Deployment failure is reported separately from the quality gate.

One-time setup, available from a phone:

1. Create a Cloudflare API token with Account → Cloudflare Pages → Edit, scoped to the account containing that project.
2. In GitHub repository Settings → Secrets and variables → Actions, add repository secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Do not put tokens in chat, source files, or workflow inputs. A local Wrangler login is not used by CI.
3. Push a branch containing this workflow for an automatic preview. After this workflow reaches main, verified main pushes also update production. For an optional manual preview, open Actions → Repository quality → Run workflow, select a branch and enable Build and deploy a branch preview alongside verification. Leave Windows smoke off. Manual runs always publish previews, including runs on main.

The first deployment creates the Direct Upload project snagbadger-dev with production branch main if it does not exist. Discovery and creation use structured Cloudflare responses. A duplicate-name creation conflict is accepted only after rereading the exact project and confirming production branch main; permission, transport and other creation failures remain failures. Existing projects are reused only after that same configuration check, and incompatible settings are rejected. For another project, set repository variable CLOUDFLARE_PAGES_PROJECT to its name; an existing project's production branch must already be main. The workflow does not change an existing project's branch settings or Git integration.

tooling/quality/pages-deployment.test.mts executes the workflow's actual shell with controlled HTTP and Wrangler commands. It covers creation/reuse, a concurrent creator, configuration mismatch, malformed responses and failures without using Cloudflare credentials or making network requests. Workflow contract tests protect the verified-artifact producer, same-run consumer and publication directory.

Wrangler prints both the deployment URL and any branch alias in the deployment job log. Open /playground/ for the React playground or /documentation/ for the documentation. These are static builds; local server-only fixture endpoints are not deployed. They stay available without the PC running. Missing credentials or project-creation failure fail deployment rather than being reported as a publication.

For an authorized local deployment with a valid Wrangler login, run pnpm build and wrangler pages deploy dist/examples --project-name snagbadger-dev --branch YOUR_BRANCH. Use the Wrangler version pinned in the workflow for repeatability.

Reference: Cloudflare Pages continuous integration.

Verification execution#

The full verification recipe runs formatting and builds before bounded lanes: lint/CSS/rule/architecture tests, types/quality/workflow/unused-code/architecture checks, and the main tests/browser/consumer checks. Lint and type checking overlap; the browser lane starts immediately after the build. Pages cases run in parallel within their owned browser run. Machines with at most two available CPUs use two lanes to limit contention; larger machines use three. CI browser suites use two workers rather than the default single worker on small runners. Browser and generated-artifact work stays serial within its lane. All lanes drain before verification returns, even on failure, preserving worktree ownership. Logs include duration and exit code for each stage. Every existing full-gate check remains required in Linux CI and before handoff. Local pre-commit hooks use parallel staged-file checks and tagged critical tests with a shared deadline; see worktree setup.

Dependency installs already take only a few seconds with the pnpm store cache. Browser archives are downloaded directly: after avoiding full Chromium and Windows OS-feature setup, cache restore/upload overhead must show a measured advantage before adding browser caching. Generated builds and verification results are recreated for the current source rather than restored as passing evidence.

SnagBadger quality gate is the single aggregate check to require on main. Its job runs even after failed/skipped dependencies and requires successful Linux verification. The optional Windows job is skipped on ordinary PR/push runs without allocating a Windows runner. Explicit Windows smoke dispatch selects the native smoke instead and skips Linux to avoid repeating an already available PR gate. The aggregate requires the selected job to succeed and the other job to be skipped. Windows-only dispatch uses the separate Windows compatibility gate status, so it cannot replace the mandatory Linux SnagBadger quality gate status on a PR. A cancelled, failed, or skipped required job cannot produce a passing aggregate. The actual aggregate shell script's outcomes are regression-tested. Checks and logs are available on each PR's Checks tab.

Portable checks and native Windows smoke#

The architecture gate rejects Windows-reserved device names and case-folded file or directory collisions on any host. It also confines runtime subprocess imports to registered adapters and test files, including dynamic imports and require. Windows/POSIX/UNC boundary fixtures, CRLF catalog fixtures, and process-interruption contract tests run in the complete gate. The aliased-root regression models the filesystem's canonical-path mapping while using real Vite and HTTP serving. These checks establish portability contracts; they do not certify native Windows binaries or filesystem/process behavior.

Run the native smoke when investigating Windows behavior or validating platform, Node/pnpm, or native dependency changes:

gh workflow run quality.yaml --ref <branch> -f windows_smoke=true

This dispatch selects Windows compatibility smoke without rerunning Linux. The smoke performs a frozen install, builds the workspace with native bindings, checks hooks/processes/filesystem/worktrees, and exercises maintained fixed-save and plain-HTML browser cases. Its guarded local entry is pnpm check:compatibility; the supported recipe retains source-bound evidence in smoke.json. Ordinary local handoffs still use full pnpm verify; commit hooks use pnpm check:commit.

Merge policy on the current plan#

Accepted user decision (2026-10-11): keep the repository private on its current plan. GitHub returned HTTP 403 for branch protection and rulesets. Use hosted CI and the merge skill as the merge gate within this constraint; billing and visibility stay unchanged. GitHub itself still permits a collaborator to bypass this policy through manual merges or direct pushes.

Before an authorized agent merge:

1. Read the current PR head/base, all checks and review threads. Inspect the named SnagBadger quality gate explicitly; gh pr checks --required can return no checks on this plan and is insufficient. Use gh pr checks <PR> --json name,state,workflow,link to find the aggregate from Repository quality.
2. Require SUCCESS for that aggregate and Linux verification in the current PR workflow run. Follow its run link and verify the run's headSha matches the reviewed PR head, its event is pull_request, and the run attempt completed successfully. A missing, pending, failed, skipped, cancelled or foreign result blocks the merge; local verification is additional evidence, not a substitute. Native Windows smoke is optional. If explicitly requested for this change, require its passing manual-dispatch run on the same head as additional evidence.
3. Verify current target-base ancestry and all prerequisites. Update branches missing this workflow or the current base, then rerun checks and review. Apply the bot/static, accepted-requirements and browser-evidence gates in AFK handoff and the installed merge-pr-mr-pull-request skill.
4. Immediately before merging, re-read the head, target base and checks. Merge only the verified revision with gh pr merge <PR> --match-head-commit <OID>. Changes invalidate the corresponding evidence; refresh it before proceeding. After merge, verify closure, reconcile roadmaps and report newly unblocked tickets under tracker policy.

This is agent-enforced policy, not server-enforced branch protection. Report that distinction in merge handoffs. The canonical merge skill is versioned with this repository. Install it on each machine with pnpm skills:install; use --replace to update an existing installation with a preserved backup. Other machines must install this skill or follow this repository procedure.

Optional server protection#

The prepared configuration is retained for a future explicitly authorized change to plan or visibility. It is not a pending requirement under the accepted current plan. If support becomes available, inspect existing settings and apply it only with authorization for that change:

gh api --method PUT repos/CosticaPuntaru/SnagBadger/branches/main/protection --input tooling/quality/main-protection.json
gh api repos/CosticaPuntaru/SnagBadger/branches/main/protection

The configuration requires SnagBadger quality gate from the GitHub Actions app and an up-to-date branch, applies to administrators, blocks force pushes/deletion, and requires resolved conversations. It does not add a new human-review quota. Inspect any existing protection first and preserve unrelated stricter settings when applying a later update. Branch protection gates checks; accepted requirements and human decisions still need the merge skill's review.

The CI implementation still needs repository-version synchronization from its prerequisite before its whole acceptance scope is complete. The current workflow runs every check already present in pnpm verify; it does not claim missing version automation exists. Agent merge gating tracks the accepted current-plan fallback and stays open until its implementation merges.

Official references: required status checks, setup-node, and dependency caching.