Skip to content
SafePass
Русский

SafePass Release Process

This document describes the tag-based release workflow, artifact packaging, integrity verification, and supply-chain guarantees for SafePass.

Overview

SafePass releases are published as GitHub Draft Releases created automatically by .github/workflows/release.yml. Draft status allows the team to inspect built artifacts, check release notes, and conduct final manual review before making the release public.

Release Triggers

The release workflow is triggered by:

  • Pushing a version tag: git push origin v0.1.0 (matching v*.*.* or v*.*.*-*)
  • Manual trigger via Actions → SafePass draft release → Run workflow (workflow_dispatch). Select the source ref and provide an existing version tag that points to the same commit.

The workflow checks the tag before building and checks it again before creating the release. Protect release tags from movement and deletion: these checks do not lock a tag during the workflow or provide a signed provenance attestation.

Release Artifacts

The workflow packages the following artifacts and publishes SHA-256 checksums. Platform signing and signed provenance are not yet configured:

Platform / Target Artifact Name Description
Linux (Desktop) safepass-<version>-linux-x64.tar.gz Flutter release client bundle for Linux desktop (x64)
Windows (Desktop) safepass-<version>-windows-x64.zip Flutter release client bundle for Windows desktop (x64)
macOS (Desktop) safepass-<version>-macos-universal.zip Flutter universal application bundle (.app) for Apple Silicon and Intel
Android safepass-<version>-android.apk Release APK for Android devices
Chromium Extension safepass-<version>-browser-chromium.zip Manifest V3 browser extension for Google Chrome, Brave, Chromium
Firefox Extension safepass-<version>-browser-firefox.zip Manifest V3 browser extension for Mozilla Firefox
Native Messaging Host safepass-<version>-native-host-linux-x64.tar.gzsafepass-<version>-native-host-windows-x64.zip Optional native host executable and registration installer
ASP.NET Core API safepass-<version>-api-linux-x64.tar.gz Production build of the SafePass synchronization and OPAQUE API service
SPDX SBOM dependencies.spdx.json SPDX 2.3 software bill of materials covering Cargo, npm, pub, and NuGet dependencies
Vulnerability Report osv-results.json OSV-Scanner dependency vulnerability audit report
License Report license-report.csv Full audit report of third-party package licenses against the repository policy
Checksums checksums.sha256 SHA-256 cryptographic digests of all files in the release

Local Packaging (Linux)

You can assemble all Linux-available artifacts and verify release packaging locally without triggering CI:

bash scripts/package-release-artifacts.sh --version 0.1.0-preview

Options:

  • --output-dir <DIR>: directory where archives will be assembled (default: .artifacts/release under the repository root). An explicit relative path is resolved from the directory where the command is invoked.
  • --version <VER>: release tag or version identifier.
  • --skip-build: packages existing compiled outputs without running builds again.
  • --components <LIST>: subsets of components (e.g. linux,extensions,api,supply-chain).

For API packaging with --skip-build, place the existing publish output in .artifacts/api-publish under the repository root. For example, from the root:

dotnet publish services/api/SafePass.Api/SafePass.Api.csproj \
  --configuration Release --output .artifacts/api-publish
bash scripts/package-release-artifacts.sh --version 0.1.0-preview \
  --components api --skip-build

The second command archives that output without invoking dotnet, so it can also run on a packaging machine without the .NET SDK. If the publish directory is missing, API packaging prints a notice and skips that component. Supply-chain report generation is separate from compilation and still runs when selected.

Checksum Verification

Every release includes a checksums.sha256 manifest. To verify downloaded artifacts on Linux or macOS:

sha256sum --check --ignore-missing checksums.sha256

On Windows (PowerShell):

Get-FileHash -Algorithm SHA256 safepass-*-windows-x64.zip

Compare the output hash against the hash listed in checksums.sha256.

Code Signing & Provenance

When platform-specific developer signing credentials (Android keystore, Apple Developer Certificate/Notarization, and Windows Authenticode) are provisioned, signing steps will be linked into their respective build jobs before packaging (see the signing and provenance item in TODO.md).

Until then the Android signing inputs can be checked before a build:

python3 scripts/check-android-release-signing.py --require-keytool

It fails on a missing SAFEPASS_ANDROID_* variable, an unreadable or unsupported keystore, a wrong store or key password, an alias that is not a private-key entry, and a certificate that expires too soon for Google Play (lifetime below 25 years). Passwords reach keytool through the environment, so they never appear in a process list or a build log.

Documentation