Skip to content

Build the site with the pinned Jekyll instead of github-pages - #787

Merged
amjjbonvin merged 1 commit into
masterfrom
ci/jekyll4-native-build
Sep 29, 2026
Merged

amjjbonvin merged 1 commit into
masterfrom
ci/jekyll4-native-build

Conversation

@amjjbonvin

Copy link
Copy Markdown
Member

Resolves item 3 of UPGRADE.md.

Problem

Both workflows used actions/jekyll-build-pages, which copies its own
Gemfile (pinning the github-pages gem) into a container and ignores this
repository's. The published site was 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.

Practically, this meant Gemfile.lock governed local development only — so the
Dependabot fixes in 6e817a9 changed no gem in the published build.

Change

Both workflows now use ruby/setup-ruby + bundle exec jekyll build:

  • Gemfile.lock governs the published site, so dependency pins and Dependabot
    alerts apply to production.
  • build.yml uses the same toolchain as the deploy, so a green check actually
    predicts a green deploy.
  • New .ruby-version (3.4.5) is the single source of truth, read by both workflows.
  • build.yml drops the pages: write / id-token: write permissions it never needed.
  • UPGRADE.md is excluded from the generated site.

baseurl is deliberately left at "" and steps.pages.outputs.base_path is not
consumed — the site is served from a custom apex domain (see CNAME), and
passing it would prefix every URL with a repository subpath.

Regression found and fixed

_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:

Result Pages
Byte-identical 21
Differ by blank lines only 3

The homepage matches to within two blank lines inside an excerpt.

The comparison must be run with TZ=UTC: _config.yml sets no timezone, so a
local build stamps <time datetime> as +01:00 where the runners stamp
+00:00. The rendered date text is identical either way; without TZ=UTC this
artifact masks the real comparison. Setting timezone: explicitly is left as an
optional follow-up since it would change published offsets.

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
@amjjbonvin

Copy link
Copy Markdown
Member Author

Copilot code review:

Verdict: looks good to merge.

I didn’t find any blocking issues in this PR.

Why it looks solid:

The root cause was real: the site was being built with actions/jekyll-build-pages, which uses its own github-pages gemset and ignores the repo’s Gemfile.lock. This change fixes that by standardizing both workflows on ruby/setup-ruby + bundle exec jekyll build.
.ruby-version gives a single source of truth for the Ruby version, and the workflow now reads it consistently.
The homepage fix in _layouts/home.html is the right workaround for the Jekyll 3 vs 4 ordering change: explicitly sorting site.categories.news prevents the regression.
Excluding UPGRADE.md from the generated site is sensible, and the workflow cleanup (pages: write / id-token: write removal) matches the actual needs.

@amjjbonvin
amjjbonvin merged commit b2173b7 into master Sep 29, 2026
2 checks passed
@amjjbonvin
amjjbonvin deleted the ci/jekyll4-native-build branch September 29, 2026 19:53
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.

1 participant