fix(ci): move grpc-tools to optionalDependencies (revert NODE_OPTIONS attempt) #200

Merged

julien merged 1 commits from fix/ci-grpc-tools-optional into main 2026-05-20 15:06:27 +02:00

Conversation 0 Commits 1 Files Changed 4

+12 -24

julien commented 2026-05-20 15:05:58 +02:00

Owner

Copy Link

Copy Source

Summary

The NODE_OPTIONS=--use-system-ca workaround merged in #199 did not clear the CI install failure — the runner still rejects the TLS chain to node-precompiled-binaries.grpc.io. Either the runner's OS CA bundle is missing the same intermediate Node's bundled set is missing, or --use-system-ca does not propagate down to the node-fetch@2 that node-pre-gyp uses. Without runner shell access the exact reason is not worth chasing.

Switch angle: the protoc binary grpc-tools downloads is never used 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; protoc only runs when a developer regenerates from apps/portal-bff/src/grpc/proto/apf-ai/*.proto.

This PR moves grpc-tools from devDependencies to optionalDependencies. Per pnpm semantics, when an optional dep's install (including postinstall) fails, pnpm logs a warning and the overall install completes. CI's pnpm install --frozen-lockfile therefore succeeds even when the binary cannot be fetched; developer machines (where TLS validates) install grpc-tools normally and pnpm grpc:codegen works unchanged.

What lands

• package.json — grpc-tools: "^1.13.0" moves out of devDependencies and into a new optionalDependencies block. The entry in pnpm.onlyBuiltDependencies stays — it controls whether pnpm attempts the postinstall, not whether failure is fatal. Local installs (where TLS works) still run the postinstall and download the binary.
• pnpm-lock.yaml — refreshed; the lockfile reflects the new optional-dep classification. No version changes to anything else.
• .gitea/workflows/ci.yml — revert the workflow-level env: NODE_OPTIONS: --use-system-ca block added in #199. Did not help; left in place it would be a misleading "this is supposed to fix CI TLS" signpost.
• .gitea/workflows/docs-site.yml — same revert.

Notes for the reviewer

• Why optionalDependencies is the right primitive. pnpm 10 documents the contract: a package listed in optionalDependencies is attempted; if the install fails for any reason (platform mismatch, postinstall script error, network failure), the failure is logged and the overall command continues. That maps exactly to what this PR needs: try in CI, fail gracefully, succeed locally.
• Why not remove grpc-tools from pnpm.onlyBuiltDependencies instead. Removing it from the allowlist tells pnpm not to even try the postinstall, which would also fix CI. But it would also break the developer workflow — locally, the protoc binary would never download, and pnpm grpc:codegen would fail. The dev would have to manually trigger the build (pnpm approve-builds then pnpm rebuild grpc-tools), or worse, devs would commit accidental package.json mutations from approve-builds. The optionalDependencies route keeps the local DX identical.
• Why revert the workflow env: blocks. They do not help here, and leaving them in place implies that --use-system-ca is the canonical fix for this class of failure — which it is not, at least not for this runner / this CDN. If a future native dep hits a similar wall and --use-system-ca does fix it for that case, the env var lands in a focused PR with a real validation. Carrying it now as a "maybe useful later" workaround is noise.
• Codegen workflow on developer machines. Unchanged. pnpm install runs the postinstall (TLS validates locally), the protoc binary lands in node_modules/, pnpm grpc:codegen regenerates stubs. The only visible difference is a one-line WARN GET_RESOLVED_FROM_REGISTRY ... if a contributor ever encounters the same TLS failure locally (e.g., on a corporate-proxied machine) — pnpm will mark grpc-tools as failed-optional and the rest of the install proceeds; the dev can then debug their own network without blocking the whole repo.
• Idempotence with CI's --frozen-lockfile. The lockfile change is small (re-classifies grpc-tools from dev to optional) and lands in this PR. After merge, CI runs against the new lockfile; no further coordination needed.

Test plan

• pnpm install locally — clean, grpc-tools postinstall runs successfully (TLS validates), protoc binary present.
• pnpm grpc:codegen — regenerates the TypeScript stubs identically (no diff in apps/portal-bff/src/grpc/gen/).
• pnpm nx run-many -t lint test build -p portal-shell,portal-admin,portal-bff,shared-ui,shared-charts — all five projects green.
• CI green on this PR's first run. The validation that matters: pnpm install --frozen-lockfile completes despite grpc-tools' postinstall failure; ci:check runs to completion.
• Spot-check of post-merge CI runs over the next few days to confirm the warning is recurring (expected) and the install never fails (the contract).

What's next

• If the CI behaviour is what this PR predicts (warning instead of failure), no further action required.
• If optionalDependencies does not work as documented (highly unlikely, but possible if the pnpm version has a regression), the fallback is to drop grpc-tools from pnpm.onlyBuiltDependencies and add a small dev-onboarding note. One-line change away.
• Long-term cleanup: if a future PR migrates the codegen step to a Docker-based tool (buf, system protoc) the optional-dep entry can be removed entirely. Out of scope here.

## Summary The `NODE_OPTIONS=--use-system-ca` workaround merged in #199 did not clear the CI install failure — the runner still rejects the TLS chain to `node-precompiled-binaries.grpc.io`. Either the runner's OS CA bundle is missing the same intermediate Node's bundled set is missing, or `--use-system-ca` does not propagate down to the `node-fetch@2` that `node-pre-gyp` uses. Without runner shell access the exact reason is not worth chasing. Switch angle: **the protoc binary `grpc-tools` downloads is never used in CI**. The generated TypeScript stubs in `apps/portal-bff/src/grpc/gen/` are committed per [ADR-0024](docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md) §"Sub-decision 3 — vendored protos", so CI only needs to type-check them; protoc only runs when a developer regenerates from `apps/portal-bff/src/grpc/proto/apf-ai/*.proto`. This PR moves `grpc-tools` from `devDependencies` to `optionalDependencies`. Per pnpm semantics, when an optional dep's install (including postinstall) fails, pnpm logs a warning and the overall install completes. CI's `pnpm install --frozen-lockfile` therefore succeeds even when the binary cannot be fetched; developer machines (where TLS validates) install grpc-tools normally and `pnpm grpc:codegen` works unchanged. ## What lands - `package.json` — `grpc-tools: "^1.13.0"` moves out of `devDependencies` and into a new `optionalDependencies` block. The entry in `pnpm.onlyBuiltDependencies` stays — it controls whether pnpm *attempts* the postinstall, not whether failure is fatal. Local installs (where TLS works) still run the postinstall and download the binary. - `pnpm-lock.yaml` — refreshed; the lockfile reflects the new optional-dep classification. No version changes to anything else. - `.gitea/workflows/ci.yml` — revert the workflow-level `env: NODE_OPTIONS: --use-system-ca` block added in #199. Did not help; left in place it would be a misleading "this is supposed to fix CI TLS" signpost. - `.gitea/workflows/docs-site.yml` — same revert. ## Notes for the reviewer - **Why `optionalDependencies` is the right primitive.** pnpm 10 documents the contract: a package listed in `optionalDependencies` is *attempted*; if the install fails for any reason (platform mismatch, postinstall script error, network failure), the failure is logged and the overall command continues. That maps exactly to what this PR needs: try in CI, fail gracefully, succeed locally. - **Why not remove `grpc-tools` from `pnpm.onlyBuiltDependencies` instead.** Removing it from the allowlist tells pnpm not to even *try* the postinstall, which would also fix CI. But it would also break the developer workflow — locally, the protoc binary would never download, and `pnpm grpc:codegen` would fail. The dev would have to manually trigger the build (`pnpm approve-builds` then `pnpm rebuild grpc-tools`), or worse, devs would commit accidental `package.json` mutations from `approve-builds`. The `optionalDependencies` route keeps the local DX identical. - **Why revert the workflow `env:` blocks.** They do not help here, and leaving them in place implies that `--use-system-ca` is the canonical fix for this class of failure — which it is *not*, at least not for this runner / this CDN. If a future native dep hits a similar wall and `--use-system-ca` *does* fix it for that case, the env var lands in a focused PR with a real validation. Carrying it now as a "maybe useful later" workaround is noise. - **Codegen workflow on developer machines.** Unchanged. `pnpm install` runs the postinstall (TLS validates locally), the protoc binary lands in `node_modules/`, `pnpm grpc:codegen` regenerates stubs. The only visible difference is a one-line `WARN GET_RESOLVED_FROM_REGISTRY ...` if a contributor ever encounters the same TLS failure locally (e.g., on a corporate-proxied machine) — pnpm will mark grpc-tools as failed-optional and the rest of the install proceeds; the dev can then debug their own network without blocking the whole repo. - **Idempotence with CI's `--frozen-lockfile`.** The lockfile change is small (re-classifies grpc-tools from `dev` to `optional`) and lands in this PR. After merge, CI runs against the new lockfile; no further coordination needed. ## Test plan - [x] `pnpm install` locally — clean, grpc-tools postinstall runs successfully (TLS validates), protoc binary present. - [x] `pnpm grpc:codegen` — regenerates the TypeScript stubs identically (no diff in `apps/portal-bff/src/grpc/gen/`). - [x] `pnpm nx run-many -t lint test build -p portal-shell,portal-admin,portal-bff,shared-ui,shared-charts` — all five projects green. - [ ] **CI green on this PR's first run.** The validation that matters: `pnpm install --frozen-lockfile` completes despite grpc-tools' postinstall failure; `ci:check` runs to completion. - [ ] Spot-check of post-merge CI runs over the next few days to confirm the warning is recurring (expected) and the install never fails (the contract). ## What's next - If the CI behaviour is what this PR predicts (warning instead of failure), no further action required. - If `optionalDependencies` does not work as documented (highly unlikely, but possible if the pnpm version has a regression), the fallback is to drop `grpc-tools` from `pnpm.onlyBuiltDependencies` and add a small dev-onboarding note. One-line change away. - Long-term cleanup: if a future PR migrates the codegen step to a Docker-based tool (`buf`, system protoc) the optional-dep entry can be removed entirely. Out of scope here.

julien added 1 commit 2026-05-20 15:05:59 +02:00

fix(ci): move grpc-tools to optionalDependencies (revert NODE_OPTIONS attempt) ... 204727b1a7

The NODE_OPTIONS=--use-system-ca workaround merged in #199 did not
clear the failure — the same TLS-chain rejection still trips the
runner. Either the runner's OS CA store also lacks the missing
intermediate, or `--use-system-ca` does not propagate down to the
node-fetch@2 used by node-pre-gyp. Without runner shell access the
exact reason is not worth investigating.

Different angle: grpc-tools is never invoked in CI. The protoc
binary it downloads is only used by `pnpm run grpc:codegen`, which
runs on a developer's machine when a proto file changes. 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 — protoc is dead weight there.

Move grpc-tools from devDependencies to optionalDependencies. Per
pnpm semantics, an optional dependency whose install (including
postinstall) fails is logged as a warning and the overall install
continues. On the runner: postinstall still fails on TLS, pnpm
emits a warning, ci:check proceeds. On a developer machine: TLS
validates, postinstall runs, protoc binary lands, `pnpm grpc:codegen`
works exactly as before. No dev-side friction; no workflow env
vars to maintain.

Reverts the workflow `env:` blocks added in #199 — they did not
help and adding noise to the workflow YAML for a non-working
workaround is worse than removing it.

julien merged commit e389567a3c into main 2026-05-20 15:06:27 +02:00

julien deleted branch fix/ci-grpc-tools-optional 2026-05-20 15:06:29 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

adastra-bot (AdAstra Bot) julien (Julien Gautier)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: julien/apf_portal#200