Download API and GitHub releases produce different binaries for the same version (undocumented build tag divergence)

[rramphal]

Issue Details

Summary

For the same Caddy version (v2.11.4), binaries from the download API (caddyserver.com/api/download) and GitHub releases use different build tags, producing structurally different binaries. This is undocumented and prevents users from cross-verifying download API binaries against published GitHub release checksums.

Reproduction

# Download stock binary from GitHub releases
curl -sL -o caddy_github.tar.gz \
  "https://github.com/caddyserver/caddy/releases/download/v2.11.4/caddy_2.11.4_linux_amd64.tar.gz"
tar -xzf caddy_github.tar.gz caddy
mv caddy caddy_github

# Download stock binary from download API (no extra modules)
curl -s -o caddy_api \
  "https://caddyserver.com/api/download?os=linux&arch=amd64&version=v2.11.4"
chmod +x caddy_api

# Compare
ls -la caddy_github caddy_api
# caddy_github: 48,521,378 bytes
# caddy_api:    52,293,794 bytes

sha512sum caddy_github caddy_api
# caddy_github: 171b57a6b36ac03d88d427dc663af364345fd2b1d96367ee0786c8d8100dc55211b6a50707319419a5fd2da758436da8299ad70391ddd7f90543619e36d2f820
# caddy_api:    aece2434e42582dfa3fab49bb66e294a66b82603166e5829c56d7c6e6f1d000cf81f93aead8e2437219b38a9475864a0b1ed06347eea1d96ef0a4f39181a7164

Root cause

The two distribution channels use different build tags:

Channel	Build tags
GitHub releases (.goreleaser.yml)	nobadger,nomysql,nopgx
Download API	nobadger

Verified via caddy build-info — both binaries report the same Go version (go1.26.3), same 134 modules, same Caddy version hash. The only difference is the build tags. The download API binary includes MySQL and PostgreSQL drivers that GitHub releases strip out.

Why this matters

Users who pin binary checksums for supply-chain security (e.g., verifying downloads in automated provisioning scripts) cannot cross-reference download API binaries against the SHA-512 checksums published in GitHub releases. The two official distribution channels are effectively independent trust roots with no way to verify one against the other.

This is particularly relevant for users of the download API who add modules — since the download API publishes no checksums at all, there is no published integrity reference for custom builds. Being able to at least verify the stock build across sources would provide a trust anchor.

Related issues

This extends several earlier requests:

• Reproducible builds caddy#709 — Reproducible builds: requested checksums and library version transparency for pre-built binaries
• Cryptographic Signatures for Releases? caddy#936 — Cryptographic signatures for releases: requested GPG-signed releases for verification in deployment scripts
• Allow pinning of downloads/downloading by hash caddy#992 — Allow pinning of downloads by hash: requested bit-exact reproducible downloads from caddyserver.com

These were filed during Caddy v1 (2016) and closed. The situation has improved since then — GitHub releases now include a checksums file and cosign signatures. However, the download API still has no integrity verification mechanism, and the build tag divergence documented here is a new finding.

Possible resolutions (any would help)

1. Align build tags between goreleaser and the download API so stock binaries are identical across both channels
2. Document the divergence if it's intentional, so users know not to expect matching binaries
3. Publish checksums for download API builds (even if they differ from GitHub releases), so users have a published reference for custom builds

Thank you!

Assistance Disclosure

AI used

If AI was used, describe the extent to which it was used.

I used Claude Code to research and test and to draft this issue

[mohammed90]

It's not an API, and we discourage using it as an API. Don't use it that way.

If you have access to the GitHub release's assets, why would you download one from the download page endpoint? What's the advantage?

[rramphal]

Thank you for the quick response! Apologies for calling it an API in the issue title - it was just my description.

The reason I can't use GitHub release assets is that I need a build with a module (caddy-ratelimit) — GitHub releases are stock-only, with no checksums for module builds. As far as I could tell, the download page is the only way to get a module-included binary without installing Go + xcaddy on the target machine.

This is the core issue:

This is particularly relevant for users of the download API who add modules — since the download API download page publishes no checksums at all, there is no published integrity reference for custom builds. Being able to at least verify the stock build across sources would provide a trust anchor.

Could you point me to where programmatic use of the download page is discouraged? I couldn't find any mention of this in the install or build docs — it's presented as a standard distribution channel alongside GitHub releases and xcaddy.

Unless I'm mistaken, GitHub has neither builds with modules nor checksums for them, right? Regardless, even if publishing checksums for every possible combination is unfeasible, I think these two points still stand independently:

1. Align build tags between goreleaser and the download API download page so stock binaries are identical across both channels
2. Document the divergence if it's intentional, so users know not to expect matching binaries

Could you help me understand why different build tags are used at all? If the team decides no change is needed, this issue at least documents the divergence for others who run into it.

Thank you!

[mholt]

Thanks, I think we did update the build tags in CI multiple times but not the build server. I am currently rewriting the download page backend so I will take this into consideration and try to get identical builds.