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 +`