Skip to content

[P0] Add SHA-256 checksums and GitHub artifact attestations to release assets #1469

@shm11C3

Description

@shm11C3

Why

Windows Authenticode signing is still pending, and Linux artifacts are currently unsigned.
Until platform-specific signing is fully available, users need a reliable way to verify that a downloaded artifact is the exact file produced by this repository's release workflow.
Winget is also an official Windows installation path, so the release checksum data should be usable to populate or verify the Winget InstallerSha256 value for Windows installer assets.

This issue adds two verification layers:

  • SHA-256 checksums for all release assets
  • GitHub Artifact Attestations for release artifacts

Scope

Add checksum generation and artifact attestations to the release workflow.

This should cover all distributable release assets, including:

  • Windows installers
  • Windows installer assets used by Winget, where applicable
  • macOS artifacts
  • Linux AppImage
  • Linux .deb
  • Linux .rpm
  • Tauri updater signature files, where applicable

Do not include SHA256SUMS.txt itself in its own checksum list.
Winget should remain a distribution/install channel, not a replacement for Authenticode signing, checksums, or attestations.

Tasks

  • Identify the release workflow that builds and uploads GitHub Release assets.
  • Generate SHA256SUMS.txt after all release assets are built.
  • Sort the checksum list by filename for stable output.
  • Upload SHA256SUMS.txt as a GitHub Release asset.
  • Add GitHub Artifact Attestations for all distributable release assets.
  • Add attestations for SHA256SUMS.txt.
  • Ensure release assets are attached before publishing the immutable release.
  • Make SHA256SUMS.txt the canonical checksum source for documentation, website metadata, and Winget manifest updates.
  • For Windows release assets published through Winget, ensure the generated SHA-256 value can be used to verify the Winget InstallerSha256 value.
  • Add a CI check that fails the release if a distributable asset has no checksum.
  • Add a CI check that fails the release if attestation generation fails.

Suggested implementation

Example checksum step:

cd dist
find . -maxdepth 1 -type f ! -name 'SHA256SUMS.txt' -print0 \
  | sort -z \
  | xargs -0 sha256sum > SHA256SUMS.txt

Example attestation permissions:

permissions:
  contents: read
  id-token: write
  attestations: write

If the same job also creates or updates a GitHub Release, keep the required contents: write permission for that job.

Example attestation step:

- name: Generate artifact attestations
  uses: actions/attest@v4
  with:
    subject-path: |
      dist/*.exe
      dist/*.msi
      dist/*.dmg
      dist/*.AppImage
      dist/*.deb
      dist/*.rpm
      dist/*.sig
      dist/SHA256SUMS.txt

Adjust the glob patterns to match the actual release output paths.

User-facing verification commands

These commands should work after this issue is complete.

Windows:

Get-FileHash .\HardwareVisualizer_1.8.0_x64_en-US.msi -Algorithm SHA256

macOS:

shasum -a 256 HardwareVisualizer_1.8.0_aarch64.dmg

Linux:

sha256sum hardware-visualizer_1.8.0_amd64.deb

GitHub attestation:

gh attestation verify ./HardwareVisualizer_1.8.0_x64_en-US.msi \
  -R shm11C3/HardwareVisualizer

Acceptance criteria

  • Every published release includes SHA256SUMS.txt.
  • Every distributable release asset is listed in SHA256SUMS.txt.
  • SHA256SUMS.txt is attached to the GitHub Release.
  • GitHub Artifact Attestations are generated for release assets.
  • gh attestation verify succeeds for at least one asset from each supported OS.
  • Windows checksum output can be used to populate or verify the Winget InstallerSha256 value.
  • The release process does not publish an immutable release before all assets are attached.
  • The official website can consume or link to the checksum data.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P0cireleaseRelease process and distributionsecuritysupply-chainSupply chain security and provenance

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions