script/bootstrap did `pkg_install hugo hugo hugo hugo`, so the tool that
produces the published artifact was whatever the base image's package
repo happened to serve: alpine 3.21 gives hugo 0.139.0, about two years
behind upstream, chosen by nobody, and liable to change silently on any
base image digest bump. Hugo's version is a property of the site's
output, not of the build environment, so it now gets pinned like every
other external reference in this repo.
It is installed with `go install github.com/gohugoio/hugo@v0.164.0`,
which verifies the module against the sum.golang.org checksum database.
That is genuine hash verification rather than bare version pinning, it
is the mechanism REPO_POLICIES.md already names for Go, and it needs no
hand-maintained sha256. It also keeps a single pinned base image: a
digest-pinned Hugo container would have reintroduced the second base
image that #7 deliberately removed.
Two constants carry the decision, each with the canonical
`# name version, YYYY-MM-DD` comment:
- HUGO_VERSION=v0.164.0, the current stable release.
- HUGO_GOTOOLCHAIN=go1.26.5. hugo v0.164.0's go.mod requires
go >= 1.26.0 and alpine 3.21's go package is 1.23.9 built with
GOTOOLCHAIN=local, so a bare `go install` refuses to run at all.
Naming the toolchain makes Go fetch it through the module proxy and
verify it against sum.golang.org like any other module, so the chain
stays hash-verified end to end and the compiler is deliberate too.
CGO_ENABLED=0 is deliberate: standard Hugo, not extended. Verified that
this site uses nothing extended provides - no .scss/.sass, no
resources.ToCSS, no PostCSS, and no image processing; the CSS is plain
and inlined by readFile in baseof.html. The `+extended` on the apk build
this replaces was incidental, and the script says so, so a later change
does not assume extended is required.
The binary is placed in /usr/local/bin rather than left in a GOPATH bin
directory, because it has to be on the default PATH of a *fresh* shell:
the Dockerfile's `RUN make check` and deploy.yml's `script/test` step
each start their own shell. The location is overridable via
HUGO_BIN_DIR for unprivileged installs, and `go install` itself runs as
the invoking user so a workstation's module cache is not populated as
root.
The idempotency guard is version-aware instead of `missing hugo`: an
older hugo already on PATH must be replaced, not accepted, or the pin
means nothing. A same-version build that happens to be `+extended` is
accepted, since it renders this site identically. After installing, the
script re-checks what `hugo` on PATH actually resolves to and fails
loudly if something else shadows it.
Rendered output was compared three ways in a container carrying both
binaries - apk 0.139.0 against 0.164.0 on identical sources. Across the
whole public/ tree the only byte that differs is the generator meta
tag's version string, which is the change describing itself. The RSS
<language> element and the html lang attribute are unchanged.
Cold `script/cibuild` is 2m36s, within the five-minute budget: 52.6s of
it is the bootstrap layer (apk go, toolchain fetch, compile) and 100s is
image export. The check image grows to 683 MB because the Go toolchain
and module cache stay in the bootstrap layer; that image is only ever
built to run checks, never published or deployed.
script/check ran only fmt-check then test, so script/lint was never
invoked anywhere in the gate: make check shims to script/check, the
Dockerfile runs make check, script/cibuild builds the Dockerfile, and
the pre-commit hook calls script/check. The script was dead code that
the README advertised as part of the gate.
It now runs test, lint, fmt-check in the canonical order. script/lint
is hugo --minify --printPathWarnings, which reports render-target
collisions that the plain hugo --minify in script/test does not; that
signal was being discarded.
The gate still modifies no tracked files. script/test and script/lint
both write to public/, which is gitignored and was already written by
script/test before this change.
Corrects the two documents that enumerated the old two-step gate: the
README Entrypoints line for script/check, and the Dockerfile header
comment above the RUN make check that executes it.
deploy.yml was the last file in the repo carrying mutable external references.
Both job container images are now pinned by digest, all three `uses:` by a full
40-hex commit SHA, and the wrangler install by exact version, each with a
version/date comment above the reference.
- build container: klakegg/hugo:ext-alpine (abandoned since 2021, mutable tag)
replaced by the exact alpine 3.21 digest the Dockerfile already pins, with a
pre-checkout `apk add --no-cache nodejs git tar` step, `shell: sh` as the job
default, then script/bootstrap and script/test. One pinned base and one
dependency list now serve both the check build and the deploy build.
- deploy container: node:20 -> node@sha256:8f693eaa... (node 20.20.2 bookworm).
- actions/checkout: v4 -> 11bd7190... (v4.2.2), the same SHA check.yml pins.
- actions/upload-artifact: -> ff15f030... (v3.2.1).
- actions/download-artifact: -> 9bc31d5c... (v3.0.2).
- wrangler: `npm install -g wrangler` -> `wrangler@4.86.0`.
Also drops the dead feat/initial-site push trigger, reindents to 4-space YAML
to match check.yml, and adds `if: github.ref_name == 'main'` to the deploy job
so it can never publish from a branch.
This is the second attempt. The first passed two adversarial reviews, merged,
and broke the deploy, because deploy.yml triggers only on push to main and so
nobody could execute what they were reviewing. This time the workflow was
temporarily triggered on the branch, with the deploy job guarded off, and
iterated against the commit-status API until the build job ran green for real.
Doing that found two independent breaks that review had not:
1. actions/upload-artifact v4 fails on this Gitea Actions instance -- artifacts
v4 is a different wire protocol and it is not served here. Two otherwise
identical branch jobs, one with the v4 upload step and one without, failed
and passed respectively. The issue asked for the v3 -> v4 bump; the
artifact actions instead stay on the v3 line, pinned by SHA, at the exact
commits the mutable @v3 references were already resolving to. Tracked
separately in issue 20.
2. wrangler 4.120.0 requires node >= 22 and refuses to start on the pinned
node 20 container. `npm install` only warns about engines, so the install
step would have passed and the deploy step would have failed. The unpinned
command this replaces was never installing `latest` either: npm resolves a
bare name to the newest version whose engines the running node satisfies,
which on node 20 is 4.86.0. So 4.86.0 is what has actually been deploying
this site, and that is what is pinned. Tracked separately in issue 21.
The temporary branch trigger and the temporary probe workflow used to bisect
this are removed in this commit; the deploy guard is deliberately kept.
Verified: make check and script/cibuild green; the build job observed green on
the branch under act_runner (commit 73f912c, "Successful in 7s"); a probe job
pair rehearsed the deploy job end to end -- same pinned node image, same pinned
download action, same pinned wrangler, real site tarball extracted -- stopping
at `wrangler pages deploy --help` instead of publishing. The real deploy job
remains unexercised: it needs CLOUDFLARE_API_TOKEN and would publish, so it can
only run on main. The main run must still be watched and the live site
confirmed.
Replacing klakegg/hugo:ext-alpine with the Dockerfile's pinned alpine
digest satisfied the pinning requirement but dropped the runtime the
Actions runner itself depends on, which would have broken the deploy:
- act_runner executes JavaScript actions with `node` inside the job
container and does not inject one. Stock alpine has no node, so
actions/checkout - the job's first step - would fail with
"node: not found", and script/bootstrap (which installs node) is step
2 and never runs. The build job fails, deploy is skipped for
`needs: build`, and the site stops publishing.
- Steps default to `bash`, which stock alpine does not ship either.
Fixes, both scoped to keeping the mandated image replacement runnable:
- A pre-checkout inline `run:` step (`apk add --no-cache nodejs git tar`)
installs what the runner needs before the first `uses:` step. An
inline run needs only a shell, so it works on the bare image. git is
there for checkout's `submodules: recursive`; without it checkout
degrades to a tarball download that cannot do submodules.
- `defaults.run.shell: sh` on the build job, so the shell is stated
rather than left to a bash-to-sh fallback.
No pinned value is touched. The apk packages resolve at run time and are
not hash-pinned; that gap is repo-wide (script/bootstrap has it too) and
is tracked in #19.
Also moves each version/date comment to sit directly above the pinned
line rather than above the step's `- name:`, matching check.yml, and
dates the actions/checkout pin 2026-02-28 as check.yml already does for
the same SHA.
Verified by running the build job's step sequence inside the pinned
alpine digest: bare, `node` and `bash` are absent and the pinned
checkout bundle dies with "node: not found"; after the new apk step,
node 22.23.2, git 2.47.3 and GNU tar 1.35 are present, that same
checkout bundle runs under node and gets as far as "GITHUB_WORKSPACE not
defined", and script/bootstrap, script/test and the tar step all
complete. make check and script/cibuild (with the build cache pruned, so
nothing was CACHED) are green.
deploy.yml was the last file in the repo carrying mutable external
references. Every image is now pinned by digest and every action by a
full 40-hex commit SHA, each with a version/date comment on the line
above. All values were resolved from upstream and verified to resolve.
- build container: klakegg/hugo:ext-alpine (abandoned since 2021,
mutable tag) replaced by the exact alpine 3.21 digest the Dockerfile
already pins, with script/bootstrap to install hugo and script/test
to build. One pinned base and one dependency list now serve both the
check build and the deploy build.
- deploy container: node:20 -> node@sha256:8f693eaa... (node 20.20.2,
bookworm).
- actions/checkout: v4 -> 11bd7190... (v4.2.2), the same SHA check.yml
pins, so the two workflows agree.
- actions/upload-artifact: v3 -> ea165f8d... (v4.6.2); v3 is deprecated.
- actions/download-artifact: v3 -> d3f86a10... (v4.3.0); v3 is
deprecated.
- npm install -g wrangler -> wrangler@4.120.0, so the deploy no longer
executes whatever the wrangler tag happens to point at.
Also drops the dead feat/initial-site push trigger (that branch is fully
merged into main) and reindents the file to 4-space YAML to match
check.yml and .editorconfig.
The two jobs are deliberately left separate so a deploy regression can
be attributed unambiguously.
Verified: make check and script/cibuild both green; the workflow parses
as YAML with the expected job/step structure. The Cloudflare Pages
deploy path itself cannot be exercised from a branch (it runs only on
push to main and needs CLOUDFLARE_API_TOKEN), so the deploy run on main
must be watched after merge.
Adopt the Scripts to Rule Them All standard for this Hugo site:
- script/ POSIX-sh entrypoints (bootstrap, setup, projectname, test,
lint, fmt, fmt-check, check, docker, cibuild, precommit,
install-precommit). The correctness check (test/lint) is a clean
`hugo --minify` production build; fmt/fmt-check run prettier over the
repo's own top-level markdown only, leaving content/ untouched.
- Makefile targets reduced to thin shims that call script/NAME, plus a
convenience serve target for `hugo server`.
- Dockerfile on a sha256-pinned alpine base that installs deps via
script/bootstrap and runs `make check`, so the image build fails on
any formatting or Hugo build error; .dockerignore added.
- .gitea/workflows/check.yml runs script/cibuild on push.
- README Entrypoints section documenting the scripts.
