# Verify a release

> Check the signature, the checksums, the provenance and the image digests of a published release.

Source: https://alexgalhardo.github.io/vukem-video/docs/self-hosting/verify-a-release/

## You will learn

- what is signed and attested in a release;
- the commands that verify the archive and the image;
- what a failure means.

## The idea

Every release is built by one workflow, `release.yml`, on GitHub. It signs `checksums.txt` with cosign (keyless, through Sigstore), attaches a build provenance attestation, and signs and attests the digests of the container image on both registries. You verify that the file you hold is the one that workflow built from a tag, without trusting the download.

Install `cosign`, the GitHub CLI `gh` and, for the image, `docker`.

## Quick start

Set the version, then download and verify the archive of your platform:

```bash
VERSION=vX.Y.Z
V="${VERSION#v}"
REPO=AlexGalhardo/vukem-video
ARCHIVE="vukem-video_${V}_linux_amd64.tar.gz"
IDENTITY="^https://github[.]com/$REPO/[.]github/workflows/release[.]yml@refs/tags/v"
ISSUER=https://token.actions.githubusercontent.com
gh release download "$VERSION" -R "$REPO" -p checksums.txt -p checksums.txt.sigstore.json \
  -p "$ARCHIVE" -p "$ARCHIVE.sbom.json"
cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
sha256sum --ignore-missing -c checksums.txt
gh attestation verify "$ARCHIVE" -R "$REPO"
```

On macOS use `shasum -a 256 -c` for the check of the checksums. The release also attaches the provenance bundle, `vukem-video.intoto.jsonl`, and a software bill of materials (SBOM) for each archive.

Verify the container image on both registries. The two digests printed must be equal, because one build is pushed to both:

```bash
for image in ghcr.io/alexgalhardo/vukem-video alexgalhardo/vukem-video; do
  digest="$(docker buildx imagetools inspect "$image:$V" --format "{{.Manifest.Digest}}")"
  cosign verify "$image@$digest" \
    --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
  echo "$image $digest"
done
docker run --rm "ghcr.io/alexgalhardo/vukem-video:$V" version
```

The last command prints `vukem-video vX.Y.Z`. The Windows and macOS installers are not signed with a paid code-signing certificate; the signed `checksums.txt` is how you verify them.

## The BETA installers are not signed

The BETA has no paid code signing: no Apple Developer ID or notarization, and no Windows code-signing certificate. This covers the installers of the local server and the installers of the [desktop application](/docs/guide/desktop) (`vukem-video-desktop_X.Y.Z_windows_amd64_setup.exe`, `..._darwin_arm64.dmg`, `..._darwin_amd64.dmg` and `..._linux_amd64.deb`). Paid signing is decided again before 1.0. Until then the proof that a file is the one the project built is the signature of `checksums.txt` and the attestation of the file, and your system warns before it runs the file:

- **Windows SmartScreen** shows "Windows protected your PC". Choose **More info**, then **Run anyway**. The publisher shows as unknown because there is no certificate.
- **macOS Gatekeeper** says the app or package cannot be opened because Apple cannot check it. Control-click (right-click) it, choose **Open**, then **Open** again; or run `xattr -d com.apple.quarantine <path of the file or app>`.

A warning is not a verdict, and a missing warning is not proof. Verify the file first; the checks below do not depend on what the system says.

Download the installer and run, with the version and the file name of your system:

```bash
FILE="vukem-video-desktop_${V}_windows_amd64_setup.exe"
gh release download "$VERSION" -R "$REPO" -p "$FILE"
bash scripts/desktop-verify.sh "$VERSION" "$FILE"
```

`scripts/desktop-verify.sh` is in the repository (clone it, or download it from the tag). It downloads `checksums.txt` and its signature, verifies the signature with cosign, checks that the SHA-256 of your file equals its line of `checksums.txt`, and runs `gh attestation verify` on the file. It uses neither `codesign` nor `signtool`, because there is no code signature to check. Without the script, do the same by hand with the commands of the quick start, using `$FILE` where they use `$ARCHIVE`.

### The update feed

The desktop application can look for a newer version, but only when you turn it on: the setting `update.check` is off by default and the application then opens no connection. It reads one signed file, `feed.json`, from the GitHub Pages site of the project (`<site>/updates/feed.json`), and the installers it lists come from the same address. The feed and each installer are signed with an Ed25519 key whose public half is built into the application; a file that does not match its signature or its digest is refused. The release also attaches `feed.json`, and `bash scripts/release-verify.sh vX.Y.Z` checks that every digest in it equals `checksums.txt`.

## Common mistakes

- Skipping `cosign verify-blob` and running only `sha256sum`: a checksum file you did not verify proves nothing.
- Changing the identity regexp to accept any workflow. Keep it exact: the identity is the proof of who built the file.
- A recovery run signed from a branch instead of a tag has the identity `@refs/heads/<branch>`; the regexp above rejects it on purpose. Use the next tagged release.

## Next steps

- [Run the Docker image](/docs/self-hosting/docker)
- [The release process](/docs/contributing/releases)
