95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# Release policy
|
|
|
|
OpenWrt RMM versions the cloud application and router bundle independently with Semantic
|
|
Versioning.
|
|
|
|
## Server releases
|
|
|
|
Tags use `server-vMAJOR.MINOR.PATCH`, for example `server-v0.8.1`.
|
|
|
|
A server release contains the Go API, web interface, database migrations and the coupled
|
|
SSH reverse-tunnel service. The GitHub Actions server workflow tests the server and
|
|
publishes two images with the same version:
|
|
|
|
```text
|
|
ghcr.io/benya9669/openwrt-rmm-server:0.8.1
|
|
ghcr.io/benya9669/openwrt-rmm-server:latest
|
|
ghcr.io/benya9669/openwrt-rmm-tunnel:0.8.1
|
|
ghcr.io/benya9669/openwrt-rmm-tunnel:latest
|
|
```
|
|
|
|
The tunnel remains a separate container for isolation, but shares the server release line
|
|
because its SSH policy and port-forwarding behavior form part of the server-side protocol.
|
|
Introduce independent `tunnel-v*` releases only if the tunnel later gains a separate API
|
|
and lifecycle.
|
|
|
|
Increment `MAJOR` for incompatible API or migration requirements, `MINOR` for compatible
|
|
features, and `PATCH` for compatible fixes. Database backups remain mandatory before a
|
|
production upgrade even when the release is marked compatible.
|
|
|
|
## Agent releases
|
|
|
|
Tags use `agent-vMAJOR.MINOR.PATCH`, for example `agent-v0.6.8`.
|
|
|
|
An agent release contains the Go runtime, LuCI application and OpenWrt IPK/APK packages.
|
|
Before tagging, the tag version must match `agentVersion` in the Go source and
|
|
`PKG_VERSION` in the production Go package. CI rejects a mismatched release tag.
|
|
|
|
Tagged releases automatically build the current OpenWrt 24.10 and 25.12 package matrix.
|
|
OpenWrt 21.02, 22.03 and 23.05 are a manual legacy tier that extends an existing agent
|
|
release without blocking current packages. Run it after the tagged workflow completes:
|
|
|
|
```sh
|
|
gh workflow run build-legacy.yml -f agent_tag=agent-v0.6.8
|
|
```
|
|
|
|
The LuCI application is shipped as part of the router bundle. It can retain its own package
|
|
version for package-manager upgrades, but it does not require a separate GitHub release
|
|
line unless it later becomes an independent product.
|
|
|
|
## Protocol compatibility
|
|
|
|
Server and agent versions do not need to match. Compatibility is determined by the agent
|
|
API protocol, currently `v1`. Within the same protocol major version:
|
|
|
|
- a newer server should continue to accept supported older agents;
|
|
- a newer agent should tolerate unknown response fields and optional server features;
|
|
- required capabilities must be negotiated or reported explicitly rather than inferred
|
|
only from the package version.
|
|
|
|
An intentional incompatible protocol change requires a new API version and a documented
|
|
transition period; it should not silently reuse `v1`.
|
|
|
|
## Release commands
|
|
|
|
Before creating a tag, add an English `## <tag>` section to `CHANGELOG.md`. The release
|
|
workflow uses that section verbatim and fails instead of publishing empty autogenerated
|
|
notes.
|
|
|
|
```sh
|
|
git tag -s server-v0.8.1 -m "OpenWrt RMM Server 0.8.1"
|
|
git push origin server-v0.8.1
|
|
|
|
git tag -s agent-v0.6.8 -m "OpenWrt RMM Agent 0.6.8"
|
|
git push origin agent-v0.6.8
|
|
```
|
|
|
|
Pushing a server tag publishes the container image and creates a GitHub Release. Pushing
|
|
an agent tag builds the full OpenWrt matrix and creates a GitHub Release containing only
|
|
installable `.ipk` and `.apk` packages. Repository indexes, public signing keys and
|
|
provenance metadata stay in the signed GitHub Pages package feed and GitHub attestations.
|
|
Repository setup, key generation and router configuration are documented in
|
|
[`docs/package-repository.md`](docs/package-repository.md). `workflow_dispatch` can test
|
|
either workflow without creating a release.
|
|
|
|
Server and tunnel images are published with SBOM/provenance attestations bound to the
|
|
release workflow identity. Agent packages receive GitHub build-provenance attestations.
|
|
IPK and APK feeds additionally use their native OpenWrt repository signatures so `opkg`
|
|
and `apk` can enforce trust on the router.
|
|
|
|
The package repository also contains `update-manifest.json`, a detached ECDSA signature,
|
|
and its Sigstore bundle. The server verifies the detached signature before adopting a
|
|
version from the manifest, then exposes the trusted stable version through authenticated
|
|
release metadata. The dashboard compares versions with Semantic Versioning and never
|
|
recommends downgrading an agent newer than the stable channel.
|