eggpack-github 0.1.2

GitHub draft release staging adapter and local staging payload materializer
Documentation

eggpack-github

GitHub draft release staging adapter and local staging payload materializer (CI M003a).

  • Draft only; exact existing tag only; no publication.
  • Eggpack never creates, moves, force-updates, or deletes tags; annotated tags are peeled with a bounded loop to an exact commit.
  • Draft creation sets draft: true and make_latest: false; there is no API/CLI path that publishes a release.
  • Published or immutable releases are never mutated; unexpected or mismatched assets fail closed without clobber.
  • Same-name assets are reused only on exact size plus sha256:<digest> match.
  • A zero-byte starter asset left by a failed 502 upload is the only narrowly recoverable deletion; the invocation still fails and a later explicit rerun may resume.
  • Credentials are environment-only (GITHUB_TOKEN); tokens never appear in argv, config, evidence, errors, or Debug output.
  • Production endpoints are fixed to https://api.github.com with uploads constrained to https://uploads.github.com; every request uses Accept: application/vnd.github+json, X-GitHub-Api-Version: 2026-03-10, and a bounded User-Agent.
  • HTTP retries and redirects are disabled via the lean eggfetch-core profile (standard-http1, tls-rustls, tls-native-roots, json); 3xx fails closed.
  • Bounded timeouts and metadata body sizes apply to every request; local staging paths reject symlinks and traversal.
  • Incomplete drafts remain visible for maintainer inspection after failure; reruns reconcile exact state without automatic retry or broad cleanup.
  • Production asset files are opened once, length- and SHA-256-verified in bounded 64 KiB chunks, then uploaded from that same handle as a known-length one-shot stream. No full-file upload buffer is materialized.
  • Asset reconciliation reads every page under the policy bound (default 16, maximum 32); a full final allowed page fails closed because completeness is unknown.
  • Upload templates are parsed and checked against the exact HTTPS uploads.github.com origin and current release path. Asset names are encoded as URL query pairs and round-trip unchanged.
  • This crate owns no producer rule of its own. The SHA-256 hex acceptance set belongs to eggpack-manifest (ADR-0006), the file digest and the exact-tag safety rule belong to eggpack-core; this crate applies them and keeps its own diagnostic wording.

Local payload (prepare_staging_payload) revalidates the finalized root against the contract and manifest, rejects missing/extra/tampered files, writes a standalone release-manifest.json that decodes back to the exact M004 manifest, generates deterministic install.sh/install.ps1 with exact-tag origins (https://github.com/<owner>/<repo>/releases/download/<tag>), and emits a deterministic StagingPayloadV1. M004 root semantics are unchanged.

There is one staging-payload builder. prepare_staging_payload and prepare_staging_payload_with_presentation are thin entry points into it; the installer presentation selects only the installer surface — the names the generated exact installers are staged under, and whether the product wrappers become the public install surface. Every other step — validation, inventory construction, sidecars, installers, digest loop, canonical sort, and payload assembly — is implemented once, so the two entry points cannot diverge.

See plans/implementation/ci-release-orchestration/003a-local-staging-payload-and-github-draft-adapter.md and plans/closure/ci-release-orchestration/003a-status.md.

M003b consumes this adapter from one generated stage job only: the workflow checks out the exact tag, downloads the exact aggregate artifact, runs the payload materializer, then reconciles the draft with environment-only credentials, and uploads the bounded receipt. No other job gains write authority; reruns reuse exact drafts/assets without clobber. Live draft evidence is tracked by plans/closure/ci-release-orchestration/003b-status.md.

M003d adds the staging-owned installer presentation policy (InstallerPresentationV1) and the static draft template (GitHubDraftTemplateV1). GeneratedDefault preserves the behavior above byte-for-byte. ProductWrappers stages four installer assets: consumer-owned wrapper bytes copied exactly from the verified source tree as the public install.sh/install.ps1 (new product_posix_wrapper / product_powershell_wrapper kinds), plus the Eggpack-generated exact installers under configured non-colliding names as qualified-bootstrap evidence. Wrapper sources are explicit repository-relative paths (regular non-symlink files, 1 MiB bound each, no traversal or interpolation, no execution during staging). The template carries only owner, repository, fixed title prefix, body, prerelease flag, and transport bounds; resolve(tag) appends the exact validated tag with no templating language. The staging payload schema stays v1: default payloads parse on existing readers unchanged, while wrapper payloads fail closed on readers that do not know the new kinds. Ownership boundary: generated exact installers are Eggpack first-install evidence; product wrappers are consumer-owned selection/fallback/install UX and are only ever copied as bytes, never executed by staging.

See plans/implementation/ci-release-orchestration/003d-consumer-release-composition-seam.md and plans/closure/ci-release-orchestration/003d-status.md.