Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions .github/workflows/publish-tech-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,30 @@ jobs:
- name: Checkout code
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6

- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
# ARC runners ship techdocs-cli and mkdocs with these plugins (monta-app/actions-runner).
- name: Check for the runner's TechDocs tools
id: baked
run: |
if command -v techdocs-cli >/dev/null && command -v mkdocs >/dev/null \
&& "$(dirname "$(readlink -f "$(command -v mkdocs)")")/python" -c "import techdocs_core, mkdocs_literate_nav, mermaid2" 2>/dev/null; then
echo "present=true" >> "$GITHUB_OUTPUT"
else
echo "TechDocs tools not on this runner; installing them"
fi

- if: steps.baked.outputs.present != 'true'
uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
- if: steps.baked.outputs.present != 'true'
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: '3.14'

- name: Install techdocs-cli
if: steps.baked.outputs.present != 'true'
run: sudo npm install -g @techdocs/cli

- name: Install mkdocs and mkdocs plugins
if: steps.baked.outputs.present != 'true'
run: python -m pip install mkdocs-techdocs-core==1.* mkdocs-literate-nav mkdocs-mermaid2-plugin

- name: Generate docs site
Expand Down
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
- **Latest SHA**: 84fb68d (check for newer commits)
- **Changes**: new `pnpm-dependency-submission.yml` and `pnpm-dependency-graph` action for pnpm 12 lockfiles

## Recent Changes (2026-10-27)
1. **`publish-tech-docs.yml` uses the runner's TechDocs tools**: the ARC runner image (monta-app/actions-runner) ships `@techdocs/cli` and mkdocs with the techdocs-core, literate-nav and mermaid2 plugins, pinned there by lockfiles. A first step checks that `techdocs-cli` is on PATH and that the Python behind `mkdocs` imports the three plugins, and when it does, setup-node, setup-python and both installs are skipped. Those took 27-46s of a 50-70s job on `arc-arm64-2cpu-4gb` (service-ocpi, service-wallet), on every push to main in 55 calling repos. Public repos (`ubuntu-24.04-arm`) and runners without the tools install them as before, unpinned. The baked versions are bumped in actions-runner, not here.

## Recent Changes (2026-10-23)
1. **`pnpm-dependency-submission.yml` and the `pnpm-dependency-graph` action**: pnpm 12 writes `pnpm-lock.yaml` as two YAML documents (one pinning pnpm itself via `packageManagerDependencies`, then the workspace lockfile), and GitHub's dependency graph reads only the first, so it falls back to each workspace's `package.json`. The SBOM then has only direct dependencies with their specifiers. monorepo-typescript listed 906 packages, 895 as `catalog:…`, against the 2,795 its lockfile resolves. The action reads every document with `yq` (no install), walks each importer's dependencies through `snapshots`, and submits one manifest per workspace named `<importer>/package.json`. Tested on tool-reviews: a single `pnpm-lock.yaml` manifest left GitHub's 30 `package.json` specifiers next to the resolved versions, while manifests named after the `package.json` files replaced them (540 entries, 430 unique packages, all with a license, no specifiers). Scope follows npm: anything a workspace's `dependencies`/`optionalDependencies` reach is `runtime`, the rest `development`. Edges to a package's `peerDependencies` (pnpm lists resolved peers, optional ones included, under the snapshot's dependencies) don't decide a scope, which kept vitest and `@types/react` from turning runtime through `@testing-library/jest-dom` and `posthog-js`; a package reachable only through a peer takes the scope of what reaches it. Workspace-level scoping (a config package linked only as a devDependency) was tried and dropped: the lockfile can't tell such a package from an app that a dev tool links to (`apps/storybook` dev-links `apps/hub`). Unittests: `python3 .github/actions/pnpm-dependency-graph/test_pnpm_dependency_graph.py`.
1. **`GHL_USERNAME`/`GHL_PASSWORD` optional on `gradle-dependency-submission.yml`**: only builds that resolve packages from GitHub Packages need them, and the Kotlin repos with their own CI that are next to call the workflow include public libraries and tools that don't. A required secret the caller can't see would leave those repos unable to call it. `sonar-cloud.yml` still requires them for its own build and passes them on.
Expand Down
3 changes: 1 addition & 2 deletions docs/workflow-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -858,8 +858,7 @@ jobs:
**Purpose:** Publishes technical documentation to Backstage via AWS S3.

### What it does:
1. Sets up Node.js and Python environments
2. Installs techdocs-cli and mkdocs
1. Uses the techdocs-cli and mkdocs (with the techdocs-core, literate-nav and mermaid2 plugins) baked into ARC runners; on other runners, sets up Node.js and Python and installs them
3. Generates documentation site
4. Publishes to S3 bucket for Backstage

Expand Down