script/cibuild was a bare `docker build .`, and the Dockerfile did
`COPY . .` then `RUN make check`. COPY is keyed on content, so on an
unchanged tree Docker served the check layer from cache: the checks
never executed, no Hugo or prettier output appeared, and the build still
exited 0. A gate that reports success without running is worse than no
gate, because it is trusted -- three separate reviewers in this repo
have been fooled by it.
The Dockerfile now declares `ARG CHECK_EPOCH` immediately below
`COPY . .`, guards it, and expands it into the check command:
ARG CHECK_EPOCH
RUN [ -n "$CHECK_EPOCH" ] || exit 1
RUN echo "check epoch: ${CHECK_EPOCH}" && make check
script/cibuild and script/docker both generate the value identically and
pass it. Every element is load-bearing:
- No default value. A default is a constant, and a constant is a stable
cache key -- the defect unchanged.
- Placed below `COPY . .`. Everything above keeps caching, so the
script/bootstrap layer, which compiles Hugo from source, is not
rebuilt. Whole-build `--no-cache` would have discarded it and blown
the five-minute budget for no benefit.
- The guard. An unset ARG is the empty string, which is also a stable
cache key, so without it a bare `docker build .` still collects the
false green. Failed steps are never cached, so it fails on every such
invocation rather than only the first. This is why script/docker had
to be updated too: the guard makes passing the argument mandatory for
every entrypoint that builds the image.
- The value expanded into the RUN. Hardening rather than the fix: the
bare unreferenced-ARG form does work, but expansion makes the cache
miss contractual rather than dependent on BuildKit's handling of an
unreferenced ARG, and puts the epoch in the build log. The guard also
references the value, so there are two independent invalidation
points, not one.
- `epoch="$(date +%s%N)$$"` on its own line rather than inlined into the
argument list. A command substitution that fails inside an argument
does not trip `set -e`, so the inline form would quietly pass an empty
string and restore the cached false green. `%N` keeps concurrent
invocations distinct; `$$` covers busybox date, which drops `%N`
silently and still exits 0.
ARG is stage-scoped and must be redeclared in every stage that runs
checks. This image is single-stage, so one declaration is complete.
This is the shape settled upstream in the prompts repo, where it has not
merged to main yet, so it may need re-syncing later.
Verified: two consecutive script/cibuild runs on an unchanged tree both
executed the checks (two Hugo builds and the prettier line in each,
15s then 6s) with `RUN script/bootstrap` and `COPY . .` both CACHED in
the second -- the validity control that rules out a cache eviction
between them. A constant-epoch counterfactual restored the cached false
green, confirming the varying value is what does the work. A bare
`docker build .` now fails on the guard, and fails again on immediate
repeat. A planted prettier failure failed the build with exit 1. `make
docker` and `make check` both pass.
Hugo enables the `tags` and `categories` taxonomies by default. This
site is a single page with no taxonomy terms and no taxonomy templates,
so every build emitted
WARN found no layout file for "html" for kind "taxonomy"
and generated `categories/index.xml` and `tags/index.xml` that nothing
links to. `disableKinds = ['taxonomy', 'term']` is the documented Hugo
mechanism for a site that uses no taxonomies; it removes the warning at
its source rather than suppressing it, and it does not create dead
template files to satisfy the layout lookup.
The premise was re-verified against hugo v0.164.0, the version now
pinned in `script/bootstrap`, rather than trusted from the issue text,
which was written when the build still used apk's 0.139.0. The warning
and the unwanted pages are unchanged on v0.164.0.
`make test`, `make lint` and `make check` now emit zero `WARN` lines, so
the build's noise floor is zero and the next warning to appear will be
visible instead of scrolling past. Rendered output is otherwise
byte-identical: `index.html`, `css/style.css` and the RSS `index.xml`
are unchanged, and `sitemap.xml` is still generated, now listing only
the home page rather than two taxonomy URLs.
Reverts the branch entry added purely so act_runner would really
execute the deploy workflow's build job against the new hugo install
path. deploy.yml is back to `branches: [main]` and is now byte-identical
to main's copy: `git diff main HEAD -- .gitea/workflows/deploy.yml` is
empty.
The runner-verified commit 2a95023 is deliberately left in this branch's
history rather than rebased away, so a reviewer can confirm for
themselves that nothing functional changed between what the runner
actually ran and what is being merged:
git diff 2a95023 HEAD -- .gitea/workflows/deploy.yml
Only the trigger entry and its comment differ.
Hugo deprecated the project config key `languageCode` in v0.158.0 in
favour of `locale`, and says it will be removed. The preceding commit
moves the build onto hugo v0.164.0, which emits:
WARN deprecated: project config key languageCode was deprecated in
Hugo v0.158.0 and will be removed in a future release. Use locale
instead.
Left alone that would be a third routinely-ignored warning in the build
output alongside #13's taxonomy warning, and a latent breakage once the
key is dropped.
Sequencing matters and is why this rides in the same branch, on top of
the version move rather than before it. Under the apk hugo 0.139.0 that
CI ran until the preceding commit, `locale` is simply an unknown key:
0.139.0 ignores it and falls back, which downgrades the generated RSS
from <language>en-us</language> to <language>en</language>. No warning,
no error, exit 0 - an output regression the gate would not have caught.
Landing this first would have broken the published feed.
Verified on hugo v0.164.0, the version the build now actually uses:
- the RSS <language> element still reads en-us;
- the html lang attribute is unchanged;
- public/ is byte-identical to the preceding commit's output, so the
key swap is a pure no-op on rendered content;
- the deprecation warning is gone from the build output.
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.
Round 3 (07af755) cleared the artifact path and left one failure:
check / check success 8s
Build and Deploy .../ build success 8s <- green
Build and Deploy .../ deploy skipped <- if: guard
probe / r1-wrangler-only failure 7s
probe / r2a-upload-proven success 12s
probe / r2b-download-proven success 2s
probe / r3a-upload-node20 success 8s
probe / r3b-download-node20 success 2s
r2a/r2b and r3a/r3b upload and download the real site tarball across the two
job containers, so the artifact round trip is sound. r1 does nothing but
install wrangler and invoke it, and it fails.
Reproduced locally in the pinned node image, which is faster than another CI
round:
$ docker run --rm node@sha256:8f693eaa... sh -c \
'npm install -g wrangler@4.120.0; wrangler --version'
install exit=0 (with EBADENGINE warnings)
Wrangler requires at least Node.js v22.0.0. You are using v20.20.2.
version exit=1
npm treats engines as a warning on an explicit version, so the install step
would have passed and the deploy step would have failed -- a second break,
independent of the artifact one, in the same job nobody could run.
The instructive part is what the unpinned command it replaced was doing:
$ docker run --rm node@sha256:8f693eaa... sh -c \
'npm install -g wrangler; wrangler --version'
`-- wrangler@4.86.0
4.86.0
npm resolves a bare name to the newest version whose engines the running node
satisfies, so `npm install -g wrangler` on node 20 has been installing 4.86.0,
not the 4.120.0 that `latest` points at. Pinning 4.120.0 was therefore not
"pin the version we are already getting", it was an unnoticed major-ish bump
onto a node the container does not have.
So this pins wrangler 4.86.0 (engines: node >= 20.3.0, published 2026-04-28),
which is exactly the version that has been deploying this site, verified to
install and run on the pinned node 20 digest. The node image digest is left
alone. Bumping the container to node 22 to keep 4.120.0 is the alternative,
but that changes the deploy runtime for no benefit this issue asks for.
Round 4 replaces the probe jobs with a single end-to-end rehearsal: the build
job as written, then the deploy job as written with `wrangler pages deploy
--help` in place of the publish call.
Round 2 (602fd60) put the build job green:
check / check success 6s
Build and Deploy .../ build success 20s <- green
Build and Deploy .../ deploy skipped <- if: guard
probe / q1-upload-v3-node16 success 7s
probe / q2-upload-v3-node20 success 22s
probe / q3-build-for-roundtrip success 11s
probe / q4-deploy-dryrun failure 43s
Every v3 upload works and the build job is fixed. But q4 -- the deploy-side
rehearsal, which downloads the artifact in the pinned node container and
installs the pinned wrangler, stopping short of the publish call -- failed.
That is a break the deploy job would have hit on main, in a job nobody has
ever been able to run.
q4 bundled two things together, so round 3 splits them:
- r1 runs only the wrangler install and invocation. Worth measuring rather
than assuming: wrangler 4.120.0 declares engines.node >= 22 and the deploy
container is node 20, though the pre-issue deploy did run an unpinned
wrangler on node:20 successfully.
- r2a/r2b run the artifact round trip with no wrangler at all.
- r3a/r3b do the same for the newer node20 artifact builds, so the choice
between the two pairs is made on measurement.
deploy.yml meanwhile moves to the artifact commits that the mutable `@v3`
references were actually resolving to while this site was deploying, rather
than to the newest thing on the v3 line:
- upload-artifact -> ff15f030 (v3.2.1)
- download-artifact -> 9bc31d5c (v3.0.2)
That is the conservative reading of what this issue is for: pin what is known
to work, do not take a version bump for free on the way past.
Round 1 of the branch probes reproduced the main failure and localised it.
Observed commit-status output for 2d328e7:
check / check success 10s
Build and Deploy .../ build failure 15s <- reproduced
Build and Deploy .../ deploy skipped <- if: guard working
probe / p1-bare-alpine-checkout failure 3s
probe / p2-alpine-apk-checkout success 5s
probe / p3-alpine-apk-build success 15s
probe / p4-alpine-apk-upload failure 11s
probe / p5-node20alpine-checkout success 8s
probe / p6-node20slim-checkout success 11s
Reading that:
- p1 vs p2: act_runner does not supply node for JavaScript actions, so the
`apk add --no-cache nodejs git tar` prerequisite step is genuinely required
and genuinely sufficient. checkout then runs on musl.
- p3: script/bootstrap and script/test complete inside the Actions container
on the pinned alpine digest. The mandated image replacement was never the
problem.
- p2 vs p4: the only difference is a trailing upload-artifact v4 step, and it
is the difference between success and failure.
- p5/p6: musl is not the issue -- checkout runs on both musl and glibc images.
So what broke the deploy was not the image swap that everyone reviewed, it was
the v3 -> v4 artifact bump that nobody questioned. Gitea 1.25.4's artifact
backend and this runner do not serve the v4 protocol; the workflow used v3
before this issue and that is what worked.
The artifact actions therefore move back to the v3 line, still pinned by full
commit SHA, which satisfies the hash-pinning requirement this issue is actually
about. Both are the node20 builds rather than the node16 defaults, so nothing
depends on a node16 runtime:
- upload-artifact -> c6a3b2bd (v3.2.2-node20)
- download-artifact -> ad191675 (v3.1.0-node20)
Round 2 probes: the two fallback v3 builds in case the node20 ones do not
resolve, plus a producer/consumer pair that rehearses the deploy job -- same
pinned node image, same pinned download action, same pinned wrangler version,
stopping short of `wrangler pages deploy` so it touches nothing external.
Restores the hash-pinning work reverted in 3d17e22 (originally 3f91a7c and
b157bfd) verbatim -- all six pinned values were independently re-resolved and
confirmed correct twice, so they are reused, not re-derived.
What is different this time is that the path is observable before it reaches
main. The previous attempt broke the deploy because deploy.yml triggers only on
push to main, so every pre-merge check simulated the runner instead of being
it, and two adversarial reviews could not catch what neither could execute.
Three changes on top of the restored work:
- A temporary development-only branch trigger on on.push.branches, so the
build job actually executes under act_runner. Removed before merge.
- if: github.ref_name == 'main' on the deploy job. Without it, a branch push
would run wrangler pages deploy against the real Cloudflare project with the
real token on every iteration. This guard is permanent: it is one line and it
makes any future branch trigger, deliberate or accidental, unable to reach
Cloudflare.
- A temporary .gitea/workflows/probe.yml, also deleted before merge. The
Actions jobs and logs API is not readable by this account; the commit-status
API is, and it reports one entry per job. So the diagnosis is encoded as job
topology rather than log output: six jobs, each isolating one hypothesis
about the 22s failure (bare alpine vs apk prerequisites, checkout vs site
build vs artifact upload, musl node vs glibc node), each surfacing as its own
status context so a single push tests them all in parallel.
make check is green. No pinned value is touched.
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.
- switch to bright/light color scheme
- inline CSS in head for single-file deployment
- show full mesh/signal URLs in monospace
- reorganize meetups into upcoming/past sections
- add Meshcore section
- remove beginner explanatory content
Minimal single-page site with custom loravega theme.
No external dependencies, no JavaScript, pure local CSS.
Sections: Mesh Channels, Discord Groups, Signal Groups, Meetup, Resources.
Includes LongFast settings reference and getting-started guide.
Closes#1
