Checksums: What They Are, Why They Matter, and Where They Belong in Your Release Pipeline

Source: Dev.to

When you distribute software—especially binaries—you’re making an implicit promise: this file is exactly what you intended to ship. Checksums are how you keep that promise.

In this article we’ll go through what checksums are, why they matter, and how to add them to your own open source project. Let’s get started!

What is a checksum?

A checksum is a fixed‑length value derived from a file’s contents using a cryptographic hash function. SHA‑256 is the gold standard, so unless you have a specific reason to use another algorithm, stick with SHA‑256. If even a single byte of the file changes, the checksum changes completely. After downloading the file, the checksum can be computed and compared against the advertised value. Thus, a checksum is basically a way of saying “yes, this program is what it claims to be.”

To summarize…

Checksums (in this context) can…

• Detect corruption after downloading a file
• Detect tampering after downloading a file
• Provide confidence to end users

Checksums cannot…

• Prove who created the file
• Protect against malicious servers publishing a tampered file and a matching checksum

A note on package managers

You may wonder whether you’re at risk because of the thousands of npm packages you installed. Nearly all package managers have some safety net that verifies the integrity of the download before installing. Binaries that are not distributed by a package manager (e.g., via GitHub releases) don’t have that built‑in verification, so it’s something to keep in mind.

Adding checksums to your project

Adding checksums to your open‑source project is actually quite simple. Just make sure you put them in the right place or they won’t work.

Build artifacts
↓
Package artifacts (tar.gz, zip, binaries)
↓
Generate checksums
↓
Publish artifacts + checksums
↓
Create release

My current project, Doclific, uses a single file (checksums.txt) containing the checksum, two spaces, then the specific file name:

a21bd2e10abbdb057e8acd91a331b5ff6e187e845031f22d0117927e276d6b4f  doclific-v0.1.1-darwin-amd64.tar.gz
a8c91ead81f402e380293f9a0fa6cf56cf380782dbfdff9bc604548bf14a35da  doclific-v0.1.1-darwin-arm64.tar.gz
499224f4d05f023c560978c6fff2bbb381b7425e742e0b5b3c4b54068d7f6dfb  doclific-v0.1.1-linux-amd64.tar.gz
1913c0669ec383133e8460a0be9df43e285a5ebc39928e62c86fcb6c9b486665  doclific-v0.1.1-linux-arm64.tar.gz

I generate the file in my release.sh script, which runs every time I create a new release:

echo "🔐 Generating checksums"
cd "$DIST_DIR"
shasum -a 256 * > checksums.txt

When the user runs:

curl -fsSL https://raw.githubusercontent.com/muellerluke/doclific/main/scripts/install.sh | bash

the install.sh script pulls the appropriate archive, computes its checksum, and verifies it against the hosted checksums.txt file:

info "Verifying checksum..."

# Determine command
if command -v sha256sum >/dev/null 2>&1; then
    CHECKSUM_CMD="sha256sum -c -"
elif command -v shasum >/dev/null 2>&1; then
    CHECKSUM_CMD="shasum -a 256 -c -"
else
    err "No SHA256 checksum tool found. Please install sha256sum or shasum."
fi

# Run checksum verification
grep "$ARCHIVE" "$CHECKSUM_FILE" | $CHECKSUM_CMD || err "Checksum verification failed"

Note: Some OS versions may not have shasum installed, so the script falls back to sha256sum when necessary.

Closing thoughts

If you’re distributing software via a package manager, you generally don’t have to worry about manual checksum verification. However, when you distribute a binary outside of a package manager—using curl or similar tools—implementing checksums provides an added layer of security and confidence for your end users.