Distribution

Open Sesame uses semantic-release for automated versioning, GitHub Actions for building, SLSA attestations for supply chain security, and GitHub Pages for hosting an APT repository alongside documentation.

Semantic Release

Version management is configured in release.config.mjs. Semantic-release runs on pushes to main and analyzes conventional commits to determine version bumps.

Release Rules

Plugin Pipeline

The semantic-release plugin chain executes in order:

1. @semantic-release/commit-analyzer – Analyzes commits using the conventionalcommits preset to determine the version bump type.
2. @semantic-release/exec – Generates a release header from .github/templates/RELEASE_HEADER.md.
3. @semantic-release/release-notes-generator – Generates release notes from commits, categorized by type.
4. @semantic-release/changelog – Updates CHANGELOG.md.
5. @semantic-release/exec – Updates the [workspace.package] version in Cargo.toml using sed, then runs cargo generate-lockfile to update Cargo.lock.
6. @semantic-release/git – Commits CHANGELOG.md, Cargo.toml, and Cargo.lock with message chore(release): <version> [skip ci].
7. @semantic-release/github – Creates the GitHub release.

Release Pipeline DAG

The release workflow (release.yml) runs on pushes to main and defines the following job dependency graph:

semantic-release
├── build (amd64)       ─┬──► attest
├── build (arm64)       ─┤
│                        └──► upload-assets
├── nix-cache
├── build-docs
│
└── [all above] ────────────► publish ──► cleanup

All downstream jobs gate on needs.semantic-release.outputs.new_release == 'true'. If semantic-release determines no version bump is needed, the pipeline stops after the first job.

Job Details

semantic-release: Checks out with fetch-depth: 0, installs Node.js via mise, runs npx semantic-release. Outputs new_release, version, and tag.

build: Runs on a dual-architecture matrix (ubuntu-24.04 for amd64, ubuntu-24.04-arm for arm64). Installs Rust and cargo-deb via mise. Raises RLIMIT_MEMLOCK to 256 MiB with prlimit before building (required by ProtectedAlloc). Builds .deb packages via mise tasks (ci:build:deb / ci:build:deb:arm64), renames them with architecture suffixes, and uploads as artifacts.

nix-cache: Calls the reusable nix.yml workflow with the release tag. Builds both open-sesame and open-sesame-desktop for each architecture and pushes to Cachix.

build-docs: Builds rustdoc and mdBook documentation via mise run ci:docs:all and mise run ci:docs:combine, then uploads as an artifact.

attest: Downloads all .deb artifacts and generates SLSA build provenance attestations using actions/attest-build-provenance@v2.

upload-assets: Downloads .deb artifacts, generates SHA256SUMS.txt, renders install instructions from a template with per-architecture checksums, and uploads all .deb files and checksums to the GitHub release using softprops/action-gh-release@v2.

publish: Downloads .deb artifacts and documentation, imports the GPG signing key, generates the APT repository via mise run ci:release:apt-repo, and deploys the combined APT repository and documentation site to GitHub Pages.

cleanup: Deletes old releases, keeping the 10 most recent. Uses dev-drprasad/delete-older-releases@v0.3.4. Tags are preserved.

APT Repository

The APT repository is hosted on GitHub Pages and generated by the ci:release:apt-repo mise task during the publish job. The process:

1. Downloads all .deb artifacts into a packages/ directory.
2. Imports the GPG private key (GPG_PRIVATE_KEY secret) using crazy-max/ghaction-import-gpg@v6.
3. Generates the Packages index and signs the repository with GPG.
4. Combines the APT repository with the documentation site into a single gh-pages/ directory.
5. Deploys to GitHub Pages using actions/deploy-pages@v5.

The publish job runs in the github-pages environment and requires pages: write and id-token: write permissions.

SLSA Build Provenance

Every .deb artifact receives a SLSA build provenance attestation generated by actions/attest-build-provenance@v2. This runs in the attest job after the build completes. The workflow declares attestations: write permission at the top level.

Attestations provide a cryptographic link between each .deb file and its GitHub Actions build, allowing consumers to verify that artifacts were produced by the CI pipeline and not tampered with.

Checksum Verification

The upload-assets job generates SHA256SUMS.txt containing SHA-256 hashes for all .deb files:

sha256sum ./*.deb > SHA256SUMS.txt

The checksums file is uploaded alongside the .deb files to the GitHub release. Per-architecture checksums are also interpolated into the release body template for inline verification instructions.

Workflow Permissions

The release workflow requests the following permissions: