Build in GitHub Actions

A complete workflow that checks, prefetches on a cache miss, builds, uploads dist/ and hands off to your host.

This page gives you one workflow file that validates your docs on every pull request and builds the deployable site. Copy it, set two repository variables, and replace the deploy step with your host’s upload command.

It follows the same conventions as the workflow that builds this site: Node 22, no pipes, no publish step, and a CLI built from source. It is a general-purpose pipeline, not a copy of that workflow. The reasoning behind each step is on Offline builds in CI.

Getting the Reed CLI

Reed is not published to npm yet. There is no package to install. In CI you build the CLI from source, the same way this site’s own workflow does:

Check out the Reed source repository next to your docs.
Install its dependencies and build it.
Run node <reed-source>/packages/cli/dist/bin.js.

The workflow reads two repository variables and one optional secret:

Name	Kind	Value
`REED_REPO`	variable	The Reed source repository, as `owner/name`. Required.
`REED_REF`	variable	A commit SHA, tag or branch of that repository. Pin a SHA.
`REED_REPO_TOKEN`	secret	A read token, only if the source repository is private.

If REED_REPO is unset, the job fails on its first step and says why. It never reports a green build it did not run.

The workflow

Save this as .github/workflows/docs.yml:

1
name: docs
2

3
on:
4
  pull_request:
5
  push:
6
    branches: [main]
7

8
permissions:
9
  contents: read
10

11
env:
12
  # Both caches that `reed prefetch` fills live inside the workspace so actions/cache can
13
  # save and restore them. REED_COREPACK_HOME points Reed's Corepack calls at the same
14
  # directory as COREPACK_HOME.
15
  REED_STORE_DIR: ${{ github.workspace }}/.ci-cache/reed-pnpm-store
16
  COREPACK_HOME: ${{ github.workspace }}/.ci-cache/corepack
17
  REED_COREPACK_HOME: ${{ github.workspace }}/.ci-cache/corepack
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      - name: Require a Reed source
24
        if: ${{ vars.REED_REPO == '' }}
25
        run: |
26
          echo "error: set the repository variable REED_REPO to the Reed source (owner/name)." >&2
27
          exit 1
28

29
      - name: Check out docs
30
        uses: actions/checkout@v4
31

32
      # Node 22, not "latest": prefetch and build shell out to Corepack, and Node 25 and
33
      # newer no longer bundle it.
34
      - name: Set up Node
35
        uses: actions/setup-node@v4
36
        with:
37
          node-version: "22"
38

39
      - name: Check out Reed source
40
        uses: actions/checkout@v4
41
        with:
42
          repository: ${{ vars.REED_REPO }}
43
          ref: ${{ vars.REED_REF }}
44
          token: ${{ secrets.REED_REPO_TOKEN || github.token }}
45
          path: .ci-reed
46

47
      # A throwaway COREPACK_HOME here keeps building Reed itself from warming the cache
48
      # this job is about to restore and measure.
49
      - name: Build the Reed CLI
50
        id: reed
51
        env:
52
          COREPACK_HOME: ${{ runner.temp }}/corepack-reed-source
53
        run: |
54
          set -euo pipefail
55
          cd .ci-reed
56
          corepack enable pnpm
57
          pnpm install --frozen-lockfile
58
          pnpm run build
59
          test -f packages/cli/dist/bin.js
60
          echo "REED_BIN=$PWD/packages/cli/dist/bin.js" >> "$GITHUB_ENV"
61
          echo "rev=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
62

63
      # One step, both caches. The key is the Reed revision: what prefetch stores depends
64
      # on Reed's pins and the runner, not on your content.
65
      - name: Restore Reed caches (store + Corepack)
66
        id: reed-cache
67
        uses: actions/cache@v4
68
        with:
69
          path: |
70
            ${{ env.REED_STORE_DIR }}
71
            ${{ env.COREPACK_HOME }}
72
          key: reed-${{ runner.os }}-${{ runner.arch }}-${{ steps.reed.outputs.rev }}
73
          restore-keys: |
74
            reed-${{ runner.os }}-${{ runner.arch }}-
75

76
      # Offline, no prerequisites. Fails the job on any error-level diagnostic.
77
      - name: reed check
78
        run: node "$REED_BIN" check
79

80
      # The only Reed command allowed network access. Skipped on an exact cache hit.
81
      - name: reed prefetch (cache miss only)
82
        if: steps.reed-cache.outputs.cache-hit != 'true'
83
        run: node "$REED_BIN" prefetch
84

85
      - name: reed build
86
        run: node "$REED_BIN" build --out dist
87

88
      - name: Upload the built site
89
        uses: actions/upload-artifact@v4
90
        with:
91
          name: docs-site
92
          path: dist/
93
          if-no-files-found: error
94

95
  deploy:
96
    needs: build
97
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
98
    runs-on: ubuntu-latest
99
    steps:
100
      - name: Download the built site
101
        uses: actions/download-artifact@v4
102
        with:
103
          name: docs-site
104
          path: dist
105

106
      # REPLACE ME: put your host's upload command in `run`, then delete the `if` line.
107
      # Until then the step is skipped, and the run shows it as skipped rather than as a
108
      # deploy: nothing is uploaded.
109
      - name: Deploy (replace me)
110
        if: ${{ false }}
111
        run: |
112
          echo "Upload dist/ to your host here."

What each part is doing

Both caches, one step. reed prefetch fills two directories: the dependency store at REED_STORE_DIR, and Corepack’s cache of the pinned package-manager binary at COREPACK_HOME. Restore only one and the build still passes on a hosted runner. It just fetches the other one over the network, where you cannot see it.

Prefetch runs only on a miss. cache-hit is true only when the exact key matched. A partial match through restore-keys reports a miss, so prefetch runs, refreshes the store, and the cache is saved under the new key at the end of the job.

The key follows Reed, not your docs. Prefetch rejects --dir because its caches are machine-wide. One prefetch serves every project on the runner, so hashing docs.json into the key only adds cache misses. The Reed revision and the runner’s OS and architecture are what actually change the contents.

A stale cache fails loudly. If a restored store was prefetched for a different Reed pin, reed build stops with a diagnostic telling you to run reed prefetch. It does not fall back to the network.

No pipes. Every Reed command runs on its own line. Piping one into tee makes the step’s exit status the status of tee, and a failed build reports success. GitHub’s default bash shell does not set pipefail, so this matters here. If you need a log file, redirect with > instead.

Stricter checks

reed check fails only on errors. To fail pull requests on warnings as well, pass both strict flags:

1
node "$REED_BIN" check --strict-components --strict-tokens

--strict-components escalates the DS-D* design warnings. --strict-tokens escalates every other warning. See Diagnostics.

Deploying

The deploy job runs only on a push to main, and only after build succeeds. It downloads the same dist/ that was built and checked. Nothing is rebuilt.

What goes in the deploy step is up to your host. Reed has no deploy command and no hosted runtime. Three things to get right:

Credentials. Put your host’s token in a repository secret and reference it only in the deploy step. The build job never needs it.
The mount path. If docs.json sets base, the files have to be served from a directory matching it. Stage the tree before uploading. See Deploy.
_headers. It belongs at the root of the served tree, even when the pages sit under a mount path. See Response headers.

After the upload, fetch a page from the live origin and look for a string from this build. A zero exit code from the upload is not proof the new site is live.

Proving the build is offline

If your runner allows unprivileged user namespaces, you can run the build step with no network at all. A cache that was missing a directory then fails here instead of passing quietly:

1
unshare --user --map-root-user --net -- \
2
  bash -c 'ip link set lo up 2>/dev/null || true; exec node "$REED_BIN" build --out dist'

reed check can run the same way with no prior step. It never touches the network.

Other platforms

Prefetch covers exactly the platform, architecture and libc it ran on. If you add an Alpine or macOS job, give it its own cache. The runner.os and runner.arch parts of the key already keep hosted Linux, macOS and ARM runners apart. They do not tell glibc from musl, so an Alpine container job needs its own key prefix.

For the same pipeline on GitLab, see Build in GitLab CI.