Skip to content

Fix gen-docs CI: run protoc-gen-doc on host instead of stale container#274

Merged
follesoe merged 1 commit into
masterfrom
fix-gen-docs-ci
Jun 24, 2026
Merged

Fix gen-docs CI: run protoc-gen-doc on host instead of stale container#274
follesoe merged 1 commit into
masterfrom
fix-gen-docs-ci

Conversation

@follesoe

Copy link
Copy Markdown
Member

Fixes #271

Problem

The Generate documentation workflow fails on every push to master, at the Checkout source step — before any docs are generated. It runs inside container: pseudomuto/protoc-gen-doc:1.5.1, whose ~4-year-old Alpine/musl base can no longer host the Node binary GitHub injects to run JS actions (actions/checkout). With Node 20 being deprecated, the runner now injects Node 24, which needs pthread_getname_np (musl ≥ 1.2.3):

Error relocating /__e/node24_alpine/bin/node: pthread_getname_np: symbol not found

Bumping actions/checkout doesn't help — the failing binary is the runtime the runner injects, not the action's code.

Fix (Option 1 from the issue)

Drop the container and install the toolchain directly on ubuntu-latest:

  • protoc via apt (protobuf-compiler)
  • protoc-gen-doc via go install …@v1.5.1 (Go is preinstalled on runners)
  • add $(go env GOPATH)/bin to $GITHUB_PATH so protoc finds the plugin

protoc-gen-doc is pinned to v1.5.1 — the same version as the old container — so the generated HTML is identical. The doc-generation command, triggers, secrets, and Azure upload (container: protocoldefinitions, artifact docs) are unchanged.

Also removed the leftover debug steps (Print path, List files, List doc files).

Why not the alternatives

  • Buf migration (Option 2): best long-term, but a real migration (adds buf.yaml/buf.gen.yaml) — out of scope for a CI hotfix.
  • Community rebuilt image (Option 3): trades one stale dependency for a less-trusted one.
  • ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION stopgap: Node 20 is on a removal path; only buys time.

Validation

  • Workflow YAML parses cleanly.
  • Full verification is the workflow run itself (it only triggers on push to master), so it will be exercised once merged.

🤖 Generated with Claude Code

The gen-docs workflow ran inside pseudomuto/protoc-gen-doc:1.5.1, whose
~4-year-old Alpine/musl base can no longer host the Node 24 binary the
runner injects for JS actions (actions/checkout), so the job died at
checkout with:

  Error relocating .../node24_alpine/bin/node: pthread_getname_np: symbol not found

Drop the container and install protoc + protoc-gen-doc directly on
ubuntu-latest (Option 1 from #271). protoc-gen-doc is pinned to v1.5.1 to
match the previous container, so the generated HTML is identical. Go's
bin dir is added to PATH so protoc can find the plugin.

Fixes #271

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@follesoe follesoe added bug Something isn't working documentation Improvements or additions to documentation automation Issues related to build automation labels Jun 24, 2026
@follesoe follesoe self-assigned this Jun 24, 2026
@follesoe follesoe requested a review from jp-pino June 24, 2026 13:00
@follesoe follesoe merged commit dfffd4a into master Jun 24, 2026
4 checks passed
@follesoe follesoe deleted the fix-gen-docs-ci branch June 24, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automation Issues related to build automation bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

gen-docs CI fails: Node 24 injected into old protoc-gen-doc container (musl too old)

1 participant