m2pack-secure/docs/release-workflow.md

Release workflow

This is the recommended end-to-end release flow for m2pack-secure.

The goal is to keep archive creation on Linux, keep signing keys off developer workstations when possible, and make the Windows client consume only runtime delivery material.

Inputs

• client asset tree
• master.key
• signing.key
• signing.pub
• target key_id

Output artifacts

• one or more .m2p archives
• generated M2PackKeys.h
• runtime key payload for the launcher
• release manifest and validation logs

Minimal release flow

1. Generate or select the active content key set.
2. Build the archive with the intended key_id.
3. Verify the archive with the signing public key and content key.
4. Diff the archive against the source tree to catch packing mistakes.
5. Export M2PackKeys.h for the client source tree.
6. Export the runtime key payload for the launcher.
7. Build the Windows client against the generated header.
8. Ship .m2p plus the client and launcher together.

Example

./build/m2pack build \
  --input /srv/build/client-root \
  --output out/root.m2p \
  --key keys/master.key \
  --sign-secret-key keys/signing.key \
  --key-id 3 \
  --json

./build/m2pack verify \
  --archive out/root.m2p \
  --public-key keys/signing.pub \
  --key keys/master.key \
  --json

./build/m2pack diff \
  --left /srv/build/client-root \
  --right out/root.m2p \
  --json

./build/m2pack export-client-config \
  --key keys/master.key \
  --public-key keys/signing.pub \
  --key-id 3 \
  --output /path/to/m2dev-client-src/src/PackLib/M2PackKeys.h \
  --json

./build/m2pack export-runtime-key \
  --key keys/master.key \
  --public-key keys/signing.pub \
  --key-id 3 \
  --format json \
  --output out/runtime-key.json \
  --json

CI recommendations

• Run archive builds on Linux only.
• Keep signing.key in CI secrets or on a dedicated release box.
• Treat master.key as release secret material, not as source code.
• Archive and retain verify and diff outputs for each release.
• Fail the pipeline if verify fails or diff reports unexpected changes.
• Run the built-in Linux workflow in .gitea/workflows/ci.yml on every push.
• Run the real client runtime gate separately on a machine that has the client runtime assets available.
• For that runner, use .gitea/workflows/runtime-self-hosted.yml plus scripts/self_hosted_runtime_ci.py.

Production posture

• The client should embed only verifier material and metadata.
• The launcher should provide the runtime master key.
• If .m2p exists and runtime key delivery fails, startup should fail hard.
• Do not silently fall back to legacy packs in production.