From 219b7a214379e37816030c17ecfa624ee4fc1c10 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Wed, 20 May 2026 10:23:38 +0200 Subject: [PATCH] fix(ci): pass NODE_OPTIONS=--use-system-ca to clear grpc-tools tls install (#199) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary The CI runner fails `pnpm install --frozen-lockfile` since the AI-relay chantier added `grpc-tools` to the dep tree. The package's postinstall downloads a precompiled `protoc` archive from `node-precompiled-binaries.grpc.io`, and Node 24's bundled CA set cannot verify the TLS chain on the runner network path. The fix follows the Node team's own remediation, surfaced verbatim in the error message: > unable to verify the first certificate; if the root CA is installed locally, try running Node.js with `--use-system-ca` Setting `NODE_OPTIONS=--use-system-ca` at the workflow `env:` block makes Node consult the OS CA store in addition to its bundled set. The runner image (`catthehacker/ubuntu:act-22.04` per [ADR-0015](docs/decisions/0015-cicd-gitea-actions.md)) carries the standard Ubuntu `ca-certificates` bundle, which validates the chain. ## What lands `.gitea/workflows/ci.yml`: ```yaml env: NODE_OPTIONS: --use-system-ca ``` `.gitea/workflows/docs-site.yml`: same one-line block. Both placed at workflow scope so every Node process (pnpm itself + every postinstall it spawns) inherits the option without per-step duplication. No package.json change. No code change. No runner-image change. ## Notes for the reviewer - **Why not skip the grpc-tools postinstall in CI instead.** The protoc binary downloaded here is never invoked in CI — the generated TypeScript stubs in `apps/portal-bff/src/grpc/gen/` are committed (per ADR-0024 §"Sub-decision 3 — vendored protos"), so CI only needs to type-check them. Removing `grpc-tools` from `pnpm.onlyBuiltDependencies` would also clear the failure and is arguably more minimal in CI. The trade-off: developers who update protos would have to opt back into the postinstall (`pnpm approve-builds grpc-tools && pnpm rebuild grpc-tools`) before running `pnpm grpc:codegen`. `--use-system-ca` keeps the developer workflow identical and fixes the underlying TLS-chain issue for any future native dep that hits the same wall (a real risk as the dep tree grows). The cost is a single workflow env var. - **Why workflow-scope `env:` rather than per-step `env:`.** Five separate `pnpm install` steps run across `ci.yml`; setting it five times would invite drift. The `env:` block at workflow scope applies to every step in every job — clean, single source of truth. - **Node 24 compatibility.** `--use-system-ca` is documented since Node 22; Node 24 (the workspace LTS per `.nvmrc`) carries it. No `.nvmrc` change required. - **Local-dev impact.** None. Local developers' Node already validates the chain (the issue is specific to the runner's network path); the env var is a no-op locally. - **Forward compatibility.** If a future native dep fetches binaries from a different CDN with a similar chain issue, this fix covers it without further changes. ## Test plan This PR cannot be locally validated in a way that reproduces the failure — the CI runner's network path is the only environment where `node-precompiled-binaries.grpc.io` cannot be reached with Node's bundled CA. The validation is the next CI run. - [ ] **CI green** on this PR's first run — `pnpm install --frozen-lockfile` completes; `pnpm ci:check` runs to completion. - [ ] If CI still fails: the runner's Ubuntu CA bundle does not contain the missing intermediate either. Fallback path: drop `grpc-tools` from `pnpm.onlyBuiltDependencies` so the postinstall is skipped entirely in CI (and document the dev-side `pnpm approve-builds` step). Trivial follow-up if needed. ## What's next If `--use-system-ca` fixes the CI install and no other Node TLS issues surface, no further action is required. The env var stays as a forward-looking guard. --------- Co-authored-by: Julien Gautier Reviewed-on: https://git.unespace.com/julien/apf_portal/pulls/199 --- .gitea/workflows/ci.yml | 12 ++++++++++++ .gitea/workflows/docs-site.yml | 7 +++++++ 2 files changed, 19 insertions(+) diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 7123a19..1bd0753 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -11,6 +11,18 @@ on: push: branches: [main] +# Node 24's bundled CA set does not include every intermediate the +# self-hosted runner's network path serves (the precompiled-binary +# CDN behind grpc-tools is the first surface where this surfaced). +# `--use-system-ca` tells Node to consult the OS CA store in +# addition to its bundled set — supported since Node 22 and the +# documented Node-team fix for exactly this class of TLS-chain +# rejection. The runner image (`catthehacker/ubuntu:act-22.04` per +# ADR-0015) carries the standard Ubuntu `ca-certificates` bundle, +# which validates the impacted chains. +env: + NODE_OPTIONS: --use-system-ca + jobs: check: runs-on: [self-hosted, on-prem] diff --git a/.gitea/workflows/docs-site.yml b/.gitea/workflows/docs-site.yml index 1d271e1..113bbce 100644 --- a/.gitea/workflows/docs-site.yml +++ b/.gitea/workflows/docs-site.yml @@ -28,6 +28,13 @@ on: - 'pnpm-lock.yaml' - '.gitea/workflows/docs-site.yml' +# See `.gitea/workflows/ci.yml` for the rationale — Node 24's +# bundled CA set rejects some chains the runner's OS trust store +# validates, and `--use-system-ca` (Node ≥ 22) tells Node to +# consult the OS CA bundle alongside its own. +env: + NODE_OPTIONS: --use-system-ca + jobs: build: runs-on: [self-hosted, on-prem]