ci: publish TypeDoc to packages.electronjs.org on version tags

[claude]

Requested by Erick Zhao · Slack thread

• I have read the contribution documentation for this project.
• I agree to follow the code of conduct that this project follows, as appropriate.
• The changes are appropriately documented (if applicable).
• The changes have sufficient test coverage (if applicable). (CI-only change; no tests.)
• The testsuite passes successfully on my local machine (if applicable). (yarn docs builds with 0 errors / 0 warnings locally; oxfmt --check and zizmor are clean on the new workflow.)

Summarize your changes:

Before: The TypeDoc API reference is only published to js.electronforge.io, via gh-pages.yml committing api-docs/ to the gh-pages branch, and only on v7.** tags. The v8 alpha tags (v8.0.0-alpha.N) never publish anything, and Forge has no presence on packages.electronjs.org even though the rest of the @electron/* toolchain (packager, get, asar, rebuild, osx-sign, notarize, ...) publishes there and typedoc.jsonc already cross-links to those pages.

After: Every version tag (v[0-9]+.[0-9]+.[0-9]+*, so prereleases included) runs a new docs.yml workflow that builds yarn docs and uploads api-docs/ to packages.electronjs.org/forge/<tag>/ over Azure OIDC, exactly the way @electron/packager and the other @electron/* packages do it. The site title is now "Electron Forge" (was the TypeDoc default "Documentation"), and the one remaining yarn docs warning is fixed by adding the @electron/packager Options.electronVersion entry to externalSymbolLinkMappings, so the docs build is now 0 errors / 0 warnings.

How: .github/workflows/docs.yml is a near-verbatim copy of electron/packager's docs.yml: workflow-level id-token: write + contents: read, job environment: docs-publish, the actions/checkout / actions/setup-node SHAs Forge already pins elsewhere (with persist-credentials: false, node-version-file: .nvmrc, and package-manager-cache: false so a publishing job never restores a cache), yarn install --immutable, yarn docs, then azure/login + azure/cli at the same SHAs packager uses. Differences from packager: the upload script reads the storage account and tag from env: instead of inline ${{ }} (keeps zizmor's template-injection audit clean without an ignore comment), and the forge path segment is hardcoded rather than derived from github.event.repository.name. gh-pages.yml is intentionally left untouched (see open questions).

Depends on (electron/infra#349):

• Add "forge" to allowed_repos in terraform/global/oidc/ecosystem-packages-upload.tf. That module provisions the docs-publish environment with its v* tag-only deployment policy, the Azure federated credential for repo:electron/forge:environment:docs-publish, and scopes the AZURE_OIDC_CLIENT_ID / AZURE_OIDC_TENANT_ID / AZURE_OIDC_SUBSCRIPTION_ID / AZURE_ECOSYSTEM_PACKAGES_STORAGE_ACCOUNT_NAME org secrets to this repo. Until that lands, the workflow will fail at the environment / Azure login step (deep-link uploads need nothing else).
• Fix the packages-redirector Cloudflare Worker so /forge/ and /forge/latest resolve the latest version from @electron-forge/core on npm. Today it falls back to https://registry.npmjs.org/@electron/<name>/latest, and @electron/forge does not exist, so https://packages.electronjs.org/forge/ currently 302s to /forge/vnull/index.html.

Open questions:

• Should we retire gh-pages.yml / js.electronforge.io in favour of a redirect to packages.electronjs.org/forge/? This PR leaves the existing v7 publish in place so nothing regresses while we decide. Note the new TypeDoc slugs are _electron-forge_* (hyphen) while the old js.electronforge.io URLs used _electron_forge_*, so any redirect would need to account for that, and the ~45 API links in docs/ should be repointed as a follow-up.
• The infra module also adds a "Version Tag Protection" ruleset that only the ecosystem publisher GitHub App can bypass. Forge's release.yml creates the vX tag via gh release create with a secret-service App token. We need to confirm that token belongs to the same App the ruleset allows, otherwise tag creation from the release workflow will be blocked once forge is added to allowed_repos.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P4HRbe7XtfgT6eVQZbjcUb

---

Generated by Claude Code