actor-ts/.github/workflows/docs.yml at develop · pathosDev/actor-ts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# Build + deploy the Astro Starlight documentation site under `docs/`
# to GitHub Pages.
#
# Strategy: build + deploy on pushes to `main`.  `main` only moves when a
# release is cut (see AGENTS.md → Release strategy), so the published docs
# still track released versions — without the `release: [published]`
# trigger, whose runs execute on the TAG ref and are rejected by the
# `github-pages` environment protection rules (only `main` may deploy;
# this is how the v0.11.0 docs deploy failed).  Not built on develop
# pushes/PRs (the build is slow).  Build output is never committed; Pages
# consumes the workflow artifact directly via `actions/deploy-pages`.
#
# **Prerequisite — manual one-time setup**:
#   Settings → Pages → Source: GitHub Actions
# (Without that, the deploy step fails with "Pages site not found".)
#
# **Permissions**: the deploy job needs `pages: write` + `id-token:
# write` to publish the artifact via OIDC.  Workflow-level defaults
# leave other scopes read-only.
name: docs

on:
  # Fire on pushes to `main` — which happen only at release time — so the
  # docs deploy in lockstep with the npm publish and run on a ref the
  # `github-pages` environment protection accepts.  Docs are deliberately
  # NOT built on `develop` pushes/PRs — the build is slow (TypeDoc +
  # Astro + headless-Chromium Mermaid SSR).  Use workflow_dispatch for an
  # out-of-band rebuild.
  push:
    branches: [main]
  workflow_dispatch:

# Avoid in-flight workflow conflicts: cancel any older run on the same
# branch if a new push lands.  Pages itself only accepts one deploy
# at a time anyway.
concurrency:
  group: "pages-${{ github.ref }}"
  cancel-in-progress: false

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          # Starlight's `lastUpdated` feature reads Git history to show
          # the per-page last-modified date.  Full history (`0`) lets
          # it work; shallow checkout makes every page report "now".
          fetch-depth: 0

      # `bun install` is fast and reads `docs/bun.lock`, but `bun run build`
      # ultimately invokes `astro build` whose shebang spawns Node — so the
      # system Node has to satisfy Astro's minimum (>= 22.12 for Astro 7).
      # We install the repo's `engines` floor.
      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '24'

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      # TypeDoc compiles `../src/` to extract JSDoc — but `src/` imports
      # framework peer-deps (`ts-pattern`, `@types/node`, etc.) that live
      # under the **repo root** `node_modules/`, not under `docs/`.  We
      # therefore install root deps first, then the docs-specific deps.
      # Without this, TypeDoc errors out with TS2307 ("cannot find
      # module 'ts-pattern'") + TS2503 ("cannot find namespace
      # 'NodeJS'") on every source file.
      #
      # Both installs are `--frozen-lockfile`: this workflow used to install
      # whatever `package.json` resolved to, so a lockfile that had drifted from
      # its manifest (Dependabot never regenerates `bun.lock`) built green here
      # against a dependency set nobody had recorded — until a bump resolved to
      # something that did not work and the release docs deploy broke (#473).
      - name: Install root dependencies (for TypeDoc to resolve src/ imports)
        run: bun install --frozen-lockfile

      - name: Install docs dependencies
        working-directory: docs
        run: bun install --frozen-lockfile

      # rehype-mermaid renders ```mermaid``` blocks at build time by
      # driving headless Chromium via Playwright.  The npm package
      # ships only the JS bindings; the actual browser binary has to
      # be fetched separately.  `--with-deps` pulls the Linux system
      # libs Chromium needs on the GH Actions Ubuntu runner.
      - name: Install Playwright browsers (for Mermaid SSR)
        working-directory: docs
        run: bunx playwright install --with-deps chromium

      - name: Build site (includes TypeDoc API generation)
        working-directory: docs
        run: bun run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: docs/dist

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5