diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e13e85c..a495bd3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -39,7 +39,10 @@ just --list # see every available recipe ## The development loop Run the Rust gate before pushing. It includes native and release checks, -Linux-target Clippy, a locked build, and tests: +Linux-target Clippy, a locked build, and tests. + +The `Quality (ubuntu-latest)` and `Quality (macos-latest)` checks are required +on `main`. ```sh just ci-rust # fmt-check, native/release/Linux clippy, build, test @@ -59,6 +62,17 @@ just audit # advisory database check, warnings fail ## Submitting a change +Release tooling has its own focused checks: + +```sh +just release-test +just release-build aarch64-apple-darwin # select the native target +``` + +These require Python 3.11 or newer. +The [release guide](../docs/src/development/releases.md) describes GitHub +attestations, tag/manual publication, and consumer verification. + 1. Branch off `main` (`git switch -c fix/short-description`). 2. Make the change and add tests where needed. 3. Run the full `just ci`. diff --git a/.github/release/publish.sh b/.github/release/publish.sh new file mode 100644 index 0000000..2488fca --- /dev/null +++ b/.github/release/publish.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Publish only after checking every draft asset's integrity and GitHub attestation. +# Args: tag (string), source commit (SHA), artifact directory (path). +# Requires GH_TOKEN and the GitHub workflow identity variables. +set -euo pipefail + +tag="$1" +commit="$2" +directory="$3" +if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then + echo "Release already exists; refusing to replace its assets" >&2 + exit 1 +fi +release_flags=() +if [[ "$tag" == *-* ]]; then + release_flags+=(--prerelease) +fi +gh release create "$tag" "$directory"/* \ + --repo "$GITHUB_REPOSITORY" --verify-tag --draft \ + --title "$tag" --generate-notes "${release_flags[@]}" +download_dir="$(mktemp -d)" +trap 'rm -rf "$download_dir"' EXIT +gh release download "$tag" --repo "$GITHUB_REPOSITORY" --dir "$download_dir" +just release-verify "$tag" "$commit" "$download_dir" +for artifact in "$download_dir"/*; do + gh attestation verify "$artifact" --repo "$GITHUB_REPOSITORY" \ + --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \ + --source-digest "$GITHUB_SHA" --source-ref "$GITHUB_REF" \ + --deny-self-hosted-runners +done +gh release edit "$tag" --repo "$GITHUB_REPOSITORY" --draft=false diff --git a/.github/release/release.py b/.github/release/release.py new file mode 100644 index 0000000..ec9daf6 --- /dev/null +++ b/.github/release/release.py @@ -0,0 +1,271 @@ +"""Validate release sources and package and verify the distributed files.""" + +import argparse +import gzip +import hashlib +import json +import os +import re +import shutil +import subprocess +import tarfile +import tempfile +import tomllib +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +TARGETS = ( + "x86_64-unknown-linux-gnu", + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-gnu", + "x86_64-apple-darwin", + "aarch64-apple-darwin", +) + + +def git(root: Path, *args: str) -> str: + """Run Git in the source checkout. + + Args: + root (Path): Checkout directory. + *args (str): Git arguments. + + Returns: + str: Standard output with trailing whitespace removed. + + Raises: + subprocess.CalledProcessError: Git rejects the operation. + """ + return subprocess.check_output(["git", *args], cwd=root, text=True).strip() + + +def validate_tag(tag: str, version: str) -> None: + """Require a version tag matching the Cargo package. + + Args: + tag (str): Release tag, including its v prefix. + version (str): Cargo package version. + + Raises: + ValueError: The tag is malformed or differs from the package version. + """ + if not re.fullmatch(r"v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", tag): + raise ValueError( + "release tag must be vMAJOR.MINOR.PATCH with an optional prerelease" + ) + if tag != f"v{version}": + raise ValueError("release tag does not match Cargo.toml") + + +def plan(root: Path, tag: str, preview: bool) -> tuple[str, str]: + """Resolve the immutable source revision for a release or PR build. + + Args: + root (Path): Checkout with fetched tags and origin/main. + tag (str): Existing release tag; unused for a PR preview. + preview (bool): Whether to build the checked-out PR revision. + + Returns: + tuple[str, str]: Validated tag and source commit SHA. + + Raises: + ValueError: The tag/version is invalid or its commit is outside main. + subprocess.CalledProcessError: A required Git ref is unavailable. + """ + if preview: + manifest = tomllib.loads((root / "Cargo.toml").read_text()) + tag = f"v{manifest['package']['version']}" + commit = git(root, "rev-parse", "HEAD") + else: + # Validate before using the supplied tag as a Git revision. + validate_tag(tag, tag.removeprefix("v")) + commit = git(root, "rev-parse", "--verify", f"refs/tags/{tag}^{{commit}}") + if subprocess.run( + ["git", "merge-base", "--is-ancestor", commit, "origin/main"], + cwd=root, + check=False, + ).returncode: + raise ValueError("release tag must point to a commit reachable from main") + manifest = tomllib.loads(git(root, "show", f"{commit}:Cargo.toml")) + validate_tag(tag, manifest["package"]["version"]) + return tag, commit + + +def archive_names(tag: str) -> set[str]: + """Return the complete set of versioned archive names. + + Args: + tag (str): Validated release tag. + + Returns: + set[str]: One archive filename for each supported target. + """ + return {f"postmaster-{tag}-{target}.tar.gz" for target in TARGETS} + + +def verify_archive(path: Path, root: Path | None = None) -> None: + """Check archive contents and optionally execute the extracted binary. + + Args: + path (Path): Release archive to inspect. + root (Path | None): Source checkout for an optional packaged-binary smoke check. + + Raises: + ValueError: Entries include unexpected paths, links, or permissions. + subprocess.CalledProcessError: The packaged binary fails its smoke check. + """ + with tarfile.open(path, "r:gz") as archive: + members = archive.getmembers() + if [entry.name for entry in members] != ["postmaster", "LICENSE"]: + raise ValueError("archive must contain exactly postmaster and LICENSE") + if any(not entry.isfile() for entry in members): + raise ValueError("archive entries must be regular files") + if [entry.mode for entry in members] != [0o755, 0o644]: + raise ValueError("archive permissions differ from the release contract") + if root is not None: + with tempfile.TemporaryDirectory(prefix="postmaster-release-") as directory: + binary = Path(directory) / "postmaster" + with ( + archive.extractfile(members[0]) as source, + binary.open("wb") as output, + ): + shutil.copyfileobj(source, output) + binary.chmod(0o755) + version = tomllib.loads((root / "Cargo.toml").read_text())["package"][ + "version" + ] + actual = subprocess.check_output( + [str(binary), "--version"], text=True + ).strip() + if actual != f"postmaster {version}": + raise ValueError("packaged binary reports the wrong version") + subprocess.run( + [ + str(binary), + "exec", + "--config", + str(root / "docs/examples/exec-env.json"), + "--check", + ], + check=True, + ) + + +def package(root: Path, target: str) -> Path: + """Package a built release binary and smoke-test the resulting archive. + + Args: + root (Path): Built source checkout. + target (str): Supported Rust target triple. + + Returns: + Path: Verified archive under target/release-artifacts. + + Raises: + ValueError: The target or binary type is invalid, or verification fails. + OSError: An input cannot be read or the archive cannot be written. + """ + if target not in TARGETS: + raise ValueError("unsupported release target") + version = tomllib.loads((root / "Cargo.toml").read_text())["package"]["version"] + tag = f"v{version}" + validate_tag(tag, version) + binary = root / "target" / target / "release/postmaster" + if binary.is_symlink() or not binary.is_file(): + raise ValueError("release binary must be a regular file") + directory = root / "target/release-artifacts" + directory.mkdir(parents=True, exist_ok=True) + path = directory / f"postmaster-{tag}-{target}.tar.gz" + timestamp = int(git(root, "show", "-s", "--format=%ct", "HEAD")) + with ( + path.open("wb") as output, + gzip.GzipFile(fileobj=output, mode="wb", filename="", mtime=0) as compressed, + tarfile.open(fileobj=compressed, mode="w") as archive, + ): + for source, name, mode in [ + (binary, "postmaster", 0o755), + (root / "LICENSE", "LICENSE", 0o644), + ]: + info = tarfile.TarInfo(name) + info.size = source.stat().st_size + info.mode = mode + info.mtime = timestamp + with source.open("rb") as data: + archive.addfile(info, data) + verify_archive(path, root) + return path + + +def release_files(directory: Path, tag: str, commit: str, verify: bool) -> None: + """Create or verify a complete release manifest and its bound source metadata. + + Args: + directory (Path): Release files, without nested directories. + tag (str): Release tag matching the source manifest. + commit (str): Exact tagged source commit. + verify (bool): Verify existing metadata/checksums instead of creating them. + + Raises: + ValueError: Files, metadata, archive contents, or hashes are inconsistent. + OSError: Release files cannot be read or written. + """ + validate_tag(tag, tag.removeprefix("v")) + if not re.fullmatch(r"[0-9a-f]{40}", commit): + raise ValueError("release source must be an exact commit SHA") + archives = archive_names(tag) + expected = archives | ({"release.json", "SHA256SUMS"} if verify else set()) + if {p.name for p in directory.iterdir()} != expected: + raise ValueError("release files do not match the complete target set") + if any(p.is_symlink() or not p.is_file() for p in directory.iterdir()): + raise ValueError("release files must be regular files") + for name in sorted(archives): + verify_archive(directory / name) + metadata = {"tag": tag, "commit": commit, "targets": list(TARGETS)} + metadata_path = directory / "release.json" + if verify: + if json.loads(metadata_path.read_text()) != metadata: + raise ValueError( + "release metadata does not match its tag and source commit" + ) + else: + metadata_path.write_text(json.dumps(metadata, indent=2) + "\n") + checksums = [] + for name in sorted(archives | {"release.json"}): + with (directory / name).open("rb") as data: + digest = hashlib.file_digest(data, "sha256").hexdigest() + checksums.append(f"{digest} {name}\n") + manifest = directory / "SHA256SUMS" + if verify: + if manifest.read_text() != "".join(checksums): + raise ValueError("release checksums do not match the distributed files") + else: + manifest.write_text("".join(checksums)) + + +def main() -> None: + """Dispatch release tooling; invalid input terminates with a nonzero status.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("command", choices=["plan", "package", "manifest", "verify"]) + parser.add_argument("args", nargs="*") + args = parser.parse_args() + if args.command == "plan": + event = os.environ.get("GITHUB_EVENT_NAME", "workflow_dispatch") + if ( + event == "workflow_dispatch" + and os.environ.get("GITHUB_REF", "refs/heads/main") != "refs/heads/main" + ): + raise ValueError("manual releases must run the workflow from main") + tag, commit = plan( + ROOT, os.environ.get("RELEASE_TAG", ""), event == "pull_request" + ) + print(f"tag={tag}\ncommit={commit}") + elif args.command == "package": + (target,) = args.args + print(package(ROOT, target)) + else: + tag, commit, directory = args.args + release_files(Path(directory), tag, commit, args.command == "verify") + + +if __name__ == "__main__": + main() diff --git a/.github/release/test_release.py b/.github/release/test_release.py new file mode 100644 index 0000000..5b6af23 --- /dev/null +++ b/.github/release/test_release.py @@ -0,0 +1,329 @@ +"""Exercise release source authorization, archive integrity and attestation policy.""" + +import io +import json +import os +import re +import subprocess +import tarfile +import tempfile +import unittest +from pathlib import Path + +import release + + +class ReleaseTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory(prefix="postmaster-release-test-") + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.tag = "v0.1.0" + self.commit = "a" * 40 + + def archive(self, path, binary=b"binary", name="postmaster", kind=tarfile.REGTYPE): + with tarfile.open(path, "w:gz") as archive: + for entry, data, mode in [ + (name, binary, 0o755), + ("LICENSE", b"license", 0o644), + ]: + info = tarfile.TarInfo(entry) + info.mode = mode + info.type = kind if entry == name else tarfile.REGTYPE + info.size = len(data) if info.isfile() else 0 + archive.addfile(info, io.BytesIO(data) if info.isfile() else None) + + def files(self): + for name in release.archive_names(self.tag): + self.archive(self.root / name) + + def test_tag_resolves_its_own_manifest_and_rejects_unmerged_commit(self): + release.git(self.root, "init", "-b", "main") + manifest = self.root / "Cargo.toml" + manifest.write_text('[package]\nversion = "0.1.0"\n') + release.git(self.root, "add", "Cargo.toml") + commit_args = [ + "-c", + "commit.gpgsign=false", + "-c", + "core.hooksPath=/dev/null", + "-c", + "user.name=Release test", + "-c", + "user.email=release@example.invalid", + "commit", + "-m", + "fixture", + ] + release.git(self.root, *commit_args) + release.git(self.root, "tag", self.tag) + original = release.git(self.root, "rev-parse", "HEAD") + manifest.write_text('[package]\nversion = "0.2.0"\n') + release.git(self.root, "add", "Cargo.toml") + release.git(self.root, *commit_args) + release.git(self.root, "update-ref", "refs/remotes/origin/main", "HEAD") + self.assertEqual(release.plan(self.root, self.tag, False), (self.tag, original)) + release.git(self.root, "checkout", "-b", "unmerged") + manifest.write_text('[package]\nversion = "0.3.0"\n') + release.git(self.root, "add", "Cargo.toml") + release.git(self.root, *commit_args) + release.git(self.root, "tag", "v0.3.0") + with self.assertRaisesRegex(ValueError, "reachable from main"): + release.plan(self.root, "v0.3.0", False) + release.git(self.root, "tag", "v0.9.0", original) + with self.assertRaisesRegex(ValueError, "Cargo.toml"): + release.plan(self.root, "v0.9.0", False) + + def test_tag_rejects_revision_syntax_and_shell_input(self): + for tag in ["main", "v0.1.0^{commit}", "v0.1.0;exit", "v0.1.0\n", "v../0.1.0"]: + with self.subTest(tag=tag), self.assertRaises(ValueError): + release.validate_tag(tag, "0.1.0") + + def test_archive_rejects_traversal_links_and_duplicate_entries(self): + for name, kind in [ + ("../postmaster", tarfile.REGTYPE), + ("postmaster", tarfile.SYMTYPE), + ("LICENSE", tarfile.REGTYPE), + ]: + path = self.root / "bad.tar.gz" + self.archive(path, name=name, kind=kind) + with self.subTest(name=name, kind=kind), self.assertRaises(ValueError): + release.verify_archive(path) + + def test_manifest_rejects_missing_and_unexpected_targets(self): + self.files() + extra = self.root / "unexpected.tar.gz" + extra.write_bytes(b"unexpected") + with self.assertRaisesRegex(ValueError, "complete target set"): + release.release_files(self.root, self.tag, self.commit, False) + extra.unlink() + (self.root / next(iter(release.archive_names(self.tag)))).unlink() + with self.assertRaisesRegex(ValueError, "complete target set"): + release.release_files(self.root, self.tag, self.commit, False) + + def test_manifest_binds_source_and_rejects_changed_archive(self): + self.files() + release.release_files(self.root, self.tag, self.commit, False) + release.release_files(self.root, self.tag, self.commit, True) + with self.assertRaisesRegex(ValueError, "source commit"): + release.release_files(self.root, self.tag, "b" * 40, True) + self.archive( + self.root / min(release.archive_names(self.tag)), binary=b"changed" + ) + with self.assertRaisesRegex(ValueError, "checksums"): + release.release_files(self.root, self.tag, self.commit, True) + + def test_install_instructions_stop_on_failed_verification(self): + guide = (release.ROOT / "docs/src/development/releases.md").read_text() + snippet = ( + guide.split("## Verify and install", 1)[1] + .split("```sh\n", 1)[1] + .split("```", 1)[0] + ) + tools = self.root / "bin" + tools.mkdir() + program = tools / "stub" + program.write_text("""#!/usr/bin/env python3 +import json, os, sys +from pathlib import Path +name = Path(sys.argv[0]).name +if name == "install": + Path("installed").touch() +if name == "gh": + with Path("verified.jsonl").open("a") as log: + log.write(json.dumps(sys.argv[1:]) + "\\n") + if os.environ.get("REJECT_ARTIFACT") == sys.argv[3]: + sys.exit(1) +sys.exit(1 if os.environ.get("REJECT") == name else 0) +""") + program.chmod(0o755) + for name in ["curl", "shasum", "gh", "tar", "mkdir", "install"]: + (tools / name).symlink_to(program) + archive = "postmaster-v0.1.0-aarch64-apple-darwin.tar.gz" + (self.root / "SHA256SUMS").write_text("a" * 64 + f" {archive}\n") + env = os.environ | { + "PATH": str(tools) + os.pathsep + os.environ["PATH"], + } + for failure in [ + {"REJECT": "curl"}, + {"REJECT": "shasum"}, + {"REJECT_ARTIFACT": "SHA256SUMS"}, + {"REJECT_ARTIFACT": archive}, + ]: + with self.subTest(failure=failure): + result = subprocess.run( + ["sh", "-c", snippet], + cwd=self.root, + env=env | failure, + check=False, + capture_output=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertFalse((self.root / "installed").exists()) + log = self.root / "verified.jsonl" + log.write_text("") + subprocess.run( + ["sh", "-c", snippet], + cwd=self.root, + env=env, + check=True, + capture_output=True, + ) + self.assertTrue((self.root / "installed").exists()) + calls = [json.loads(line) for line in log.read_text().splitlines()] + self.assertEqual( + [call[:3] for call in calls], + [ + ["attestation", "verify", "SHA256SUMS"], + ["attestation", "verify", archive], + ], + ) + identity = ( + "https://github.com/beardedeagle/postmaster/.github/workflows/release.yml@" + ) + for call in calls: + self.assertEqual(call[call.index("--repo") + 1], "beardedeagle/postmaster") + self.assertEqual( + call[call.index("--signer-workflow") + 1], + "beardedeagle/postmaster/.github/workflows/release.yml", + ) + self.assertIn("--deny-self-hosted-runners", call) + pattern = call[call.index("--cert-identity-regex") + 1] + for ref in ["refs/heads/main", "refs/tags/v0.1.0", "refs/tags/v0.1.0-rc.1"]: + self.assertIsNotNone(re.fullmatch(pattern, identity + ref)) + for ref in [ + "refs/pull/15/merge", + "refs/heads/untrusted", + "refs/tags/untrusted", + "refs/tags/v0.1.0/untrusted", + "refs/heads/untrusted@refs/heads/main", + "refs/tags/v0.1.0@refs/heads/main", + ]: + self.assertIsNone(re.fullmatch(pattern, identity + ref)) + self.assertIsNone( + re.fullmatch( + pattern, + identity.replace("postmaster/", "other/") + "refs/heads/main", + ) + ) + + def test_manual_release_rejects_untrusted_branch(self): + env = os.environ | { + "GITHUB_EVENT_NAME": "workflow_dispatch", + "GITHUB_REF": "refs/heads/untrusted", + "RELEASE_TAG": self.tag, + } + result = subprocess.run( + ["python3", str(release.ROOT / ".github/release/release.py"), "plan"], + env=env, + check=False, + capture_output=True, + text=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertIn("workflow from main", result.stderr) + + def test_publication_requires_verified_downloads_and_preserves_existing_release( + self, + ): + directory = self.root / "dist" + directory.mkdir() + for name in release.archive_names(self.tag): + self.archive(directory / name) + release.release_files(directory, self.tag, self.commit, False) + tools = self.root / "bin" + tools.mkdir() + fake = tools / "gh" + fake.write_text("""#!/usr/bin/env python3 +import json, os, shutil, sys +from pathlib import Path +args = sys.argv[1:] +with Path(os.environ["GH_TEST_LOG"]).open("a") as log: + log.write(json.dumps(args) + "\\n") +if args[:2] == ["release", "view"]: + sys.exit(0 if os.environ.get("GH_TEST_EXISTING") else 1) +if args[:2] == ["release", "download"]: + target = Path(args[args.index("--dir") + 1]) + for source in Path(os.environ["GH_TEST_ASSETS"]).iterdir(): + shutil.copyfile(source, target / source.name) + if os.environ.get("GH_TEST_CORRUPT"): + (target / "release.json").write_text("{}") + if os.environ.get("GH_TEST_MISSING"): + (target / os.environ["GH_TEST_MISSING"]).unlink() +if args[:2] == ["attestation", "verify"] and Path(args[2]).name == os.environ.get("GH_TEST_BAD_ATTESTATION"): + sys.exit(1) +""") + fake.chmod(0o755) + log = self.root / "gh.log" + env = os.environ | { + "PATH": str(tools) + os.pathsep + os.environ["PATH"], + "GH_TEST_LOG": str(log), + "GH_TEST_ASSETS": str(directory), + "GITHUB_REPOSITORY": "beardedeagle/postmaster", + "GITHUB_SHA": self.commit, + "GITHUB_REF": "refs/tags/" + self.tag, + "JUST_NO_DOTENV": "true", + } + command = [ + "bash", + str(release.ROOT / ".github/release/publish.sh"), + self.tag, + self.commit, + str(directory), + ] + files = release.archive_names(self.tag) | {"SHA256SUMS", "release.json"} + for failure in [ + {"GH_TEST_CORRUPT": "1"}, + {"GH_TEST_EXISTING": "1"}, + {"GH_TEST_MISSING": min(files)}, + *({"GH_TEST_BAD_ATTESTATION": name} for name in sorted(files)), + ]: + with self.subTest(failure=failure): + log.write_text("") + result = subprocess.run( + command, + cwd=release.ROOT, + env=env | failure, + check=False, + capture_output=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertNotIn('"edit"', log.read_text()) + if "GH_TEST_EXISTING" in failure: + self.assertNotIn('"create"', log.read_text()) + for ref, digest in [ + (env["GITHUB_REF"], self.commit), + ("refs/heads/main", "b" * 40), + ]: + with self.subTest(ref=ref): + log.write_text("") + subprocess.run( + command, + cwd=release.ROOT, + env=env | {"GITHUB_REF": ref, "GITHUB_SHA": digest}, + check=True, + capture_output=True, + ) + calls = [json.loads(line) for line in log.read_text().splitlines()] + self.assertEqual(calls[-1][:2], ["release", "edit"]) + self.assertIn("--draft=false", calls[-1]) + verified = [ + call for call in calls if call[:2] == ["attestation", "verify"] + ] + self.assertEqual({Path(call[2]).name for call in verified}, files) + self.assertEqual(len(verified), len(files)) + for call in verified: + self.assertEqual( + call[call.index("--repo") + 1], "beardedeagle/postmaster" + ) + self.assertEqual( + call[call.index("--signer-workflow") + 1], + "beardedeagle/postmaster/.github/workflows/release.yml", + ) + self.assertEqual(call[call.index("--source-digest") + 1], digest) + self.assertEqual(call[call.index("--source-ref") + 1], ref) + self.assertIn("--deny-self-hosted-runners", call) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..d23f946 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,182 @@ +name: Release + +on: + push: + tags: ["v*"] + workflow_dispatch: + inputs: + tag: + description: Existing version tag to release (vMAJOR.MINOR.PATCH) + required: true + type: string + pull_request: + paths: + - ".github/workflows/release.yml" + - ".github/release/**" + - ".github/actions/setup-rust/**" + - "docs/src/development/releases.md" + - "Cargo.toml" + - "Cargo.lock" + - "src/**" + - "tests/**" + - "Justfile" + +concurrency: + group: release-${{ inputs.tag || github.ref_name }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +env: + JUST_NO_DOTENV: "true" + CARGO_TERM_COLOR: always + +jobs: + plan: + name: Validate release source + runs-on: ubuntu-24.04 + timeout-minutes: 15 + outputs: + tag: ${{ steps.source.outputs.tag }} + commit: ${{ steps.source.outputs.commit }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + - name: Test release tooling + run: just release-test + - name: Resolve source + id: source + env: + RELEASE_TAG: ${{ inputs.tag || github.ref_name }} + run: just release-plan >> "$GITHUB_OUTPUT" + + build: + name: Build ${{ matrix.target }} + needs: plan + runs-on: ${{ matrix.os }} + timeout-minutes: 30 + permissions: + contents: read + id-token: write + attestations: write + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-24.04 + target: x86_64-unknown-linux-gnu + - os: ubuntu-24.04 + target: x86_64-unknown-linux-musl + - os: ubuntu-24.04-arm + target: aarch64-unknown-linux-gnu + - os: macos-15-intel + target: x86_64-apple-darwin + - os: macos-15 + target: aarch64-apple-darwin + steps: + - name: Checkout validated source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.plan.outputs.commit }} + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + with: + targets: ${{ matrix.target }} + - name: Install musl linker + if: matrix.target == 'x86_64-unknown-linux-musl' + run: | + sudo apt-get update + sudo apt-get install --yes musl-tools + - name: Build, test and package release binary + env: + RELEASE_TARGET: ${{ matrix.target }} + run: just release-build "$RELEASE_TARGET" + - name: Attest the built archive + if: github.event_name != 'pull_request' + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: target/release-artifacts/*.tar.gz + create-storage-record: false + - name: Upload release archive + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: release-${{ matrix.target }} + path: target/release-artifacts/*.tar.gz + if-no-files-found: error + retention-days: 7 + + publish: + name: Verify and publish + if: github.event_name != 'pull_request' + needs: [plan, build] + runs-on: ubuntu-24.04 + timeout-minutes: 20 + environment: release + permissions: + contents: write + id-token: write + attestations: write + env: + RELEASE_TAG: ${{ needs.plan.outputs.tag }} + RELEASE_COMMIT: ${{ needs.plan.outputs.commit }} + steps: + - name: Checkout validated source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.plan.outputs.commit }} + fetch-depth: 0 + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + - name: Download built archives + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + pattern: release-* + merge-multiple: true + path: target/release-artifacts + - name: Check tag and build attestations + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + just release-plan > "$RUNNER_TEMP/release-source" + grep -Fx "commit=$RELEASE_COMMIT" "$RUNNER_TEMP/release-source" + for archive in target/release-artifacts/*.tar.gz; do + gh attestation verify "$archive" --repo "$GITHUB_REPOSITORY" \ + --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \ + --source-digest "$GITHUB_SHA" --source-ref "$GITHUB_REF" \ + --deny-self-hosted-runners + done + just release-manifest "$RELEASE_TAG" "$RELEASE_COMMIT" + - name: Verify release files + run: just release-verify "$RELEASE_TAG" "$RELEASE_COMMIT" + - name: Attest release metadata + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: | + target/release-artifacts/SHA256SUMS + target/release-artifacts/release.json + create-storage-record: false + - name: Verify downloaded release before publication + env: + GH_TOKEN: ${{ github.token }} + run: just release-publish "$RELEASE_TAG" "$RELEASE_COMMIT" diff --git a/CHANGELOG.md b/CHANGELOG.md index e820825..c31d80d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -136,6 +136,11 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - Provides native and cross builds through the Justfile build matrix. Cross builds use `cargo zigbuild`; builds preserve compiler flags and profile overrides, and `max` builds remap source paths. +- Builds five Linux and macOS release targets from version tags or manual + runs. Runs release-profile tests and packaged-binary checks, and generates + GitHub attestations for archives, SHA-256 manifests, and source metadata. + Verifies downloaded draft assets before publication and refuses to + overwrite existing releases. - Uses Justfile recipes for local checks and GitHub workflow definitions. In-repo setup actions refresh stable before resolving the repository's components and targets. Nix installation verifies diff --git a/Justfile b/Justfile index 54d98ae..c171062 100644 --- a/Justfile +++ b/Justfile @@ -83,6 +83,27 @@ audit: ci-rust: fmt-check clippy clippy-release clippy-linux build test ci: ci-rust flake-check +# Release tooling is shared by local checks and the release workflow. +release-test: + python3 -B -m unittest discover -s .github/release -p 'test_*.py' -v + +release-plan: + python3 .github/release/release.py plan + +release-build target: + cargo +{{stable_toolchain}} test --locked --release --target {{quote(target)}} + cargo +{{stable_toolchain}} build --locked --release --target {{quote(target)}} + python3 .github/release/release.py package {{quote(target)}} + +release-manifest tag commit directory="target/release-artifacts": + python3 .github/release/release.py manifest {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + +release-verify tag commit directory="target/release-artifacts": + python3 .github/release/release.py verify {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + +release-publish tag commit directory="target/release-artifacts": + bash .github/release/publish.sh {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + # ============================================================================= # Build Matrix — Cross-platform builds with varying optimization levels # ============================================================================= diff --git a/README.md b/README.md index 157f7dd..b8c321b 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,10 @@ $ just build-matrix max macos-arm # optimized release Source builds require Rust 1.99.1 or newer. `just build-help` lists the optimization levels and cross-compilation targets. +[Release instructions](docs/src/development/releases.md) cover attested +checksums and archives, binary installation, and tag or manual +publication. + Cross builds use `cargo zigbuild` and require the Rust target, `cargo-zigbuild`, and Zig to be installed; Darwin cross builds also require a macOS SDK. The matrix preserves compiler flags and profile environment overrides. Its diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 37fe6ec..2f55079 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -32,4 +32,5 @@ # Development +- [Releases](./development/releases.md) - [Changelog](./changelog.md) diff --git a/docs/src/development/releases.md b/docs/src/development/releases.md new file mode 100644 index 0000000..e1d5f91 --- /dev/null +++ b/docs/src/development/releases.md @@ -0,0 +1,113 @@ +# Releases + +Version-tag pushes and manual runs publish the same release artifacts. +The tag must match the version in its `Cargo.toml`, and its commit must be +reachable from `main`. Manual runs use the workflow on `main` and select +an existing tag. + +Each release contains archives for these Rust targets: + +| Platform | Target | +| --- | --- | +| Linux x86-64 | `x86_64-unknown-linux-gnu` | +| Linux x86-64, static musl | `x86_64-unknown-linux-musl` | +| Linux ARM64 | `aarch64-unknown-linux-gnu` | +| macOS Intel | `x86_64-apple-darwin` | +| macOS Apple Silicon | `aarch64-apple-darwin` | + +The workflow runs release-profile tests on each target, packages the binary +and license, then runs the extracted binary's version and configuration +checks. GitHub attestations identify the workflow that builds each archive. +The publisher checks those attestations, creates the complete SHA-256 manifest, +and attests the manifest and source metadata. It downloads the +draft release and verifies every asset before making the release public. + +## Release setup + +Create a `release` GitHub environment that allows the `main` branch and +`v*` tags. GitHub signs attestations using the workflow's OpenID Connect +identity. No release signing secret or public-key configuration is required. +Verification trusts GitHub's identity for this repository and release workflow; +attestations do not replace source review or the workflow's source restrictions. + +## Publish a version + +Commit the version and changelog, merge to `main`, then tag that commit: + +```sh +git tag v0.1.0 && git push origin v0.1.0 +``` + +To run manually for an existing tag: + +```sh +gh workflow run release.yml --repo beardedeagle/postmaster \ + --ref main -f tag=v0.1.0 +``` + +The workflow refuses to replace an existing release. If verification leaves +a failed draft, inspect it and remove that draft before retrying. Do not move +a published version tag or overwrite its assets. The workflow marks tags +with a prerelease suffix as prereleases. + +Pull requests exercise source validation, release tooling and all five +builds. They upload preview archives without attesting or publishing +a release. Local recipes are `just release-test` and +`just release-build `; Python 3.11 or newer is required +for the release-tool tests. + +## Verify and install + +Install and authenticate the GitHub CLI, then download, verify and install +the selected archive. Verification accepts this repository's release workflow +on `main` or a version tag, and rejects pull-request and feature-branch +identities. This example selects Apple Silicon. The subshell stops on the +first failed command, before extraction or installation: + +```sh +( + set -eu + version=v0.1.0 + identity='^https://github\.com/beardedeagle/postmaster/\.github/workflows/release\.yml@refs/(heads/main|tags/v[^/]+)$' + archive="postmaster-${version}-aarch64-apple-darwin.tar.gz" + base="https://github.com/beardedeagle/postmaster/releases/download/${version}" + curl --fail --location --remote-name "$base/$archive" + curl --fail --location --remote-name "$base/SHA256SUMS" + gh attestation verify SHA256SUMS --repo beardedeagle/postmaster \ + --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --cert-identity-regex "$identity" \ + --deny-self-hosted-runners + awk -v file="$archive" '$2 == file { print }' SHA256SUMS > selected.sha256 + test "$(wc -l < selected.sha256 | tr -d ' ')" = 1 + shasum -a 256 -c selected.sha256 + gh attestation verify "$archive" --repo beardedeagle/postmaster \ + --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --cert-identity-regex "$identity" \ + --deny-self-hosted-runners + tar -xzf "$archive" postmaster LICENSE + mkdir -p "$HOME/.local/bin" + install -m 0755 postmaster "$HOME/.local/bin/postmaster" +) +``` + +`release.json` records the tagged source commit and complete target set. +Its checksum is covered by the same attested manifest. A manual run's +attestation identifies its triggering `main` revision; `release.json` +identifies the selected tagged source revision. + +macOS binaries have no Apple Developer ID signature or notarization. +Attestations provide release authenticity and build provenance; they do not +satisfy Gatekeeper. `curl` downloads and local builds generally +avoid browser-applied quarantine. Browser downloads can still prompt or be +blocked. The workflow does not disable Gatekeeper or remove quarantine. + +To build locally instead: + +```sh +( + set -eu + cargo build --locked --release + mkdir -p "$HOME/.local/bin" + install -m 0755 target/release/postmaster "$HOME/.local/bin/postmaster" +) +```