SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfw-release-gate

fw-release-gate

Design & creation

View repository

Updated 10-15 21:48

About this skill

Firmware Release Gate (fw-release-gate)

Release gate = scriptable factual checks, not "it feels ready." Artifacts, naming, checksums, licenses, keys, rollback plan, HIL badge — go item by item; if any one fails, do not release. A gate that fails to stop a bad artifact is as good as no gate at all.

Determine Task Type

  1. Pre-release gate (main path): image is to be released to a channel/user → Workflow A (go through the checklist item by item).
  2. Naming and version decisions: how to name, how to bump the version number, how to stamp the channel field → Workflow B + naming-and-versioning。
  3. Signing and key governance: what scheme to sign with, where keys live, how to separate multiple channels → Workflow C + "Signing and key governance" on this page.
  4. Integrity/reproducibility troubleshooting: sha256 does not match, two builds are inconsistent → Workflow D.

Prerequisites / Preflight

# 产物与校验和工具就位（占位路径按项目替换）
ls -l bin/targets/*/ 2>/dev/null || ls -l out/ 2>/dev/null || echo "no artifact dir found"
command -v sha256sum || command -v shasum || echo "no sha256 tool"
  1. Artifact directory, target channel, and target device list are in hand;
  2. the HIL badge record for this version is in hand — if not → route to fw-hil-testing; this gate does not clear a "stable release";
  3. the key ownership for the signing scheme is clear; if not clear → first go through "Signing and key governance" below, then talk about release.

Offline Baseline

  • Walkthrough date 2026-09-02, not auto-updated.
  • OpenWrt baseline 25.12.5; the five-segment naming pattern is distilled from TinyNAS closed-loop practice (its spec baseline 2026-08-31).
  • OpenWrt-side reproducible build mechanism (SOURCE_DATE_EPOCH) details are in openwrt-image-build reproducible-build reference; this Skill only consumes its conclusions (rebuild with a fixed epoch, hashes should match, drift troubleshooting order).

Contracts (release artifact contracts)

  1. sha256 must be attached: every release artifact must have a paired .sha256(content = <hash> <filename>), and the gate mustrecomputeand pass — "it was computed at build time" does not count.
  2. Reproducible build declaration: the release record states the SOURCE_DATE_EPOCH value and source; when it cannot be reproduced, mark it truthfully; claiming deterministic is prohibited.
  3. LICENSE/GPL compliance: distributing binaries must satisfy the license obligations of the included components — OpenWrt itself is GPLv2 (attach the source acquisition path and build scripts); list AGPL/MIT/Apache components bundled with the package one by one. Pattern reminder: the obligation form of network-service-style AGPL components (Alist-type) differs from GPLv2; add a separate check line for them. Attach the license list to the release notes.
  4. HIL badge prerequisite: for a version entering a channel and claiming "usable/stable," the badge must be ≥ HIL Verified(semantics → fw-hil-testing）；Build Verification Only / Boot Verified (QEMU) ); it can only enter internal/test channels and must be explicitly marked.
  5. Anti-hallucination red line: version numbers, dates, and channel fields must come from build records (epoch/CI output); manually filling in an "approximate date" is prohibited.

Signing and key governance (pattern)

Commercial authorization and integrity favor asymmetric signing, with three governance invariants:

  1. Firmware/devices embed only the public key (or public key digest)— making verification capability public is fine;
  2. the private key exists only on the build/signing machine(offline machine or controlled signing service), never into git, CI plaintext variables, logs, or chat records;
  3. Channel subkey distribution: the root key only issues channel subkeys/sub-artifacts; a leak in one channel only revokes that channel's subkey and does not touch the root.

Applicable boundaries of symmetric short activation codes(one-sentence pattern): a symmetric scheme = the firmware must contain code-minting/key-verification capability, and extracting the firmware is equivalent to obtaining the code-minting capability; an asymmetric scheme = extracting the firmware yields only the signature-verification public key,cannot mint codes. Therefore symmetric short codes are only suitable for low-value scenarios where clone risk is acceptable; for commercial licensing, always prefer asymmetric. ESP32-side eFuse / Secure Boot v2 / Flash encryption mechanisms → esp32-secureboot(its key-governance follows the same set of governance principles as this section).

Naming and versioning strategy (five-segment template)

Pattern reference (distilled from TinyNAS practice) —five-segment image name, the filename is the metadata:

openwrt_<brand>-<tier>-<device>_v<SemVer>-<channel>_<date>.img.gz
  • SemVer: MAJOR = breaking compatibility (partition layout/config not migrated/no downgrade); MINOR = new features; PATCH = fixes;
  • channel: stable / beta / dev go into the filename, eliminating "same name, different quality";
  • date: build date, taken from the build record (SOURCE_DATE_EPOCH / CI output), not manually filled in;
  • Naming lint criteria, trimming rules, and counterexamples → naming-and-versioning。

Capability Boundaries + Hand-off

User Intent Skill
Insufficient HIL evidence / badge not up to standard fw-hil-testing(the badge prerequisite of this gate)
Two builds inconsistent / reproducibility mechanism openwrt-image-build(SOURCE_DATE_EPOCH mechanism side)
ESP32 secure boot / eFuse / encryption esp32-secureboot(mechanism layer)
OTA upgrade package delivery mechanism esp32-ota(upgrade artifact verification returns to this Skill)
Task classification entry point fw-core
Building the CI/CD platform itself Out of bounds: give general advice, do not replace this gate checklist

Workflow A — Pre-release checklist (main path)

Execute item by item according to the script skeleton in release-checklist (style benchmarked against production gate scripts: pass/fail counts, exit 0 when all green):

  1. Artifact exists + .sha256 paired and the gate recomputation is consistent;
  2. Naming lint: each of the five segments is valid, and the device/version/channel/date in the filename match the build record;
  3. Zero external link scan: bundled frontend/resources have no public CDN external links;
  4. Key scan: the artifact tree and overlay layer have no private keys/salt values/credentials (test keys intentionally committed must be explicitly exempted and publicly marked);
  5. Rollback plan exists: the previous usable version image + downgrade steps are documented;
  6. HIL badge up to standard: the release notes state the badge level, channel version ≥ HIL Verified；
  7. Release notes: version highlights + known issues(even if none, write "Known issues: none");
  8. LICENSE list attached.

If any item fails → after fixing,rerun the full checklist(not just patching the failed item).

Workflow B — Naming and versioning decision

  1. Determine MAJOR/MINOR/PATCH according to the nature of the change (criteria → naming-and-versioning §2);
  2. Determine the channel label; confirm that channel/version/date are synchronously written into the watermark field inside the image (values come from the build record);
  3. Run the naming lint (reference §4); after renaming/rebuilding, rerun the release checklist.

Workflow C — Signing Scheme Decision

  1. Determine the scenario: firmware integrity/anti-tampering → asymmetric signing; commercial licensing/activation → asymmetric licenses (the device holds only the public key);
  2. Key placement: place according to the "three invariants" before starting work — if someone proposes putting the private key into CI → refusal (see Pitfalls 1);
  3. Multi-channel: root key + channel subkeys; release only after the subkey revocation process is documented;
  4. If someone proposes a symmetric short code → evaluate according to the "applicable boundaries"; if accepted, leave a written risk statement; it is not accepted for commercial licensing scenarios.

Workflow D — Integrity/Reproducibility Troubleshooting

  1. sha256 mismatch: first rule out transport truncation (redownload, compare sizes), then rule out "same name, different build" (naming lint item 2);
  2. Two builds are inconsistent: pin SOURCE_DATE_EPOCH rebuild twice and compare hashes; if still inconsistent, troubleshoot in the order "environment differences → overlay timestamps/random IDs → ipk repository drift" (mechanism details → openwrt-image-build）；
  3. Write the conclusion into the release record — if it cannot be reproduced, state that truthfully; do not change your story to "it should be the same."

Validation Gates

  • The checklist script is all green (exit 0), and the output is retained and archived with the release;
  • Spot-check one channel link: from the download point to the device, checksum + signature verification pass end to end;
  • Negative verification: deliberately break one item (rename/tamper with one byte of the image/delete the .sha256), and the gate must block it.

Pitfalls

  1. Do notput signing private keys into CI environment variables/repositories — plaintext variables will enter logs, be inherited by subprocesses, and land in image layers; "the repository is private" does not change the exposure surface. The correct approach: separate build and signing; CI keeps only the public key digest for verification checks.
  2. Do notshare one key with no derivation relationship across multiple channels — a single point of compromise brings down the entire line and you cannot revoke just one channel; use a root key + channel subkeys.
  3. Do notrelease artifacts without .sha256 , and do not trust only "it was computed at build time" — the gate must recompute.
  4. Do notlet the version/channel/date in the filename be inconsistent with the build record — naming is metadata; a wrong name is more dangerous than a missing name.
  5. Do notrelease a "stable version" to a channel when the HIL badge does not meet the standard — B0/B1 may only go to internal/test channels and must be explicitly labeled.
  6. Do notomit license obligations — the distribution obligations for GPL/AGPL components do not disappear just because it is "only flashing firmware."
  7. Do nothide known issues in the release notes — if known issues are not reported, the after-sales cost is greater.
  8. Do notuse symmetric short codes for commercial licensing — extracting the firmware lets you forge codes; if you want to use it, first confirm in writing that the cloning risk is acceptable.

Official Sources

Privacy

The gate script only performs local checks and does not upload artifacts or checksums; key material does not enter logs or reports; when key/credential scans hit, report only the file path, not the content; treat channel and device information in release notes as user data and redact it before external transmission.