Install
Markdown
Ask AI
Share

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.

Markdown
Ask AI
Share

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:

ArtifactHow 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.jsoncosign verify-blob, then sha256sum --check
Release binaries, with a GitHub build provenance attestationgh attestation verify
Container images levelrail and levelrail-agent, manifest list digest signed with cosigncosign 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.

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.

Next steps

Keep reading

Install the CLI with npm or Homebrew Install the CLI with npm or Homebrew

tutorial 3 min read

Install the Levelrail CLI: npm, Homebrew or a Binary

Three ways to install levelrail-cli: npm or a runner like npx, the Homebrew tap, or a release binary for macOS, Linux and Windows. It is a client only.

  • Self-hosting
  • DevOps
  • Tutorial
Your own cloud, managed as code Your own cloud, managed as code

tutorial 4 min read

Manage a Self-Hosted PaaS with Terraform or OpenTofu

Use the Levelrail provider from the Terraform or OpenTofu registry to manage projects, apps, domains and databases as code, with import and the gaps.

  • Self-hosting
  • DevOps
  • Terraform