Skip to content

Commit 7867d86

Browse files
chore(ci): trim comments to the non-obvious constraints
1 parent 39ef8b2 commit 7867d86

5 files changed

Lines changed: 27 additions & 67 deletions

File tree

‎.github/actions/cache-mount/action.yml‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,18 @@ description: Mount a build cache directory using Blacksmith sticky disks, or the
33

44
inputs:
55
provider:
6-
description: Empty or 'blacksmith' selects sticky disks. Any other value selects actions/cache. Must stay byte-identical to the runs-on predicate in the calling workflow.
6+
description: Empty or 'blacksmith' selects sticky disks; anything else selects actions/cache.
77
required: false
88
default: ''
99
key:
10-
description: Cache key. Shared by both backends, so callers keep one key regardless of provider.
10+
description: Cache key, shared by both backends.
1111
required: true
1212
path:
13-
description: Filesystem path the cache is mounted at.
13+
description: Path to mount.
1414
required: true
1515

16-
# The two conditions are exact complements of the runs-on expression the caller
17-
# uses. They must be inverted together: a job placed on ubuntu-latest that then
18-
# took the sticky-disk branch would hard-fail, since stickydisk hot-mounts an
19-
# ext4 volume from Blacksmith's storage agents and cannot run anywhere else.
16+
# Predicates must stay the exact complement of the caller's runs-on — stickydisk
17+
# only runs on Blacksmith.
2018
runs:
2119
using: composite
2220
steps:
@@ -27,10 +25,8 @@ runs:
2725
key: ${{ inputs.key }}
2826
path: ${{ inputs.path }}
2927

30-
# Sticky disks always re-commit the mounted path, so the cache rolls forward
31-
# every run. actions/cache skips its save step on an exact key hit, which
32-
# would freeze the cache at whatever the first run wrote — the run-scoped
33-
# suffix plus a prefix restore-key reproduces the rolling behaviour.
28+
# run_id suffix + prefix restore-key: actions/cache skips save on an exact hit,
29+
# which would freeze the cache at the first run's contents.
3430
- name: Restore and save cache
3531
if: inputs.provider != '' && inputs.provider != 'blacksmith'
3632
uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5

‎.github/actions/docker-build/action.yml‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: Set up a buildx builder and build/push an image, using Blacksmith's
33

44
inputs:
55
provider:
6-
description: Empty or 'blacksmith' selects Blacksmith's builder. Any other value selects the upstream docker/* actions. Must stay byte-identical to the runs-on predicate in the calling workflow.
6+
description: Empty or 'blacksmith' selects Blacksmith's builder; anything else selects the docker/* actions.
77
required: false
88
default: ''
99
context:
@@ -20,10 +20,8 @@ inputs:
2020
description: Comma-separated list of tags to push.
2121
required: true
2222

23-
# Registry logins must already have run in the calling job — both backends read
24-
# the same ~/.docker/config.json. provenance/sbom stay off everywhere: the
25-
# attestation manifests they add break `imagetools create` retagging in the
26-
# promote-images and create-ghcr-manifests jobs.
23+
# Registry logins must precede this action. provenance/sbom stay off: attestation
24+
# manifests break `imagetools create` retagging in promote-images.
2725
runs:
2826
using: composite
2927
steps:
@@ -47,17 +45,9 @@ runs:
4745
if: inputs.provider != '' && inputs.provider != 'blacksmith'
4846
uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
4947

50-
# No layer cache here. Blacksmith caches layers on the builder itself;
51-
# the GitHub equivalent (cache-to: type=gha) shares the same 10 GB repo
52-
# cache quota as the bun/node_modules/turbo mounts, and four images of
53-
# layers would evict them. Fallback builds are cold by design.
54-
# NEXT_BUILD_HEAP_MB is trimmed from the 8192 default here because these
55-
# runners have 16 GB total and `next build` was getting OOM-killed (exit
56-
# 137) partway through. Only app.Dockerfile declares the arg; the other
57-
# images ignore it harmlessly, so it is set unconditionally rather than
58-
# threaded per-image through every call site. This is deliberately the only
59-
# build arg the action passes — a general passthrough input would let a
60-
# caller re-raise the ceiling and silently restore the OOM.
48+
# No cache-to: type=gha — it shares the 10 GB repo quota with the cache mounts.
49+
# Heap trimmed from the 8192 default: 16 GB runners OOM-killed next build (exit
50+
# 137). Hardcoded, not an input, so a caller can't re-raise it.
6151
- name: Build and push (GitHub)
6252
if: inputs.provider != '' && inputs.provider != 'blacksmith'
6353
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7

‎.github/workflows/ci.yml‎

Lines changed: 8 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,18 @@
11
name: CI
22

3-
# Runner provider toggle. Every job here and in the reusable workflows reads the
4-
# CI_PROVIDER repository variable:
3+
# Runner provider toggle, read from the CI_PROVIDER repo variable:
54
#
65
# gh variable set CI_PROVIDER --body github # fall back to GitHub-hosted
76
# gh variable delete CI_PROVIDER # back to Blacksmith (default)
87
#
9-
# It is a repo variable rather than a committed value on purpose: during a
10-
# Blacksmith outage there is no working CI to merge a switchover commit through,
11-
# and the variable takes effect on the next run with nothing to land.
8+
# A repo variable, not a committed value: during a Blacksmith outage there is no
9+
# working CI to merge a switchover through. Only unset/'blacksmith' selects
10+
# Blacksmith; anything unrecognized selects GitHub so a typo can't queue jobs
11+
# against the provider you're escaping. Every runs-on and both composite actions
12+
# share this predicate and must change together.
1213
#
13-
# Only unset or the exact value 'blacksmith' selects Blacksmith; everything else
14-
# selects GitHub-hosted. The unrecognized case resolves toward GitHub on purpose,
15-
# because that is the provider that is always available: a typo'd or whitespace-
16-
# padded break-glass value then yields slow-but-working CI instead of jobs queued
17-
# forever against the provider you were trying to escape. `==` is case-insensitive
18-
# in Actions expressions, so 'GitHub' and 'Blacksmith' both work. Every runs-on
19-
# expression and both composite actions use this same predicate — they must be
20-
# changed together, since a job on ubuntu-latest that took a Blacksmith-only
21-
# branch would hard-fail.
22-
#
23-
# GitHub mode is a break-glass fallback, not a peer. Public-repo ubuntu-latest is
24-
# 4 vCPU / 16 GB with no free 8-core tier, the 10 GB repo cache quota will thrash
25-
# across the bun/node_modules/turbo mounts, and image builds start from cold
26-
# layers. The first live flip (2026-07-21) proved it is not merely slower: the
27-
# app image OOM-killed `next build`, and one test failed because it shells out to
28-
# `rg`, which Blacksmith's image ships and GitHub's does not. Both are addressed
29-
# now — ripgrep is installed explicitly in test-build.yml, and the GitHub path
30-
# trims NEXT_BUILD_HEAP_MB — but the app image build stays the tight spot here
31-
# and is the first thing to check if a fallback run fails. Blacksmith-only
32-
# actions are reached
33-
# exclusively through .github/actions/cache-mount and .github/actions/docker-build,
34-
# which branch internally; a bare useblacksmith/* step added anywhere else will
35-
# hard-fail in GitHub mode rather than silently degrade.
14+
# GitHub mode is break-glass, not a peer — 4 vCPU/16 GB, cold layers, and the app
15+
# image build is the tight spot (it OOM-killed next build on the first live flip).
3616

3717
on:
3818
push:

‎.github/workflows/test-build.yml‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
# Cache keys are scoped by event name, and fork PRs get their own
3131
# namespace on top: untrusted fork runs must never share a cache with
3232
# push runs (whose caches feed production image builds) or with trusted
33-
# internal-PR runs. The scoping holds on both backends.
33+
# internal-PR runs.
3434
- name: Mount Bun cache
3535
uses: ./.github/actions/cache-mount
3636
with:
@@ -153,11 +153,8 @@ jobs:
153153
- name: Type-check realtime server
154154
run: bunx turbo run type-check --filter=@sim/realtime
155155

156-
# cloud-review-tools.test.ts runs the real helper script, which shells out
157-
# to `rg`. In production that script runs inside the E2B sandbox, whose
158-
# template apt-installs ripgrep — but the test executes it on the runner,
159-
# so the runner needs it too. Blacksmith's image ships rg and GitHub's does
160-
# not, which made this an invisible dependency on the runner provider.
156+
# cloud-review-tools.test.ts runs the real helper on the runner, which shells
157+
# out to rg. Blacksmith's image ships it, GitHub's doesn't.
161158
- name: Install ripgrep
162159
run: command -v rg || (sudo apt-get update && sudo apt-get install -y ripgrep)
163160

@@ -196,8 +193,7 @@ jobs:
196193
# with test-build (identical content from the same lockfile — LWW loss is
197194
# harmless), but the Turbo cache gets its own key: with a shared key, only
198195
# the last committer's new entries survive each run, so the test and build
199-
# Turbo entries would evict each other nondeterministically. The same split
200-
# is correct on actions/cache, which is likewise last-writer-wins per key.
196+
# Turbo entries would evict each other nondeterministically.
201197
build:
202198
name: Build App
203199
runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}

‎docker/app.Dockerfile‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,10 +76,8 @@ ENV DATABASE_URL=${DATABASE_URL}
7676
ARG NEXT_PUBLIC_APP_URL="http://localhost:3000"
7777
ENV NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL}
7878

79-
# V8 old-space ceiling for `next build`. Turbopack's own allocations are native
80-
# and sit outside this budget, so the ceiling has to leave room for them plus
81-
# the daemon and BuildKit — on a 16 GB runner the default 8192 is enough to get
82-
# the process OOM-killed. Only the heap size changes; build output does not.
79+
# V8 old-space ceiling for next build. Turbopack allocates natively, outside this
80+
# budget, so the ceiling must leave room for it plus BuildKit.
8381
ARG NEXT_BUILD_HEAP_MB=8192
8482
ENV NEXT_BUILD_HEAP_MB=${NEXT_BUILD_HEAP_MB}
8583

0 commit comments

Comments
 (0)