Skip to content

feat: airgap distribution — signed release tarballs + AIRGAP.md - #1

Open
turbobeest wants to merge 1 commit into
mainfrom
feat/airgap-distribution
Open

feat: airgap distribution — signed release tarballs + AIRGAP.md#1
turbobeest wants to merge 1 commit into
mainfrom
feat/airgap-distribution

Conversation

@turbobeest

Copy link
Copy Markdown
Owner

Summary

  • Adds .github/workflows/release.yml — on v* tag push, builds a deterministic tarball, computes SHA256, and signs with cosign keyless (sigstore GitHub Actions OIDC). All four artifacts (tarball, .sha256, .sig, .pem) are attached to the GitHub Release. Includes a verification smoke test before publishing so a mis-signed release cannot reach consumers.
  • Adds AIRGAP.md — consumer-facing offline-consumption guide covering acquisition (gh release / curl), verification with cosign in both online and offline modes, extraction and consumption layout, and the update flow for vendored catalogs. Also includes a maintainer release-procedure section.

Why

Downstream consumers — specifically autonomy-harness Mode-C/D deployments (RHEL VDIs pointed at Ollama on NVIDIA DGX Spark; airgapped networks) — need to vendor the catalog at a known-good version with cryptographic provenance. Today the only acquisition path is git clone, which is unworkable for isolated networks and not auditable for regulated environments.

This PR is also useful for non-airgap consumers who want to pin to a specific release rather than tracking main.

How it works

  • Determinism: tar --sort=name --owner=0 --group=0 --numeric-owner --mtime='@0' --format=ustar, then gzip -n -9. Same tag → same tarball bytes.
  • Signing: sigstore/cosign-installer@v3 + cosign sign-blob. Uses GitHub Actions OIDC (id-token: write); no signing keys to manage. Identity is bound to the workflow running in turbobeest/audits via the certificate's SAN.
  • Smoke test: the workflow runs cosign verify-blob against its own output before creating the release, so a mis-signed artifact halts the workflow rather than reaching the public release.
  • Dry-run: workflow_dispatch path produces the artifacts as workflow outputs only — no public release — so the artifact-production path can be exercised before tagging a real v1.0.0.

What's NOT in this PR

  • No tag is pushed; no release fires from this merge alone. The first real release happens when someone pushes v1.0.0.
  • The audit-browser/ SvelteKit app is intentionally excluded from the tarball (it deploys separately via deploy-pages.yml); AIRGAP.md documents how offline networks can deploy it themselves.
  • Does not change LICENSE, the existing update-inventory.yml cadence, or any audit YAML content.

Test plan

  • Run the workflow via workflow_dispatch with input v0.0.0-dryrun to confirm artifact production end-to-end on GitHub Actions.
  • Download the dry-run artifacts from the workflow run; run consumer-side verification per AIRGAP.md (sha256 + cosign verify-blob) on a local machine.
  • Extract the dry-run tarball and confirm the directory layout matches what AIRGAP.md documents.
  • Confirm the dry-run does not create a public GitHub Release.
  • After review, when ready to cut the first real release: git tag -a v1.0.0 -m \"Release v1.0.0\" && git push origin v1.0.0. Confirm the release page lists all four artifacts and that the smoke-test step succeeded.

Notes

  • Cosign keyless requires the GitHub-hosted runner to reach sigstore (Fulcio + Rekor) at sign time. This is the producer side; consumers can verify offline (see AIRGAP.md "Offline verification").
  • If audits release CI ever moves to self-hosted runners on a restricted network, the workflow will need adjustment (either a network exception for sigstore endpoints, or a switch to keyed signing).

🤖 Drafted by Claude (Opus 4.7) on behalf of @turbobeest as part of the autonomy-harness deployment-modes work.

Add release.yml workflow that on v* tag push builds a deterministic
tarball, computes SHA256, and signs with cosign keyless via sigstore
GitHub Actions OIDC. All four artifacts (tarball, .sha256, .sig, .pem)
are attached to the GitHub Release. Determinism is enforced via
sorted file order, zeroed timestamps, and numeric owner/group in the
tar invocation. The workflow includes a verification smoke test
before publishing so a mis-signed release cannot reach consumers.

AIRGAP.md documents consumer-side acquisition (gh release / curl),
verification with cosign in both online and offline modes, extraction
and consumption layout, and the update flow for vendored catalogs.
A maintainer release-procedure section covers the tag-driven cut and
the workflow_dispatch dry-run path.

Targets autonomy-harness Mode-C/D deployments (RHEL VDIs, airgapped
networks) but is useful for any consumer that wants to vendor the
catalog at a known-good version.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant