Skip to content

docs: explain daily binary rebuilds, verification and pinning - #2784

Open
dunglas wants to merge 1 commit into
mainfrom
docs/binary-rebuilds
Open

dunglas wants to merge 1 commit into
mainfrom
docs/binary-rebuilds

Conversation

@dunglas

@dunglas dunglas commented Oct 26, 2026

Copy link
Copy Markdown
Member

The binaries attached to the latest release are rebuilt every day and replaced under the same names, so their checksums change. The docs didn't say so, and users asking for immutable release assets found out when a pinned checksum broke.

This adds a "Standalone binary updates" section to the production docs covering:

  • the rebuild schedule, and the fact that older releases are never rebuilt
  • frankenphp version to see which PHP version a binary contains
  • gh attestation verify to check a binary's provenance whatever the day it was downloaded
  • pinning: keep a verified copy, or use Docker images by digest

The README and the Docker image update section link to it. Versioned, immutable assets can come later, once static-php-cli publishes v3 tags we can pin.

Comment thread docs/production.md
## Standalone binary updates

To ship PHP and library security fixes without waiting for a new FrankenPHP release, the binaries attached to the latest release are rebuilt every day
(at midnight UTC for Linux and macOS, at 8 am UTC for Windows) and replace the previous ones under the same name.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we just rebuild them at the same time?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure, in the past we hit various rate limits with too much paralell builds. IMHO it's safer like this, but to be tested.

Anyway, we can change that later.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single Windows build isn't going to change rate limits considering the amount of linux + macos builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would propose we switch the windows build to 0 and make this less confusing. There's nothing I can imagine going wrong.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We sometimes hit the rate limit of php.net CDN, docker.io and other hidden dependencies. TBH I would prefer to keep it as is for now as it's working.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, a bit confusing from user perspective I would guess, but we can play it safe for now.

LoriKarikari added a commit to LoriKarikari/wolkpack that referenced this pull request Oct 26, 2026
## Problem

All PHP builds on `main` fail with `digest mismatch` when downloading
FrankenPHP. The pinned checksums from #21 no longer match the v1.13.3
release binaries.

## Cause

FrankenPHP's `static.yaml` workflow rebuilds the binaries of its
**latest** release every night at 00:00 UTC, and replaces them under the
same names. Their open PR php/frankenphp#2784 documents this. v1.13.3
was the latest release when #21 pinned it, so its checksums changed
every day. That's also why #21 needed a second checksum fix.

## Change

- `frankenphpBuilds` in `pack/php.go` pins the current v1.13.3 binaries.
- FrankenPHP released v1.13.4 today. Per their docs, older releases are
never rebuilt, so v1.13.3's binaries should no longer change.
- The comment now says to pin only a release that already has a newer
one, and to verify a new pin with `gh attestation verify --repo
php/frankenphp`.

## Out of scope

- **Upgrading to v1.13.4.** It's the latest release, so it would hit the
same nightly rebuilds.
- **A copy of the binary we host ourselves.** That waits until the repo
is public.

## Proof

- Command: `just test php-plain php-laravel php-missing-ext`
- Before: all three fail with `digest mismatch sha256:f88db997...`.
- After: all three pass.
- `gh attestation verify --repo php/frankenphp` passes for both
binaries. Their certificates name
`.github/workflows/static.yaml@refs/heads/main`, triggered by
`schedule`. A made-up file fails the same check.
- The x86_64 binary reports `FrankenPHP v1.13.3 PHP 8.5.12 Caddy
v2.11.7`.
- `just lint` passes.
- **Still open.** I'll check tomorrow that the hashes held. "Older
releases are never rebuilt" comes from FrankenPHP's docs PR, not from my
own observation yet.
- Test app added or updated: none.

## AI use

Written with Claude Code. Review the diff before merging.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants