Add a root Dockerfile.lint that runs `hugo --minify --printPathWarnings`
as a build step, so a successful build IS a clean lint, and reduce
script/lint to building that file. There is no host lint path and
deliberately no "am I already inside a container?" branch, which would
be a host lint path in disguise.
The containerisation boundary is lint only, per the owner ruling on the
issue: formatting is not a lint, so script/fmt and script/fmt-check stay
on the host, unchanged in version, scope and flags. That also removes
the forced duplication of prettier's settings between a script and a
Dockerfile, and with it the keep-in-sync notes that duplication needed.
Dockerfile.lint has exactly one stage on purpose. A whole-file
`docker build -f Dockerfile.lint .` builds only the file's last stage,
and sibling stages off a shared base carry no ordering edge, so a second
stage beside the lint would be silently skipped by exactly the
invocation the canonical org-wide script/lint uses -- a green that
linted nothing, which the per-stage CHECK_EPOCH guard cannot catch
because the stage that did run satisfies it. With one stage there is
nothing to skip and script/lint needs no --target. A comment in the file
says that any second check added here must be chained or carry an
explicit ordering edge, never left as a sibling.
Its first four instructions are byte-identical to the main Dockerfile's
and in the same order, so the expensive `RUN script/bootstrap` layer
that compiles the pinned Hugo from source is shared between the two
images rather than paid twice.
Resolve the recursion by direction, not detection. `make check` calls
script/lint, and script/lint is now a `docker build`, so `RUN make
check` in an image would attempt a docker build inside a build step
where there is no daemon. The main Dockerfile therefore runs the
individual non-lint checks -- script/test and script/fmt-check, as
separate RUN lines under the CHECK_EPOCH guard -- matching the canonical
shape, and only the lint is absent from it. script/cibuild runs
script/lint first, for fail-fast feedback: on a runner with no cached
bootstrap layer a lint failure should not wait behind a Hugo build from
source. CI coverage is therefore unchanged, and it runs the same scripts
a developer runs.
Caching is waived for the lint in the shape this repo already settled:
ARG CHECK_EPOCH with no default, guarded with
`[ -n "$CHECK_EPOCH" ] || exit 1`, and the value expanded into the
linted command as well as the guard, so invalidation never rests on
BuildKit's treatment of an unreferenced ARG. Every image-building
entrypoint generates and passes it -- script/cibuild, script/docker,
script/lint -- each as a whole assignment rather than inline, for the
`set -e` reason script/cibuild documents.
script/lint builds with `--output type=cacheonly`: the build is run for
its exit status, not for an image, and because the lint layer is
cache-busted on every invocation an exporting build leaves one dangling
image per lint run. On a host shared with other work that accumulates.
The build cache is unaffected, so script/bootstrap still hits, and
failures still propagate.
Two divergences from REPO_POLICIES.md, stated rather than buried:
- REPO_POLICIES.md:92, "all Dockerfiles must run `make check`". That
rule and "every lint run happens in Docker" cannot both hold once
`make check` contains the lint.
- REPO_POLICIES.md:102-168, which requires a separate lint stage whose
result the build stage depends on through
`COPY --from=lint /src/go.sum /dev/null`, on the stated grounds that
without the edge "the build stage would not wait for lint to finish
and a lint failure might not fail the overall build". No such edge
exists here: the lint is its own file and its own build, sequenced
by script/cibuild rather than by BuildKit. Both sections are
superseded upstream by 12e8db8 in sneak/prompts, which deletes the
Go multistage lint stage and its ordering trick for the same reason
-- that stage ran `make lint`, which is now a docker build.
Verified: two consecutive script/lint runs on an unchanged tree both
executed hugo for real, distinct epochs echoed, script/bootstrap CACHED,
second run 0.85s; a whole-file `docker build -f Dockerfile.lint .` with
the argument and no --target ran the lint for real; a bare build with no
argument failed closed on the guard; a planted template error failed the
lint with hugo's own render error and made script/cibuild exit non-zero
in 0.6s with the main image build never starting; a planted over-long
line failed the host script/fmt-check; both reverted and re-run clean;
`make check`, script/docker and script/cibuild all green with every
check layer observed executing rather than served from cache, and the
bootstrap layer CACHED in both images. The deploy path is byte-identical
to main: .gitea/, script/bootstrap, script/test and .dockerignore are
untouched.
The repo had no LICENSE, which REPO_POLICIES.md lists as a mandatory
minimum file, and the README's License section said "Content is provided
as-is for community use." That granted nothing explicitly and matched no
committed file.
The repo is public, verified on the Gitea API rather than assumed, so
the standing policy applies: MIT on any public repo lacking a license.
LICENSE is byte-identical to the canonical sneak/homoicon copy (same git
blob, 3274443) and its body is word-for-word the SPDX MIT text, with
only the line wrapping differing.
The README License section now reads "MIT. See LICENSE.", and says
explicitly that the licence covers content/ as well as the code: this
repo carries both a Hugo site and its community content, while MIT's own
text speaks only of "the Software". The Description first line gains the
licence, which the README requirements call for and which was the one
field it was missing.
Nothing published contradicts the choice. The built public/ tree carries
no copyright, all-rights-reserved or terms-of-use string in index.html,
css/style.css, index.xml or sitemap.xml; the rendered footer names
@sneak and links the repo but reserves no rights, and the RSS carries no
copyright element. The content is factual mesh channel data asserting no
licence of its own.
LICENSE needed no .prettierignore entry, measured rather than assumed:
script/fmt passes prettier the explicit globs '**/*.md' and '**/*.css',
and an extensionless root file matches neither. A script/fmt run leaves
the file's hash unchanged, and a counterfactual LICENSE.md copy was
reflowed by that same run, which is the direct evidence that the
extension is what excludes it and not an ignore rule.
Per-file licence headers and SPDX identifiers are deliberately omitted;
no org standard mandates them.
Nothing on the deploy path is touched.
Hugo copies static/ verbatim into public/, so static/_headers lands at
the deploy output root, which is where Pages reads it from. This is the
first root-level static/ in the repo; Hugo unions it with the theme's
static/ per path rather than shadowing it, and the built tree confirms
that: public/css/style.css and public/index.html are byte-identical to
the previous build and the static file count goes from 1 to 2.
The live "before" was measured rather than assumed. Cloudflare already
sends X-Content-Type-Options and Referrer-Policy by default, so those
two lines are restatements; the substance is Strict-Transport-Security,
Content-Security-Policy, X-Frame-Options and Permissions-Policy, none of
which the site sends today.
Every value is checked against the built page, which loads nothing: no
script, img, link, iframe, form or media element, no style= and no on*=
attribute. It has exactly one inline <style> block, filled by readFile
in baseof.html. So default-src 'none' with style-src 'unsafe-inline' is
both achievable and tight, and 'unsafe-inline' is required by, and only
by, that deliberate inlining. There is no script-src allowance because
there are no scripts. X-Frame-Options: DENY and frame-ancestors 'none'
agree.
HSTS carries neither preload nor includeSubDomains. www.lora.vegas is
the only other name in DNS and it is served by this same Pages project,
so this file sets HSTS on its responses directly; includeSubDomains
would instead bind every future subdomain for a year, with no way to
walk it back inside the max-age window without also dropping the apex
protection.
Verified in a headless Chrome against a local server that parses the
committed _headers and applies it as real response headers: zero CSP
violations, the inlined stylesheet parses to 17 rules with the computed
body padding, tagline colour and link colour all coming from the theme
CSS, framing from another origin refused by frame-ancestors, and all
five named outbound links still navigating with status 200.
Whether Pages actually parses the file cannot be verified from here.
Pages silently ignores a malformed _headers, so the green build proves
nothing about it; that check belongs after the next deploy and must be
made on Strict-Transport-Security or Content-Security-Policy, since
X-Content-Type-Options would pass either way. It has to be run against
both lora.vegas and www.lora.vegas: dropping includeSubDomains rests on
www being served by this same Pages project, which was established from
identical response bodies rather than from the Cloudflare dashboard.
REPO_POLICIES.md mandates a fixed set of README sections; this README
predated the standard being applied here and had About / Contributing /
Technical Details / Entrypoints / License instead. It is now a
Description first line followed by Getting Started, Entrypoints,
Rationale, Design, TODO, License, Author, with Author last.
Nothing the old headings held was dropped: the list of what the site
publishes moved under the Description, and the contribute contact and
the local-preview instructions moved into Getting Started.
Getting Started was written against the current Makefile rather than
carried over from the old prose, which had drifted. There is no
`make build` target, so the old "Build: `hugo`" instruction is now
`make test`; "Local Development: `hugo server`" is now `make setup`
then `make serve`, and `make setup` is what makes a fresh clone
buildable at all since it installs the pinned Hugo.
Two stale claims are fixed. The site is deployed by Gitea Actions to
Cloudflare Pages, not "automatically via GitHub Actions". And the
Entrypoints bullet for `script/fmt` still described the
top-level-markdown-only scope that #12 replaced with `'**/*.md'` and
`'**/*.css'`; the rest of that section was verified accurate against the
scripts, including the `script/check` order and the `CHECK_EPOCH` guard
that makes a bare `docker build .` fail closed.
The License section body is deliberately untouched and no LICENSE file
is added: that is #10's, which is blocked on the owner's choice of
license. For the same reason the Description sentence omits the license
clause the policy asks for; #10 completes both.
The Design section's claims were checked against the tree rather than
assumed: the vendored theme, the `readFile` inline of style.css in
baseof.html, the `hugo --minify` output to `public/`, and the deploy
workflow.
REPO_POLICIES.md scopes prettier to JS/CSS/Markdown/HTML, but script/fmt
and script/fmt-check covered only '*.md' - top-level markdown. The
canonical scripts use '**/*.md'. Both now run over '**/*.md' and
'**/*.css', and both header comments, which still described the old
top-level-only scope, were rewritten.
That brings themes/loravega/static/css/style.css into the gate. It is
inlined into every page by baseof.html via readFile, and its formatting
is whitespace-only: the minified <style> block in the built
public/index.html is byte-identical across the reformat, which is the
preceding commit.
Two paths are excluded, each with the reason recorded in
.prettierignore so the exclusion reads as a decision rather than an
oversight:
themes/loravega/layouts/ - these are not HTML. They are Go templates
carrying {{ define }}, {{ block }}, {{ .Content }} and
{{ readFile ... | safeCSS }}, and prettier has no Go-template parser; it
would fail or reflow the delimiters into markup Hugo cannot parse.
Covering them needs an out-of-tree plugin and therefore a package.json,
which this repo deliberately does not have.
content/ - excluded on measurement, not on the earlier assumption. With
content/ in scope, prettier re-wrapped one list item in
content/_index.md, and the rendered public/index.html changed with it:
the wrap landed as a literal newline between "7 PM at" and the following
<a> tag. HTML collapses that newline to a space, so the page looks the
same, but the published bytes do not match, and this content carries raw
div/span/br blocks that goldmark passes through verbatim because
hugo.toml sets markup.goldmark.renderer.unsafe = true. A formatter that
can silently change a published page is not worth the consistency.
archetypes/ stays covered - it is a template for new content, not
published output, and prettier leaves it unchanged.
Verified by extracting public/ from the built image before and after.
With the final scope, index.html, index.xml and sitemap.xml are
byte-identical; only the verbatim-copied public/css/style.css differs,
in whitespace. Each commit on this branch passes make check on its own -
the reformat lands first, under the old narrow glob that does not look
at CSS, so the widening commit arrives on an already-clean tree and no
merge commit is required to land it.
Pure formatting churn, no functional change. Kept as its own commit
ahead of the script change so the widened gate lands on an already-clean
tree, per REPO_POLICIES.md: formatting diffs are large and must not be
mixed with functional changes.
The file is inlined verbatim into every page by baseof.html via
readFile, so this was checked rather than assumed: the minified <style>
block in the built public/index.html is byte-identical before and after.
Prettier CSS formatting is whitespace-only and cannot reach the rendered
page.
The canonical upstream copy is not clean under --tab-width 4
--prose-wrap always: prettier@3.4.2 inserts a blank line before a nested
list that directly follows a paragraph, in five places. script/fmt-check
covers *.md at the repo root, so make check fails on the byte-identical
copy.
Split out from the preceding commit so the functional change and the
formatting churn stay separately reviewable. The change is whitespace
only - five blank lines - and does not alter the rendered document.
The canonical copy upstream should be reformatted so future syncs are a
straight byte copy again; tracked in TODO.md.
REPO_POLICIES.md lists the files every repo must contain at minimum;
four were missing here and .gitignore covered only Hugo's outputs.
REPO_POLICIES.md is a byte-identical copy of the canonical file in the
prompts repo, YAML front matter (title, last_modified) intact so it can
be diffed against upstream as policy evolves. It is not clean under this
repo's prettier settings, so the reformat is the next commit rather than
churn mixed in here; the byte-identical copy is what landed.
.editorconfig, .prettierrc and .prettierignore are the canonical
contents. script/fmt and script/fmt-check keep passing --tab-width 4
--prose-wrap always on the command line: the duplication is deliberate
so the scripts still work standalone when copied as a template, and the
values agree, so adding .prettierrc changes nothing about what make fmt
does.
.gitignore keeps its three Hugo lines and gains the canonical
OS/editor/node/secrets block plus .claude/. The secrets patterns are the
point: a stray .env or private key can no longer be committed by a broad
git add. .claude/ holds worktrees/, so without it a clean checkout with
agent tooling present is not git status-clean.
.dockerignore gains the same coverage but not the same syntax. It does
not use .gitignore semantics: it matches with Go's filepath.Match rules
extended with **, where * does not cross / and an unprefixed pattern is
anchored at the context root. A bare *.key therefore excludes
./server.key and ships ./certs/server.key into the image, which is worse
than an obviously incomplete file because it reads as complete. Every
depth-independent pattern here carries an explicit **/ prefix; only the
entries that are genuinely root-anchored by definition go bare - .git,
Hugo's public and resources output directories, and .hugo_build.lock.
The distinction is spelled out in a comment at the top of the file so
the next edit does not quietly undo it.
Excluding .claude/ also keeps entire additional checkouts of this repo
out of the build context, which the Dockerfile's COPY . . would
otherwise copy into the image.
Verified by planting .env, server.key, deep.pem and node_modules two
directories deep and building: with the patterns unprefixed all of them
reach /src in the image, with **/ none do. Root-only testing does not
exercise this and produces a false pass.
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
