# How to Verify a Levelrail Release: Checksums and Cosign

> Check a Levelrail binary or image by hand: cosign verify-blob on checksums.txt, sha256sum, attestation and image signature, and what each step proves.

Canonical URL: https://levelrail.com/blog/verify-levelrail-release-checksums-cosign/

To verify a Levelrail binary, check the signature on `checksums.txt` with cosign, check your file against that list with `sha256sum`, and optionally confirm the build attestation with `gh`. For container images, run `cosign verify` against the image. Together these show a file came from this repository's release workflow and was not changed on the way to you.

The installer already does the checksum and signature checks for you. Use the manual steps when you want to check by hand, for example before copying a binary onto an air-gapped host. This post follows the [verify a release docs](https://docs.levelrail.com/verify-a-release) and the [install page](https://levelrail.com/install/).

## What a release publishes

Every release is built by one GitHub Actions workflow, `.github/workflows/release.yml`. The docs list what it signs:

| Artifact | How you check it |
| --- | --- |
| `checksums.txt` (SHA-256 of every CLI, agent and control plane binary and the install scripts), signed keyless with cosign, bundle in `checksums.txt.sigstore.json` | `cosign verify-blob`, then `sha256sum --check` |
| Release binaries, with a GitHub build provenance attestation | `gh attestation verify` |
| Container images `levelrail` and `levelrail-agent`, manifest list digest signed with cosign | `cosign verify` |

Signing is keyless, so there is no long-lived key to rotate or lose. Releases cut before signing was added carry no bundle.

## Verify a binary

You need `curl`, `cosign`, `sha256sum` and, for the last step, the GitHub CLI. Set `V` to the release tag you want:

```bash
V=<version>
BASE=https://github.com/glincker/levelrail/releases/download/$V
curl -fsSLO $BASE/checksums.txt -O $BASE/checksums.txt.sigstore.json -O $BASE/levelrail-linux-amd64

cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

sha256sum --check --ignore-missing checksums.txt

gh attestation verify levelrail-linux-amd64 --repo glincker/levelrail
```

## Why each step matters

Run them in order and stop at the first failure. Do not run the binary if one fails.

1. **`cosign verify-blob`** proves `checksums.txt` was signed by the release workflow of this repository. Without this, the checksum list could come from anywhere, including whoever served you the file.
2. **`sha256sum --check`** proves your binary matches a line in that signed list. A checksum alone only shows the download was not corrupted. Combined with step 1 it ties the binary to the signed list.
3. **`gh attestation verify`** proves GitHub recorded a build provenance attestation for the binary from this repository.

On macOS, the install docs use `shasum -a 256 -c -` in place of `sha256sum -c -`.

## Verify a container image

Images use `cosign verify` with the same identity pattern:

```bash
cosign verify ghcr.io/glincker/levelrail:beta \
  --certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

Use `ghcr.io/glincker/levelrail-agent` for the node agent. According to the docs, the Docker Hub mirror (`docker.io/levelrail/levelrail`) carries the same digest, so the same signature verifies there too. Pin an exact `:vX.Y.Z` tag for anything that must not move, because `:latest` and `:beta` change.

BuildKit also attaches an SPDX SBOM and SLSA provenance to each image. The docs read them with `docker buildx imagetools inspect <image> --format '{{ json .SBOM }}'`, and the same with `.Provenance`.

## What the installer and upgrades check

`install.sh` always checks the SHA-256 checksum and refuses to install on a mismatch. It checks the signature when `cosign` is installed and the release has a bundle. `APP_INSTALL_VERIFY` accepts `auto` (the default), `require` and `off`; `require` aborts unless the signature verifies.

`levelrail self-upgrade` and the dashboard upgrade verify the signature inside the server and need no `cosign` binary. After the first verified signature, the host is pinned and refuses unsigned releases. Details are in the [installing docs](https://docs.levelrail.com/installing).

## What this does not prove

The docs are direct about the limits:

- A valid signature says where a file was built. It does not say the code is free of bugs or vulnerabilities.
- It does not cover your own apps or the images you deploy.
- The SBOM and provenance attached to images are not checked by a separate signature command on that page.
- The identity pattern accepts any ref of the release workflow in this repository. Pin an exact tag in the pattern if you need to accept one release only.
- No third-party review of the build pipeline is claimed.

## FAQ

**Does `install.sh` verify releases for me?** It always checks the checksum, and the signature when cosign is present and the release has a bundle.

**Does a valid signature mean the code is safe?** No. It says where the file was built, not that the code is free of bugs.

**Do older releases have signatures?** Releases cut before signing was added have no bundle, so the signature steps do not apply to them.

## Next steps

Read the [verify a release docs](https://docs.levelrail.com/verify-a-release), see the download list on [the install page](https://levelrail.com/install/), or compare where each package is published on [the packages page](https://levelrail.com/packages/). The mirror rules for restricted networks are in the docs under install from mainland China.

## Frequently asked questions

### Does install.sh verify releases for me?

It always checks the SHA-256 checksum. It also checks the cosign signature when cosign is installed and the release has a bundle.

### Does a valid signature mean the code is safe?

No. A valid signature says where a file was built. It does not say the code is free of bugs or vulnerabilities.

### Do older releases have signatures?

Releases cut before signing was added carry no bundle, so the signature steps do not apply to them.
