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 and the install page.
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:
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/levelrailWhy each step matters#
Run them in order and stop at the first failure. Do not run the binary if one fails.
cosign verify-blobproveschecksums.txtwas signed by the release workflow of this repository. Without this, the checksum list could come from anywhere, including whoever served you the file.sha256sum --checkproves 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.gh attestation verifyproves 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:
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.comUse 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.
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, see the download list on the install page, or compare where each package is published on the packages page. 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.