Frontend Promotion Guard v0.4.0

[0.4.0] - 2026-10-02

Added

• fpg monitor repeatedly verifies a live target on an interval and posts webhook alerts on down/recovered transitions, with a persisted state file, interval jitter, and graceful shutdown.
• Semantic visual gating: ARIA snapshot diff per route and viewport (visual.ariaSnapshot, ariaSnapshotMode), visual.maskSelectors for noisy regions, visual.freezeTime clock freezing, and per-route waitUntil/fullPage overrides.
• fpg baseline pull/push sync baselines through configured visual.remoteSync commands, and fpg verify --github writes a Job Summary, result/diffRatio outputs, and ::error annotations.
• Action inputs baseline-pull, baseline-push, and github, plus Action outputs; rollout-controller integration shapes documented in docs/integrations.md.
• npm package metadata: repository, bugs, homepage, keywords, and publishConfig with public access and provenance.
• CHANGELOG.md, docs/releasing.md, docs/monitor.md, docs/visual-gate.md, bilingual launch post, README badges, and a terminal demo animation.

Fixed

• Corrected the GitHub owner name in Action usage examples, workflow files, and maintainer references. The underscore form is not a valid GitHub username, so uses: references resolved to a 404 repository. All references now use Reality-JH.

Frontend Promotion Guard v0.3.0

Release boundaries are now explicit: targeted checks, module verification, and production promotion are separate levels. GitHub Action promotion additionally requires confirm-promotion: true, preventing ordinary feature and pull-request workflows from mutating container state. All v0.2.0 validation, immutable evidence, rollback verification, release locking, redaction, and Docker integration safeguards remain in place.

中文更新说明：https://github.com/Reality-JH/frontend-promotion-guard/blob/v0.3.0/docs/v0.3.0-release.zh-CN.md

Frontend Promotion Guard v0.2.0

Frontend Promotion Guard v0.2.0

A green build, an HTTP 200 response, and a healthy container do not guarantee that a frontend is ready for production.

A missing stylesheet or a broken build transform can leave the page accessible while its layout is already unusable. Frontend Promotion Guard adds a release gate for this gap.

Version 0.2.0 focuses on making promotion evidence clearer, configuration failures easier to diagnose, and Docker promotion and rollback behavior safer to verify.

What changed

Safer Docker promotion and rollback

• Records the candidate, previous production, and final production image IDs.
• Adds docker.requireImmutableImage for deployments that require immutable image references.
• Prevents concurrent local promote and rollback operations with a repository lock.
• Adds GitHub Actions concurrency protection.
• Fails closed when rollback completes but the restored production service still fails verification.

Stronger configuration validation

• Validates the complete YAML configuration at runtime.
• Reports configuration errors with precise field paths.
• Rejects invalid routes, viewports, thresholds, Docker settings, and browser options before verification starts.

Better release evidence

• Adds operating system, Node.js version, browser information, stage timing, image identity, Git commit, and final production state to reports.
• Applies the same secret redaction rules to console output, JSON evidence, and HTML reports.
• Fixes redaction of Authorization: Bearer ... values.
• Generates a SHA-256 manifest when visual baselines are explicitly updated.

More reliable CI integration

• GitHub Action commands now use an allowlist.
• Action inputs are passed through environment variables instead of shell interpolation.
• Baseline updates are blocked inside the GitHub Action. Baselines must be reviewed and updated explicitly.
• License scanning now uses the Node.js standard library and no longer needs a separate scanning dependency.

Expanded CSS regression coverage

CSS audit tests now cover:

• :where() and :is() selectors
• selectors inside media queries
• misleading selectors inside comments
• similar class names that must not satisfy an exact required selector

Verification evidence

The v0.2.0 release was verified with:

• 14 of 14 local automated tests passing
• TypeScript type checking passing
• npm dependency audit reporting zero known vulnerabilities
• Node.js 20 and 22
• Ubuntu, Windows, and macOS browser jobs
• 6 of 6 browser matrix jobs passing
• Docker integration job passing
• 7 of 7 GitHub Actions jobs passing

The Docker integration workflow exercises four real scenarios:

1. A valid candidate passes verification and is promoted.
2. A failed candidate is rejected without changing production.
3. A production verification failure restores the previous image.
4. A failed post-rollback verification causes the command to fail closed.

Upgrade

Use the v0.2.0 GitHub Action:

- uses: Reality-JH/frontend-promotion-guard@v0.2.0
  with:
    config: fpg.yml
    command: verify

If you use the CLI directly, update the package version and review the new configuration validation rules before running promotion.

Scope

Frontend Promotion Guard checks built CSS, computed browser styles, visual differences, candidate containers, production verification, and rollback evidence.

It does not replace functional testing, security testing, accessibility testing, or human review.

Docker support remains optional. Visual checks can run without Docker.

Visual baselines are never replaced automatically after a failed test. Updating them remains an explicit, reviewable action.

Repository: https://github.com/Reality-JH/frontend-promotion-guard

Maintainer: Reality_JH
Security contact: 849034843@qq.com

中文说明

构建成功、HTTP 返回 200、容器状态健康，并不代表前端真的可以上线。

样式文件丢失或构建转换异常时，页面仍然可以访问，但布局可能已经无法使用。Frontend Promotion Guard 要解决的就是这段常被普通健康检查漏掉的发布风险。

v0.2.0 重点补强了配置校验、发布证据，以及 Docker 镜像晋升和自动回退的验证能力。

本次更新

更安全的 Docker 晋升与回退

• 记录候选镜像、晋升前正式镜像和最终正式镜像的 ID。
• 新增 docker.requireImmutableImage，可要求发布流程使用不可变镜像引用。
• 使用仓库本地互斥锁，避免多个 promote 或 rollback 操作同时执行。
• 为 GitHub Actions 增加并发保护。
• 如果镜像已经回退，但恢复后的正式环境仍未通过验收，命令会保持失败，不会把不确定状态当作成功。

更完整的配置校验

• 在运行时校验完整的 YAML 配置。
• 错误信息会指向具体配置字段。
• 在开始验收前拦截无效路由、视口、阈值、Docker 设置和浏览器选项。

更清晰的发布证据

• 报告新增操作系统、Node.js 版本、浏览器信息、各阶段耗时、镜像标识、Git commit 和最终生产状态。
• 控制台、JSON 证据和 HTML 报告使用一致的敏感信息脱敏规则。
• 修复 Authorization: Bearer ... 的脱敏顺序问题。
• 显式更新视觉基线时生成 SHA-256 清单。

更可靠的 CI 接入

• GitHub Action 只允许执行预定义命令。
• Action 输入通过环境变量传递，不再插入 Shell 命令字符串。
• GitHub Action 中禁止更新视觉基线。基线必须经过人工确认后显式更新。
• 许可证扫描改用 Node.js 标准库，不再依赖额外的扫描包。

更全面的 CSS 回归测试

CSS 产物审计现在覆盖：

• :where() 和 :is() 选择器
• 媒体查询中的选择器
• CSS 注释中的误导内容
• 不应冒充精确选择器的相似类名

验证结果

v0.2.0 已完成以下验证：

• 本地自动化测试 14 项全部通过
• TypeScript 类型检查通过
• npm 完整依赖审计为 0 个已知漏洞
• 覆盖 Node.js 20 和 22
• 覆盖 Ubuntu、Windows 和 macOS
• 浏览器矩阵任务 6 项全部通过
• Docker 集成任务通过
• GitHub Actions 总计 7 项任务全部通过

Docker 集成流程实际验证了四种情况：

1. 正常候选版本通过验收并完成晋升。
2. 候选版本验收失败，正式镜像保持不变。
3. 正式环境复验失败，恢复上一镜像。
4. 回退后仍未通过验收，命令以失败状态结束。

升级方式

GitHub Action 可更新为：

- uses: Reality-JH/frontend-promotion-guard@v0.2.0
  with:
    config: fpg.yml
    command: verify

如果直接使用 CLI，请更新软件包版本，并在执行镜像晋升前检查新的配置校验规则。

能力边界

Frontend Promotion Guard 负责检查构建后的 CSS、浏览器真实计算样式、截图差异、候选容器、正式环境复验和回退证据。

它不能替代功能测试、安全测试、可访问性测试和人工验收。

Docker 能力是可选模块。只执行视觉检查时不需要安装 Docker。

测试失败不会自动覆盖视觉基线。基线更新必须经过人工确认，并通过显式命令执行。

项目地址：https://github.com/Reality-JH/frontend-promotion-guard

维护者：Reality_JH
安全问题联系邮箱：849034843@qq.com

Frontend Promotion Guard v0.1.1 released

An open-source release gate for frontend failures that health checks miss

Frontend Promotion Guard (FPG) v0.1.1 is now available as an open-source Node.js CLI and reusable GitHub Action.

Many deployment pipelines stop at a successful build, an HTTP 200 response, and a healthy container. Those checks do not prove that a browser received usable CSS or that a page still matches the version the team approved. FPG adds that missing check to the release path.

FPG checks built CSS, real browser-computed styles, screenshots across configured routes and viewport sizes, candidate Docker containers, and production re-verification. It generates a static HTML report with screenshots, diffs, commit information, test results, and rollback state.

FPG is intentionally narrow. It does not replace functional testing, security testing, accessibility review, or human acceptance. It is a release guard for one recurring failure mode: a technically healthy deployment that is visibly broken in the browser.

Repository: https://github.com/Reality-JH/frontend-promotion-guard

Maintainer: Reality_JH
Security contact: 849034843@qq.com

一道专门拦截“健康检查通过但前端已经坏了”的开源发布门禁

开源项目 Frontend Promotion Guard（FPG）v0.1.1 现已发布。它提供 Node.js CLI 和可复用的 GitHub Action。

很多发布流程在构建成功、HTTP 返回 200、容器健康后就结束了。这些信号无法证明浏览器拿到了可用的 CSS，也无法证明页面仍然符合团队批准过的版本。FPG 把这一步补进发布流程。

FPG 会检查构建后的 CSS、真实浏览器计算样式、多路由多视口截图、候选 Docker 容器，以及正式环境复验结果，并生成包含截图、差异图、commit、测试结果和回退状态的静态 HTML 报告。

FPG 的边界很明确。它不能替代功能测试、安全测试、可访问性检查或人工验收。它只负责拦截一种反复出现的事故：部署在技术指标上健康，但用户在浏览器里看到的页面已经损坏。

仓库：https://github.com/Reality-JH/frontend-promotion-guard

维护者：Reality_JH
安全联系：849034843@qq.com

Frontend Promotion Guard v0.1.0

Frontend Promotion Guard v0.1.0

Frontend Promotion Guard is a reusable release gate for frontend incidents that ordinary health checks miss. It audits emitted CSS, checks real browser-computed styles, compares screenshots across configured routes and viewports, accepts an isolated Docker candidate, and restores the previous image after a failed production recheck.

Highlights

• Node.js CLI: audit, capture, compare, verify, promote, rollback, report, and explicit baseline update.
• Chrome and Edge discovery with configurable browser paths.
• Static HTML evidence reports with baseline, current, and diff images.
• Cross-platform PowerShell and Linux/GitHub Actions examples.
• Vite/React validation project with CSS failure, promotion, and rollback exercises.
• English default documentation with Simplified Chinese translation.

This release does not replace functional testing, security testing, accessibility review, or human acceptance.

Documentation

• English README: https://github.com/Reality-JH/frontend-promotion-guard/blob/main/README.md
• 中文 README: https://github.com/Reality-JH/frontend-promotion-guard/blob/main/README.zh-CN.md
• Launch article: https://github.com/Reality-JH/frontend-promotion-guard/blob/main/docs/launch-post.md

Maintainer: Reality_JH
Security contact: 849034843@qq.com