Skip to content

[Task][Infra] Add dependency-aware CI impact routing and release-oriented Pages deploys #216

Closed
#218
Closed
[Task][Infra] Add dependency-aware CI impact routing and release-oriented Pages deploys#216
#218

Description

@miso-develop
miso-develop
opened on Sep 19, 2026

Parent

Owner

  • ACTIVE_ROLE: implementation
  • DOMAIN: infra

State

READY_FOR_REVIEW

Blocking dependency:

Human has explicitly approved implementing #216 before the v1.0.0 tag/Release. #213 has been revised to use the new Pages cadence.

Once #214 is integrated and current main is revalidated, this Task becomes READY_FOR_IMPLEMENTATION.

Specification baseline

At Specification time:

  • main = bc5c3b90f57952f04a80c8ddfcb55b6d384c882e
  • current protected-main required check: only security:scan from GitHub Actions integration ID 15368
  • current Pages deploys on every main push + SemVer tag + manual dispatch
  • current Foundation always runs Web, Windows Chrome, and Firmware jobs
  • current Issue117 workflow can perform a diagnostics ESP-IDF build for some docs/process changes
  • no open PR existed at design time

After #213 completes, re-bootstrap and re-read current main / Rulesets / workflows before claim. The baseline above is not permission to ignore newer repository state.

Objective

Implement #215's selected deterministic change-impact routing and release-oriented Pages cadence without weakening required-check, release, security, provenance, or artifact-cleanup contracts.

Required architecture

1. Repository-owned impact classifier

Add one deterministic classifier, preferably:

  • scripts/ci_change_impact.py

with focused tests, preferably:

  • tests/ci_change_impact_test.py

Required output categories:

  • web
  • firmware
  • pages
  • security_release_shared
  • snapshot_contract
  • snapshot_build
  • process_docs_only

The classifier must accept changed paths deterministically and be usable from GitHub Actions through GITHUB_OUTPUT or a thin shell wrapper.

Fail-safe rule

Unknown/unclassified path => Shared/all-heavy.

Diff failure / unavailable base / all-zero push base / insufficient history => Shared/all-heavy.

Do not silently skip heavy validation on classifier uncertainty.

2. Changed-path acquisition

For PR:

  • compute complete base-SHA..head-SHA changed paths.

For main push:

  • compute event before..after changed paths.

Renames/deletes count.

Use repository-owned Git/Python logic. Do not introduce an unreviewed third-party path-filter action.

3. Foundation routing

Keep .github/workflows/foundation.yml triggered on every PR and main push.

Add a lightweight always-run classification job.

Condition only heavy jobs:

  • Web Linux => Web or Shared
  • Windows Chrome QR/Argon2 => Web or Shared
  • Firmware => Firmware or Shared

Docs/process-only:

  • classification only;
  • no Web/Windows/Firmware heavy build.

The workflow/routing files themselves must classify Shared so this PR exercises all heavy jobs.

4. Required Security invariant

Keep .github/workflows/security.yml on every PR and main push.

Keep exact check/job context:
security:scan

Do not add path filtering or a job-level skip that can prevent creation of this context.

Retain the current full Security/release contract suite for #215 unless an independently approved follow-up changes it.

5. Local production-equivalent Web smoke

For Web/Shared impact, compensate for less-frequent public Pages deploys with a production-build smoke.

Required:

  • real production Vite build, not dev mode;
  • production base /m5authenticator/;
  • production CSP;
  • normal Firmware Flash surface enabled;
  • synthetic/non-secret same-origin firmware manifest/assets adequate for fetch/route validation;
  • local static/preview server;
  • Chrome validation of Provisioner/Firmware/Help route loading and same-origin firmware-manifest access;
  • preserve existing QR/Argon2 production-bundle coverage.

Do not require an ESP-IDF build solely for a Web-only change.

Do not permit synthetic firmware fixture files to become production Pages assets.

6. Pages cadence

Update .github/workflows/pages.yml so ordinary main pushes do not deploy.

Automatic deploy:

  • protected SemVer tag push v*.*.*.

Manual deploy:

  • explicit workflow_dispatch candidate path;
  • clearly marked as pre-release/candidate in input/summary;
  • record exact source SHA/build identity;
  • do not imply a manual candidate is an immutable GitHub Release.

Preserve production build/package/Web/deploy behavior on tag/manual deploy:

  • release-profile validation;
  • immutable ESP-IDF build identity;
  • isolated firmware build;
  • firmware image/package validation;
  • same-origin firmware assets;
  • production Web build;
  • one Pages staging artifact;
  • retention-days: 1;
  • exact artifact-ID deletion after deploy.

Do not add Pages/OIDC authority to release-authorized.yml.

7. Issue117 split

Refine .github/workflows/issue117-screen-snapshot.yml to separate:

Lightweight snapshot contracts
for:

  • snapshot procedure docs;
  • AGENTS.md;
  • Windows diagnostic scripts;
  • host diagnostics helper;
  • snapshot contract tests.

Diagnostics ESP-IDF build
only for:

  • relevant firmware/profile inputs;
  • relevant CMake/sdkconfig/device/time/session/vault-runtime inputs;
  • ESP-IDF image/build input;
  • workflow build-semantics changes;
  • other true diagnostics-firmware build dependencies.

A docs-only or AGENTS-only change must not build diagnostics firmware.

8. Durable CI documentation

Add/update a durable CI operations document, preferably docs/CI.md, covering:

  • category model;
  • fail-safe behavior;
  • required security:scan invariant;
  • Foundation routing;
  • Pages tag/manual cadence;
  • local production-equivalent smoke;
  • when actual hosted candidate Pages is warranted;
  • Authorized Release artifact exception.

Path-classification contract

Process/docs-only — no heavy product builds

At minimum:

  • README.md
  • README.ja.md
  • docs/assets/**
  • ordinary docs/**
  • .agent/**
  • .agents/**
  • agent/**
  • ordinary work-tracking/process metadata
  • AGENTS.md for product-build purposes

Security still runs.

Specialized lightweight doc/contract tests may run where those files are deliberately consumed.

Web

At minimum:

  • web/**
  • future explicit Web-only build/config inputs.

Runs Web + Windows + production-equivalent Web smoke.
Skips heavy firmware.

Firmware

At minimum:

  • firmware/**
  • firmware/runtime/native tests;
  • firmware build/package/image scripts and ESP-IDF pinning where not Shared.

Runs Firmware.
Skips unrelated Web/Windows.

Shared

At minimum:

  • Foundation/Security/Pages routing workflows;
  • shared release/profile/package/CI supply-chain inputs;
  • classifier itself and classifier tests;
  • cross-surface manifest/release metadata contracts;
  • ambiguous new tests/paths.

Runs Web + Windows + Firmware + Security, with production-equivalent Web smoke.

Regression matrix

Tests must mechanically pin at least:

Change Web Windows Firmware automatic Pages main deploy Security
README only skip skip skip no run
README + docs/assets skip skip skip no run
.agent/agent only skip skip skip no run
ordinary docs only skip skip skip no run
web/src only run run skip no run
firmware only skip skip run no run
release/package shared script run run run no run
CI workflow routing change run run run no run
unknown top-level path run run run no run

Also pin:

  • diff failure => all-heavy;
  • required Security workflow has no path filter/skip;
  • Pages has no main-push deploy trigger;
  • Pages retains tag + explicit manual candidate;
  • Pages artifact cleanup/retention unchanged;
  • release-authorized bounded artifact handoff unchanged;
  • snapshot docs/AGENTS => lightweight contract only;
  • snapshot firmware input => diagnostics build.

Authorized Release boundary

Do not alter #127/#199 release artifact handoffs or privilege separation.

Specifically preserve:

  • raw build artifact;
  • verified package artifact;
  • exact artifact IDs;
  • checksum verification;
  • attestation before publish;
  • one-day retention;
  • cleanup exact-ID deletion;
  • publisher permissions;
  • legacy Release tombstone/retirement.

Verification on exact PR head

  • Rulesets re-read and current required contexts recorded.
  • classifier unit matrix passes.
  • workflow contract tests pass.
  • security:scan exists and succeeds.
  • this Shared workflow-change PR runs Web + Windows + Firmware heavy validation.
  • local production-equivalent Web smoke succeeds.
  • Pages PR contract shows no main-push deployment.
  • release authorization/attestation/supply-chain tests remain green.
  • no tag/Release created.
  • no Product/Protocol/Storage/Vault behavior change.

Post-merge Integration evidence

After merge to main, Integration must record:

  • exact merged main SHA;
  • canonical Product/Firmware version is still 1.0.0;
  • successful security:scan;
  • expected Foundation routing for the shared workflow change;
  • no Pages build/deploy check run on the ordinary merge push;
  • no Pages staging artifact from that ordinary main push;
  • Authorized Release and tombstone contracts unchanged;
  • v1.0.0 tag remains absent.

Then hand back to #213 for the required pre-tag Pages Human Gate.

Required #213 manual candidate handoff

Before tag creation, Human/Integration must run the retained manual candidate Pages path once on the exact current main SHA.

The manual candidate workflow must fail closed unless:

  • it is invoked from refs/heads/main;
  • its workflow/source SHA equals freshly fetched current origin/main;
  • a required candidate_sha (or semantically equivalent explicit input) is exactly the same 40-character current-main SHA.

This prevents the privileged public Pages candidate path from being casually run from an arbitrary branch/ref.

The candidate run must:

  • deploy the production-equivalent firmware + Web output;
  • record exact source/build identity;
  • retain staging artifact one-day defense-in-depth;
  • delete the consumed Pages artifact by exact artifact ID;
  • present non-exact build identity before the tag;
  • produce durable run/deployment evidence for [Release] Prepare M5Authenticator v1.0.0 #213.

Because it overwrites public Pages, this manual candidate run requires explicit Human approval.

Do not close #215 until #216 post-merge routing evidence is durable. The release-specific manual candidate Human Gate remains tracked by #213.

Collision / sequencing

Required release sequence:

  1. [Task][Infra] Set canonical Product/Firmware version to 1.0.0 #214 implementation/review/integration;
  2. [Task][Infra] Add dependency-aware CI impact routing and release-oriented Pages deploys #216 implementation/review/integration;
  3. [Release] Prepare M5Authenticator v1.0.0 #213 exact-main manual candidate Pages Human Gate;
  4. [Release] Prepare M5Authenticator v1.0.0 #213 protected v1.0.0 tag + Authorized Release/tag-triggered Pages.

#216 therefore waits only for #214 integration, not #213 completion.

After #214 dependency clearance, perform a fresh collision/state check for:

  • exact current main;
  • [Task][Infra] Set canonical Product/Firmware version to 1.0.0 #214 merged state and canonical version 1.0.0;
  • absence of v1.0.0 tag/Release;
  • current Rulesets/required contexts;
    and then check ownership for:
  • .github/workflows/foundation.yml
  • .github/workflows/pages.yml
  • .github/workflows/security.yml
  • .github/workflows/issue117-screen-snapshot.yml
  • scripts/**
  • tests/**
  • CI docs.

References

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions