Cache the production compile's pages CSS on main

[gianfrancopiana]

What

On a main asset cache miss, the production compile unpacks the pages CSS from a cache instead of building it.

• A new script, .buildkite/scripts/main_pages_tailwind_cache.sh, keys the pages CSS on its build script, its CSS input, lib/tasks/pages_tailwind.rake, the package files, docker/base and docker/web/compile_assets.sh.
• The production path downloads the tarball and verifies its checksum, with the same helpers as the node_modules cache (Cache the production compile's node_modules on main #8311).
• make build_production mounts the tarball into the compile container. docker/web/compile_assets.sh unpacks it and sets PAGES_TAILWIND_RESTORED, so pages_tailwind:build skips the Tailwind build.
• After a build that the cache lacked, the container writes a new tarball of the four output files. Only a main build creates and uploads it.
• comp-assets-* builds read the cache and never write it. Staging and preview builds mount nothing and build as before.
• A [no-cache] commit builds the CSS and replaces the entry.
• The cache directory is removed when the build exits, also after a failed compile.

Why

About half of main deploys miss the main asset cache and compile from scratch. On a miss, the pages Tailwind build takes 73–76 s, although its output never changes with app code: scripts/build_pages_tailwind.mjs builds a fixed class list, and its CSS input sets source(none). PR CI already caches the same files on the same inputs (#8298).

With the node_modules cache, this removes the two steps of a compile miss that do not depend on the change being deployed.

Before/After

This changes the production build only. Nothing changes for users.

• Before: every compile on a cache miss builds the pages CSS (73–76 s).
• After: a compile on a cache miss unpacks the cached pages CSS, unless its inputs changed.

Test results

• bash .buildkite/scripts/main_asset_cache_compile_test.sh: 58 pass. New cases:

  • a verified hit is in place for make, and a tarball that fails its checksum is not used;
  • a main miss saves the tarball and its checksum, and a comp-assets-* miss saves nothing;
  • a [no-cache] commit builds the CSS and replaces the entry;
  • the cache directory is removed after the compile, also when the compile fails.

• The same test runs the real make build_production and the real docker/web/compile_assets.sh against a stub docker, with a real tarball:

  • a mounted tarball is unpacked before assets:precompile, the restored flag skips the build, and nothing is written back;
  • a main build writes the four output files to pages_tailwind.tar.gz.new;
  • a comp-assets-* build creates no archive, and a failed archive write leaves no partial file.

  Each piece of the change, removed on its own, makes at least one case fail.

• bundle exec rspec spec/lib/tasks/pages_tailwind_spec.rb: 2 pass. Without the skip in the rake task, the restored case fails.

• bundle exec rubocop and shellcheck -S warning: no new offenses.

• A real Buildkite production compile of this branch (build 25596, on a comp-assets-* branch, no deploy) passed in 6.2 min:

  • make build_production mounted both cache directories into the compile container;
  • with no tarball there, npm run build:pages-tailwind ran, in 75.9 s;
  • the image pushed as usual, with no tar, gzip, checksum, S3 or Rake error.

  That build cannot test a restore, because only main writes entries. The first main compile after the merge fills the cache, and the next miss restores it. Both log their result.

---

AI disclosure: Claude Opus 5.5.

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge; no actionable issue was found.

Summary

This PR lets production asset builds reuse cached pages CSS instead of rebuilding it.

• Production compiles reuse cached pages CSS when its inputs match.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Production asset cache miss] --> B{no-cache commit?}
  B -->|No| C{Pages CSS archive verifies?}
  B -->|Yes| E[Build pages CSS]
  C -->|Yes| D[Unpack CSS and skip pages build]
  C -->|No| E
  D --> F[Finish assets precompile]
  E --> F
  F --> G{Main built fresh CSS?}
  G -->|Yes| H[Save archive and checksum]
  G -->|No| I[Keep cache unchanged]
  H --> J[Remove local cache directories on exit]
  I --> J

Loading

_{Reviews (1) · Last reviewed commit: "Cache the production compile's pages CSS..." · Reviewed by Greptile}

[gumclaw]

bin/branch-specs escalated this diff (build/docker/cache scripts cannot be mapped to a spec subset), so the push run's Test Relevant step exits with "add the run-all-specs label"; added the label and re-ran the Tests run so it takes the full Fast/Slow suite.