Repository turn report

Fix docs mirroring to dirtydishes.github.io

The docs publishing workflow now mirrors the generated static docs payload into the actual GitHub Pages site repository, dirtydishes/dirtydishes.github.io, under the islandflow/docs/ path.

May 31, 2026Beads: islandflow-m3dWorkflow: .github/workflows/docs-pages.yml

Summary

Repaired the Pages publishing target so repository docs are copied to dirtydishes.github.io/islandflow/docs/ instead of attempting to force-push a gh-pages branch back to the mirrored islandflow repository.

Changes Made

Changed the workflow permission from write to read for the source repository, because publishing now happens through the target Pages checkout.
Added explicit Pages target settings for dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.
Added a target-repository checkout that uses secrets.DOCS_PAGES_TOKEN.
Mirrors the static payload into pages/islandflow/, which serves the docs at /islandflow/docs/.
Commits and pushes only when the generated mirror content actually changed.
Tightened the docs index generator so regenerated HTML does not introduce trailing whitespace.
Regenerated docs/index.html so the docs index reflects the current repository docs set.

Context

The previous workflow built a valid static payload, but its publish step initialized a temporary Git repository and pushed gh-pages to github.com/$GITHUB_REPOSITORY. That targets the dirtydishes/islandflow mirror, not the user Pages repository that serves dirtydishes.github.io.

Cross-repository publishing cannot rely on the default GITHUB_TOKEN from the source workflow. The fixed workflow uses a dedicated secret token for the Pages site checkout and push.

Important Implementation Details

The public URL remains https://dirtydishes.github.io/islandflow/docs/.
The target repository branch is master, matching the current remote state of dirtydishes/dirtydishes.github.io.
The workflow removes and replaces only the islandflow/ subtree in the Pages repository, leaving any other site content alone.
The workflow requires a GitHub Actions secret named DOCS_PAGES_TOKEN with permission to read and write dirtydishes/dirtydishes.github.io.

Relevant Diff Snippets

Rendered with @pierre/diffs/ssr using server-side generated markup so this report is readable offline without loading remote JavaScript.

.github/workflows/docs-pages.yml

-13+32

10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
3 unmodified lines
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
10 unmodified lines
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

      - name: Prepare static site payload
        run: |
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

      - name: Publish to gh-pages branch
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          rm -rf .gh-pages-tmp
          mkdir .gh-pages-tmp
          cp -R site/. .gh-pages-tmp/
          cd .gh-pages-tmp

          git init
          git checkout -b gh-pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "publish docs from ${GITHUB_SHA}"

          git push --force "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages:gh-pages
10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
26
27
28
29
3 unmodified lines
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
10 unmodified lines
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      PAGES_REPOSITORY: dirtydishes/dirtydishes.github.io
      PAGES_BRANCH: master
      PAGES_PREFIX: islandflow
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

      - name: Prepare static site payload
        run: |
          rm -rf site
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

      - name: Checkout GitHub Pages site
        uses: actions/checkout@v5
        with:
          repository: ${{ env.PAGES_REPOSITORY }}
          ref: ${{ env.PAGES_BRANCH }}
          token: ${{ secrets.DOCS_PAGES_TOKEN }}
          path: pages
          fetch-depth: 0

      - name: Mirror docs into Pages site
        run: |
          set -euo pipefail
          rm -rf "pages/${PAGES_PREFIX}"
          mkdir -p "pages/${PAGES_PREFIX}"
          cp -R site/. "pages/${PAGES_PREFIX}/"
          touch pages/.nojekyll

      - name: Commit and push Pages mirror
        run: |
          set -euo pipefail
          cd pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add "${PAGES_PREFIX}" .nojekyll

          if git diff --cached --quiet; then
            echo "No docs changes to publish."
            exit 0
          fi

          git commit -m "publish islandflow docs from ${GITHUB_SHA}"
          git push origin "HEAD:${PAGES_BRANCH}"

scripts/generate-docs-index.mjs

-8+4

128 unmodified lines
129
130
131
132
133
134
135
136
2 unmodified lines
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `
            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>
          `;
        })
        .join("\n");

      return `
        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>
      `;
    })
    .join("\n");

128 unmodified lines
129
130
131
132
133
134
135
2 unmodified lines
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>`;
        })
        .join("\n");

      return `        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>`;
    })
    .join("\n");

Expected Impact for End-Users

Once the workflow runs on GitHub with DOCS_PAGES_TOKEN configured, readers should be able to browse the Islandflow docs at dirtydishes.github.io/islandflow/docs/ from the actual Pages site instead of depending on a missing or unconfigured project gh-pages branch.

Validation

Passed: Ran node scripts/generate-docs-index.mjs; it generated docs/index.html with 64 entries.
Passed: Ran node --check scripts/generate-docs-index.mjs.
Passed: Parsed .github/workflows/docs-pages.yml with Ruby YAML.
Passed: Ran git diff --check after tightening the generated index output.
Not completed: bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.

Issues, Limitations, and Mitigations

The workflow will fail until DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.
This was validated locally for generation and YAML syntax, but the cross-repository push itself can only be fully verified by a GitHub Actions run.
The docs index includes file modified timestamps, so regenerating it can change ordering and metadata when local mtimes differ from the committed version.

Follow-up Work

islandflow-8a6: Add or verify DOCS_PAGES_TOKEN in the GitHub mirror repository secrets, then manually run the Publish Docs workflow after this branch lands on the mirrored main.
Consider replacing timestamp-based docs index ordering with commit dates or filenames so generated output is less sensitive to local filesystem mtimes.