SecurityReleasesDevOps

Practical Guide to Digital Signing for Open-Source Projects and Archives

UUnknown

2026-02-18

9 min read

Stop relying on a single CDN — learn how to sign releases with GPG, minisign & cosign so users can verify integrity even offline.

When CDNs fail: make your releases verifiable anywhere

Outage, mirror takedown, or a throttled CDN — they all turn file distribution into a trust problem. If you publish open-source releases or archives, users and operators must be able to validate integrity and provenance even when primary hosting is unavailable. This guide gives pragmatic, end-to-end steps (with commands and automation patterns) to sign releases using GPG, minisign, and cosign so downloads remain verifiable in 2026 and beyond.

Why multi-tool signing matters in 2026

Supply-chain security and offline verification are front and center in 2026. Key trends that affect signing strategy:

Keyless / transparency logs (Sigstore / cosign) are widely adopted in CI and cloud-native distribution pipelines.
Legacy OpenPGP (GPG) remains the most interoperable option for archive consumers and package maintainers who need offline verification or hardware-backed keys (YubiKey, smartcards).
Compact, modern signatures (minisign / signify-style) are popular for small artifacts and automated downloads because they’re easy to embed, fast to verify, and safe against accidental canonicalization issues.
Outage events and geopolitical disruptions in late 2025/early 2026 highlighted the need to publish multiple signature formats alongside a release so users can verify with whatever tool they have available.

High-level approach (the inverted pyramid)

Produce deterministic release artifacts (tarballs, zips, container images).
Create checksums (SHA256) and sign both the artifact and the checksum file.
Publish multiple signature formats: GPG (.asc), minisign (.minisig), and cosign (for containers and arbitrary blobs).
Publish/release public keys and short fingerprints in the repo, release notes, and at least two independent channels.
Automate signing inside CI, prefer hardware keys for key custody, and log signatures to transparency logs (when using cosign/keyless).

Practical checklist before you sign

Use a reproducible build process to reduce “file changed” uncertainty.
Decide key custody: HSM/YubiKey for long-lived keys; ephemeral or keyless for CI jobs.
Choose a canonical checksum algorithm: SHA256 (still best balance of security & interoperability in 2026).
Plan signature distribution: GitHub Releases, repository tags, mirrors, and publish fingerprints in plaintext documentation.

Step 1 — Create a release artifact and checksum

Example: package a release tarball and create a SHA256 checksum.

# Create the archive
mkdir -p build && tar -czf build/project-1.2.3.tar.gz src README.md

# Create a deterministic timestamp (optional) and compute checksum
sha256sum build/project-1.2.3.tar.gz | tee build/project-1.2.3.tar.gz.sha256

Tip: Try to ensure deterministic timestamps or use reproducible-build tools; non-determinism makes verification harder.

Step 2 — Sign with GPG (OpenPGP) — the interoperable baseline

Why use GPG?

GPG is universal: package managers, sysadmins, and auditors expect .asc signatures. It supports detach-signed checksums, hardware tokens (YubiKey), and keyservers (if you use them).

Generate a GPG key (interactive)

gpg --full-generate-key
# choose RSA 3072/4096 or EdDSA/Ed25519 for modern security
# set an expiration and a recovery policy

Export public key and fingerprint

# List your key ID (example: ABCD1234)
gpg --list-keys --keyid-format LONG

# Export ASCII-armored public key
gpg --armor --export you@example.com > public-gpg.asc

# Show fingerprint for out-of-band verification
gpg --fingerprint you@example.com

Sign artifact and checksum (detached, ASCII-armored)

# Detached signature for the archive
gpg --armor --detach-sign --output build/project-1.2.3.tar.gz.asc build/project-1.2.3.tar.gz

# Detached signature for the checksum file (recommended)
gpg --armor --detach-sign --output build/project-1.2.3.tar.gz.sha256.asc build/project-1.2.3.tar.gz.sha256

Verify (offline)

# Verify the archive signature (requires public key imported)
gpg --verify build/project-1.2.3.tar.gz.asc build/project-1.2.3.tar.gz

# Verify checksum signature and then the checksum itself
gpg --verify build/project-1.2.3.tar.gz.sha256.asc build/project-1.2.3.tar.gz.sha256
sha256sum -c build/project-1.2.3.tar.gz.sha256

Best practices with GPG:

Keep the private key offline when possible; use a YubiKey or HSM for signing in production.
Sign both the artifact and the checksum file. The checksum allows verification if the signature is detached or missing for some reason.
Publish the public key fingerprint inside your repo README and in at least one independent channel (project website, GitHub profile, or a social account).

Step 3 — Add a minimalist signature: minisign (compact & simple)

Why minisign?

minisign uses Ed25519 and is designed to be simple, easy to audit, and small. It’s ideal for signing single files and for users who want a compact verification flow without OpenPGP complexity.

Generate keys and sign (example)

Install minisign (prebuilt binaries widely available). Commands follow the common minisign pattern:

# Generate keypair
minisign -G -p build/project.pub -s build/project.sec

# Sign the artifact (creates a .minisig file)
minisign -Sm build/project-1.2.3.tar.gz -s build/project.sec

# Verify using the public key
minisign -Vm build/project-1.2.3.tar.gz -p build/project.pub

Notes: minisign's signature file is compact (typically a few dozen bytes) and can be stored side-by-side with the artifact as project.tar.gz.minisig.

Step 4 — Sign with cosign (containers and arbitrary blobs; Sigstore integration)

Why cosign?

cosign is the go-to tool for signing container images and general blobs in cloud-native supply chains. It integrates with Sigstore’s Rekor transparency log and supports both key-pair and keyless (OIDC-backed) signing. In 2025–2026 cosign adoption exploded across GitOps and Kubernetes ecosystems.

Generate a cosign keypair and sign a file

# Generate a key-pair (creates cosign.key and cosign.pub)
cosign generate-key-pair

# Sign an arbitrary file (sign-blob writes signature to stdout)
cosign sign-blob --key cosign.key build/project-1.2.3.tar.gz > build/project-1.2.3.cosign

# Verify blob using the public key
cosign verify-blob --key cosign.pub --signature build/project-1.2.3.cosign build/project-1.2.3.tar.gz

Keyless signing: For CI workflows you can use OIDC-backed, ephemeral identities instead of long-lived keys. Keyless signatures are recorded in Rekor for transparency. Example (CI):

# Example keyless sign (CI must have OIDC token or be authenticated)
COSIGN_EXPERIMENTAL=1 cosign sign-blob --keyless build/project-1.2.3.tar.gz > build/project-1.2.3.cosign

# Verify keyless signature
ecosign verify-blob --keyless --signature build/project-1.2.3.cosign build/project-1.2.3.tar.gz

Note: replace environment and flags with your CI provider's recommended approach; cosign continues to evolve, so check the official docs for exact flags.

Step 5 — Publish keys, signatures, and fingerprints reliably

Signing is only as useful as your ability to publish and verify the signer identity. Publish signatures and keys in multiple places:

Attach .asc, .minisig, and .cosign files to GitHub Releases or your artifact host.
Commit public keys (or fingerprints) in the repository (signed and anchored to a tag).
Publish the GPG key on a keyserver and host an authoritative copy on your project website (for redundancy).
Log cosign keyless signatures to Rekor (transparency log) and include Rekor entries in release metadata; transparency logs are a resilience pattern similar to other distributed logs used for verifiability (see resilient infrastructure patterns).
Post short fingerprints in your README and in an independent channel (social profile, organization website) to prevent MITM/github-supply-chain attacks.

CI/CD automation patterns (GitHub Actions example)

Two common models:

Hardware-backed signing: use a signing machine with an HSM or YubiKey. The CI job triggers a signing process on a controlled runner.
Ephemeral/keyless signing: generate ephemeral signatures in CI (cosign keyless) and use Rekor for transparency.

Minimal GitHub Actions snippets

GPG signing with a private key stored in GitHub Secrets (for small teams):

# steps (simplified)
- name: Import GPG key
  run: |
    echo "$GPG_PRIVATE_KEY" | gpg --import

- name: Sign release artifact
  run: |
    gpg --armor --detach-sign --output artifact.tar.gz.asc artifact.tar.gz

- name: Upload artifact and signature
  uses: actions/upload-release-asset@v1
  with:
    file: artifact.tar.gz
# ... upload the artifact.tar.gz.asc too

Cosign keyless signing in GitHub Actions (recommended for modern pipelines):

# steps (simplified)
- name: Install cosign
  run: curl -LO https://github.com/sigstore/cosign/releases/download/vX.Y.Z/cosign-linux-amd64 && sudo install cosign-linux-amd64 /usr/local/bin/cosign

- name: Sign artifact keyless
  env:
    COSIGN_EXPERIMENTAL: "1"
  run: |
    cosign sign-blob --keyless artifact.tar.gz > artifact.cosign

- name: Upload signature
  uses: actions/upload-artifact@v3
  with:
    name: artifact-signature
    path: artifact.cosign

Verification scenarios (including when CDNs are down)

If the main CDN is unavailable, users can:

Download the artifact from a mirror, peer, or local cache.
Get the signature file from a different channel (GitHub release, git repository, or your project's website).
Import the appropriate public key (GPG, minisign, cosign public key) stored in the repo or displayed in README.
Verify offline — all tools above support offline verification if the public key and signature are available.

Troubleshooting common problems

GPG verification fails with ‘No public key’

Import the project public key: gpg --import public-gpg.asc.
Verify the fingerprint out-of-band (README, website, social) before trusting the key; follow an identity verification playbook like the one in the identity and verification case study.

minisign verification error

Ensure you have the correct public key and that you didn’t strip newlines when copying. Use binary-safe transfers.

cosign verification fails

Check if the signature file corresponds to the exact artifact (hash mismatch if file altered).
If using keyless signatures, verify Rekor entries and OIDC issuance logs from the CI job.

Advanced strategies & future-proofing

Multiple signature layers: Sign both the raw artifact and the checksum, plus add an additional minisign signature for low-friction verification.
Hardware policy: Require HSM/YubiKey for release signing and keep emergency escrow keys inside an HSM vault.
Transparency & attestations: Publish attestation metadata (SLSA-style) alongside releases; cosign + Rekor provide an auditable trail preferred by many organizations in 2025–2026.
Mirror strategy: Push artifacts and signatures to at least two independent hosts; treat signatures as first-class artifacts and consider cross-platform release workflows described in cross-platform content flow playbooks.
Reproducible builds: The most robust verification requires reproducible build techniques so users can rebuild and compare artifact hashes.

Real-world example — end-to-end (GPG + minisign + cosign)

Summary workflow for project-1.2.3:

Build deterministic archive: project-1.2.3.tar.gz
Compute checksum: sha256sum ... > project-1.2.3.sha256
GPG sign both archive and checksum: creates .asc files
minisign sign the archive: creates .minisig
cosign sign-blob and log in Rekor: creates .cosign
Publish artifact + all signature files + public keys + fingerprints in README and GitHub Release

Checklist for release engineers (quick reference)

[ ] Deterministic build produced
[ ] SHA256 checksum created
[ ] GPG detached ASCII signatures for artifact & checksum created
[ ] minisign signature created
[ ] cosign signature (key or keyless) created and Rekor entry recorded
[ ] Public keys + fingerprints published in 2 independent places
[ ] CI automates signing and stores secrets in a vault (not in plaintext)
[ ] Emergency key-rotation & revocation process documented

Final notes and 2026 predictions

In 2026, expect the interplay of keyless signatures, transparency logs, and hardware-backed keys to become the standard for high-value open-source projects. Projects that publish multiple signature formats and make verification frictionless will see fewer support requests and higher adoption because users can verify integrity without relying on a single CDN or hosting provider.

Practical takeaway: Don’t rely on a single signing format. Publish GPG, minisign, and cosign signatures — automate them in CI and publish public keys and fingerprints in multiple trusted places.

Call to action

Start today: add GPG, minisign, and cosign steps to your release pipeline and publish the public key fingerprints in your repo README. If you want a ready-to-drop CI template or a checklist tailored to your project (containers, language-specific packages, or binary releases), download our release-signing templates and signing scripts from the project’s repository or contact our engineering team for a 30-minute walkthrough.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.