From c06b028c1f4f99cc66330280e15c66c9c2fc2217 Mon Sep 17 00:00:00 2001 From: amjjbonvin Date: Tue, 29 Sep 2026 17:02:22 +0200 Subject: [PATCH] Build the site with the pinned Jekyll instead of github-pages Both workflows used actions/jekyll-build-pages, which ships its own github-pages gem set and ignores this repository's Gemfile. The published site was therefore built with Jekyll 3.10.0 while local previews used the Jekyll 4.4.1 pinned in Gemfile.lock, and CI warned "github-pages can't satisfy your Gemfile's dependencies" on every run. Replace it with ruby/setup-ruby + `bundle exec jekyll build` in both jekyll-gh-pages.yml and build.yml, so Gemfile.lock governs the published site and a green buildability check predicts a green deploy. Add .ruby-version (3.4.5) as the single source of truth for the Ruby version, read by both workflows. Fix a regression this exposed: _layouts/home.html listed recent news via site.categories.news, whose ordering Jekyll 4 does not guarantee to match Jekyll 3, so the homepage showed 2014 items instead of current ones. Sort explicitly with `| sort: 'date' | reverse`, which behaves the same on both engines. The /news/ index (site.posts) and site.related_posts were not affected. Verified against the live Jekyll 3 site over a 24-page random sample built with TZ=UTC to match the runners: 21 byte-identical, 3 differing only by blank lines that Jekyll 3 emits and Jekyll 4 does not. Also drop the unused pages/id-token permissions from build.yml, which only builds, and exclude UPGRADE.md from the generated site. Co-Authored-By: Claude Opus 5 --- .github/workflows/build.yml | 17 +++--- .github/workflows/jekyll-gh-pages.yml | 27 +++++++--- .ruby-version | 1 + UPGRADE.md | 77 ++++++++++++++++++--------- _config.yml | 2 +- _layouts/home.html | 5 +- 6 files changed, 90 insertions(+), 39 deletions(-) create mode 100644 .ruby-version diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 03323295..6c011dee 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,3 +1,5 @@ +# Buildability check. Uses the same toolchain as the deploy workflow so that a +# green check here actually predicts a green deploy. name: check if site is buildable on: @@ -6,8 +8,6 @@ on: permissions: contents: read - pages: write - id-token: write jobs: build: @@ -16,8 +16,13 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1.0.13 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 with: - source: ./ - destination: ./_site + ruby-version: .ruby-version + bundler-cache: true + + - name: Build with Jekyll + run: bundle exec jekyll build --destination ./_site + env: + JEKYLL_ENV: production diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 86055bea..e8f04166 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -1,5 +1,7 @@ -# Sample workflow for building and deploying a Jekyll site to GitHub Pages -name: Deploy Jekyll with GitHub Pages dependencies preinstalled +# Build the site with the Jekyll version pinned in Gemfile.lock (currently +# Jekyll 4.x) rather than with actions/jekyll-build-pages, which ships its own +# github-pages gem set (Jekyll 3.x) and ignores this repository's Gemfile. +name: Deploy Jekyll site to Pages on: # Runs on pushes targeting the default branch @@ -28,13 +30,26 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: .ruby-version + bundler-cache: true + - name: Setup Pages + id: pages uses: actions/configure-pages@v4 + + # NOTE: the site is served from a custom apex domain (see CNAME), so + # baseurl stays "" as set in _config.yml. Deliberately do not pass + # steps.pages.outputs.base_path here -- doing so would prefix every URL + # with a repository subpath and break the published links. - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1.0.13 - with: - source: ./ - destination: ./_site + run: bundle exec jekyll build --destination ./_site + env: + JEKYLL_ENV: production + - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 00000000..4f5e6973 --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +3.4.5 diff --git a/UPGRADE.md b/UPGRADE.md index 09cf3e06..ce55cd66 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -18,12 +18,12 @@ which Jekyll are in use. Nothing in the repo arbitrates (there is still no | Where | Ruby | Jekyll | | --- | --- | --- | | Local workstation | 3.4.5 | 4.4.1 | -| CI build container (`actions/jekyll-build-pages@v1.0.13`) | 3.3 | 3.10.0 (github-pages 232) | -| Required by `Gemfile.lock` | >= 3.1 | — | +| CI (`ruby/setup-ruby` + `bundle exec jekyll build`) | 3.4.5 (from `.ruby-version`) | 4.4.1 (from `Gemfile.lock`) | -Both ends have now been moved up (local 3.0.7 -> 3.4.5, CI 2.7.4 -> 3.3), so the -Ruby gap is down from three majors to one and both are supported releases. The -**Jekyll** gap remains and is the real outstanding risk — see item 3. +**Resolved.** Local and CI now run the same Ruby and the same Jekyll, both driven +by files in this repository. `Gemfile.lock` governs the published site, so the +dependency pins and Dependabot alerts apply to production rather than to local +development only. Items 1-3 below record how this was reached. --- @@ -40,8 +40,10 @@ it received nothing automatically. Upgrading moved the build container from - [x] Update the pin in `.github/workflows/jekyll-gh-pages.yml` - [ ] Spot-check a few rendered pages on the live site after the deploy -This narrows but does not close the local/CI gap: `github-pages` has never -shipped Jekyll 4, so local 4.x vs deployed 3.x remains (item 3). +This narrowed but did not close the local/CI gap: `github-pages` has never +shipped Jekyll 4. **Superseded by item 3**, which removes +`actions/jekyll-build-pages` from both workflows entirely; the bump is recorded +here because it was the intermediate step that shipped first. ### 2. Upgrade local Ruby and pin it — MOSTLY DONE @@ -59,26 +61,48 @@ byte-identical. - [x] Install a supported Ruby locally (3.4.5) - [x] `bundle install` and confirm `Gemfile.lock` matches HEAD afterwards -- [ ] Add a `.ruby-version` file so the version is recorded in-repo rather than - living only on one workstation +- [x] Add a `.ruby-version` file so the version is recorded in-repo rather than + living only on one workstation (3.4.5; both workflows now read it) - [ ] Retire `check-gemfile.sh` now that the churn is gone -### 3. Decide how to handle the local/CI Jekyll split - -Local previews render with **Jekyll 4.4.1**; the published site is built with -**3.9.3**. Supporting divergences: kramdown 2.5.1 vs 2.3.2, and `sass-embedded` -vs `sassc` compiling the `style: compressed` SCSS. - -CI has been emitting `github-pages can't satisfy your Gemfile's dependencies` on -every run for a long time (confirmed present on runs predating this audit). Both -engines currently build successfully, so this is a silent-divergence risk rather -than a live breakage. - -- [ ] Choose a direction: accept the gap, align local to `github-pages`, or move - deploys to a custom Jekyll 4 workflow (`ruby/setup-ruby` + `bundle exec - jekyll build`) that actually honours `Gemfile.lock` -- [ ] Whichever is chosen, make the CI warning either resolved or explicitly - acknowledged +### 3. Resolve the local/CI Jekyll split — DONE + +Local previews rendered with **Jekyll 4.4.1** while the published site was built +with **3.10.0** (github-pages 232), with kramdown 2.5.1 vs 2.3.2 and +`sass-embedded` vs `sassc` behind it. CI emitted `github-pages can't satisfy your +Gemfile's dependencies` on every run. + +**Direction chosen:** move both workflows off `actions/jekyll-build-pages` to +`ruby/setup-ruby` + `bundle exec jekyll build`. This is the only option that +makes `Gemfile.lock` govern the published site — and therefore the only one under +which the Dependabot alerts fixed in `6e817a9` mean anything for production. It +is also what GitHub's own warning now recommends. + +- [x] Move `jekyll-gh-pages.yml` to a native Jekyll 4 build +- [x] Move `build.yml` to the same toolchain, so a green check predicts a green + deploy +- [x] Resolve the `github-pages can't satisfy your Gemfile's dependencies` warning + +**Regression found and fixed during the migration.** `_layouts/home.html` listed +recent news via `site.categories.news`, whose ordering Jekyll 4 does not +guarantee to match Jekyll 3. Under Jekyll 4 the homepage showed news items from +2014 instead of the current ones. Fixed with an explicit +`| sort: 'date' | reverse`, which behaves identically on both engines. The +`/news/` index was unaffected (it uses `site.posts`), as was `site.related_posts`. + +**Verification.** A 24-page random sample was diffed against the live Jekyll 3 +site: 21 byte-identical, 3 differing only by blank lines that Jekyll 3 emits and +Jekyll 4 does not. The homepage matches to within two blank lines inside an +excerpt. + +Note the comparison must be run with `TZ=UTC` to be meaningful: `_config.yml` +sets no `timezone`, so Jekyll uses the system zone and a local build stamps +`