This document defines the manual, maintainer-controlled release process for Eggsec. Release cadence and publication are explicit maintainer decisions.
- No GitHub Actions workflow publishes any package.
- No tag triggers artifact construction, publication, or GitHub Release creation.
- No workflow requires registry credentials or trusted-publishing OIDC permissions.
- The final publish command is typed explicitly by a maintainer in a local or maintainer-controlled environment.
- Validation and publication are separate steps.
- Failed publication is handled according to registry immutability rules; an already published version is never overwritten.
| Registry | Package | Publication method |
|---|---|---|
| crates.io | eggsec-core, eggsec-policy, eggsec-report-model, eggsec-agent, eggsec-runtime, eggsec-runtime-independent leaves (eggsec-transport, eggsec-transport-eggfetch, eggsec-tool-core, eggsec-db-lab, eggsec-mobile-lab, eggsec-udp-scan, eggsec-output, eggsec-ui-model, eggsec-web-proxy, eggsec-daemon-protocol), eggsec, eggsec-daemon |
cargo publish (manual) |
| PyPI | eggsec |
maturin publish (manual) |
| TestPyPI | eggsec |
Optional, manual rehearsal |
Note: eggsec-cli, eggsec-tui, eggsec-python, and the three
knowledge-corpus leaves (eggsec-service-db, eggsec-secrets,
eggsec-payloads) have publish = false and are not published to
crates.io.
The NSE runtime is consumed as the published eggsec-nse = "0.2.0"
crates.io dependency behind the optional engine nse feature (engine
manifest + Cargo.lock must agree — guard Check 144). It is not a member
of this workspace release sequence and is not published from this repo.
The validated release host is Linux (the CI and primary development
environment). make release-check has been verified end-to-end on Linux.
macOS and Windows CI jobs verify that the workspace compiles on those
platforms, but release-check.sh has not been executed end-to-end on
macOS. Linux is the tested and supported release host; macOS release-script
compatibility is unverified.
Run the local release check script:
make release-check
# or directly:
scripts/release-check.sh <version>This validates without publishing. The Rust portion has three deliberately separate levels:
- Level A — local archives (default): the helper derives the publishable
set from Cargo metadata and runs
cargo package --workspace --no-verify --target-dir <isolated-target>, excludingeggsec-cli,eggsec-tui, andeggsec-python. Cargo creates the.cratefiles; the helper emits an exact JSONL inventory, records each archive's size and SHA-256, inspects the normalized manifest/content, and runs standalonecargo metadata --no-deps --offlineoutside the source workspace. Any Cargo or inspection failure is a failure. - Level B — registry preflight (optional locally):
EGGSEC_RELEASE_REGISTRY_PREFLIGHT=1 make release-checkrunscargo publish --dry-runin dependency order. This is registry-sensitive and is required layer by layer immediately before a staged publication. - Level C — publication (manual): actual
cargo publishcommands are typed explicitly by a maintainer.release-check.sh, tests, and CI never publish packages.
The default check validates without publishing:
- Clean working tree and explicit current commit
- Version alignment across Cargo.toml, pyproject.toml, and optional argument
- Package graph validation via
scripts/release-package-graph.py make check(mandatory Rust CI contract)make check-python(mandatory Python CI contract, skippable withEGGSEC_RELEASE_SKIP_PYTHON=1)- Cargo-native workspace package generation, exact archive inventory, standalone manifest parsing, and archive inspection
- Python wheel and sdist build
- Fresh-environment wheel installation and smoke test
- Artifact inventory (filenames, sizes, SHA-256 hashes)
Optional environment controls:
EGGSEC_RELEASE_SKIP_PYTHON=1 # skip Python checks (Rust-only release)
EGGSEC_RELEASE_REGISTRY_PREFLIGHT=1 # run cargo publish --dry-run (network-sensitive)
EGGSEC_RELEASE_KEEP_ARTIFACTS=1 # do not clean build artifacts on exit
Optional full validation (pre-release, not required for every merge):
make check-full- Authenticated with crates.io using the maintainer's chosen mechanism
(e.g.,
cargo loginwith an API token). - All version files aligned and clean working tree.
Publish crates in dependency order. The authoritative order is generated by:
python scripts/release-package-graph.py orderCurrent publishable set and order (dependencies before dependents; regenerate with the command above after any manifest change):
eggsec-coreeggsec-agenteggsec-policyeggsec-report-modeleggsec-db-labeggsec-mobile-labeggsec-outputeggsec-runtimeeggsec-daemon-protocoleggsec-tool-coreeggsec-transporteggsec-transport-eggfetcheggsec-udp-scaneggsec-ui-modeleggsec-web-proxyeggseceggsec-daemon
Wait for each crate to appear on crates.io before publishing dependents. The staged sequence is:
validate all local archives
publish one dependency layer
wait for registry visibility
run cargo publish --dry-run for the next layer
publish the next layer
repeat
A registry failure, timeout, or unavailable dependency remains a failure or unavailable result; it is never converted into a local archive pass.
Private crates (not published to crates.io): eggsec-cli, eggsec-tui, eggsec-python, eggsec-service-db, eggsec-secrets, eggsec-payloads. The standalone eggsec-nse runtime is released from its own repository; Eggsec consumes it as the published crates.io release eggsec-nse 0.2.0, so it is not part of this workspace release sequence.
cargo publish -p eggsec-core
# wait for availability...
cargo publish -p eggsec-agent
cargo publish -p eggsec-policy
cargo publish -p eggsec-report-model
cargo publish -p eggsec-db-lab
cargo publish -p eggsec-mobile-lab
cargo publish -p eggsec-output
cargo publish -p eggsec-runtime
cargo publish -p eggsec-daemon-protocol
cargo publish -p eggsec-tool-core
cargo publish -p eggsec-transport
cargo publish -p eggsec-transport-eggfetch
cargo publish -p eggsec-udp-scan
cargo publish -p eggsec-ui-model
cargo publish -p eggsec-web-proxy
# wait for availability...
cargo publish -p eggsec
# wait for availability...
cargo publish -p eggsec-daemon- Never attempt to overwrite an immutable version. Bump the version for corrections.
- Tag only after the maintainer decides the publication state warrants it.
- Authenticated with PyPI (API token in
~/.pypircor environment). maturinandtwineinstalled.- Release check passed.
cd crates/eggsec-python
rm -rf dist/ target/wheels/
maturin build --release --out dist
maturin sdist --out dist
python -m twine check dist/*Preferred command:
cd crates/eggsec-python
maturin publishOr manually:
python -m twine upload dist/*TestPyPI is opt-in, not a release gate. If used, the rehearsal version must be unique because package indexes are immutable.
python -m twine upload --repository testpypi dist/*Tagging and GitHub Release notes are optional manual follow-up activities. They must not publish registry packages or trigger release workflows.
If maintainers create a GitHub Release manually, document it as metadata/distribution convenience after registry publication, not the source of release cadence.
- Update
versionin workspaceCargo.toml. - Update
versionincrates/eggsec-python/pyproject.tomlto match. - Update every version-qualified internal path dependency in publishable
manifests (the
version = "..."alongsidepath = "..."), including target-specific and aliased dependencies. Inventory them with:python3 scripts/release-package-graph.py version-locations. - Regenerate
Cargo.lockonly when required by the manifest change; review third-party changes and use--lockedchecks. - Run
python3 scripts/release-package-graph.py validateandmake release-checkto identify stale versions and validate archives. - Publish crates and/or Python package as described above.
- Tag the release (optional, after publication):
git tag v<version>. - Push tag:
git push origin v<version>.
- If a version is partially published (some crates succeeded, others failed), complete the remaining publishes if possible. If the failing crate cannot be fixed without a code change, bump the version and start fresh.
- Never overwrite an immutable published version.